Authenticate using 2-legged OAuth with auth manager

To let your agents authenticate to external tools like ServiceNow or Salesforce using their own authority, configure outbound authentication using 2-legged OAuth (Client Credentials) auth providers in Agent Identity auth manager.

2-legged OAuth auth providers manage credentials and tokens for you. This removes the need to write custom code to handle authentication flows.

2-legged OAuth workflow

2-legged OAuth auth providers use the agent's identity and don't require user consent. Google manages the storage of the client credentials. When you use the Agent Development Kit (ADK), it automatically retrieves and injects the resulting access tokens into the tool invocation headers.

Before you begin

Verify that you have chosen the correct authentication method .
Enable the Agent Identity Connector API.

Roles required to enable APIs

To enable APIs, you need the Service Usage Admin IAM role ( roles/serviceusage.serviceUsageAdmin ), which contains the serviceusage.services.enable permission. Learn how to grant roles .

Enable the API
Create and deploy an agent .
Obtain the client IDand client secretfrom the third-party application that you want to connect to.
Verify that you have the roles required to complete this task .

Required roles

To get the permissions that you need to create and use a 2-legged Agent Identity auth provider, ask your administrator to grant you the following IAM roles on the project:

To create auth providers:
- IAM Connector Admin ( roles/iamconnectors.admin )
- IAM Connector Editor ( roles/iamconnectors.editor )
To use auth providers:
- IAM Connector User ( roles/iamconnectors.user )
- Agent Default Access ( roles/aiplatform.agentDefaultAccess )
- Agent Context Editor ( roles/aiplatform.agentContextEditor )
- Vertex AI User ( roles/aiplatform.user )
- Service Usage Consumer ( roles/serviceusage.serviceUsageConsumer )

For more information about granting roles, see Manage access to projects, folders, and organizations .

These predefined roles contain the permissions required to create and use a 2-legged Agent Identity auth provider. To see the exact permissions that are required, expand the Required permissionssection:

Required permissions

The following permissions are required to create and use a 2-legged Agent Identity auth provider:

To create auth providers: iamconnectors.connectors.create
To use auth providers:
- iamconnectors.connectors.retrieveCredentials
- aiplatform.endpoints.predict
- aiplatform.sessions.create

You might also be able to get these permissions with custom roles or other predefined roles .

Create a 2-legged auth provider

Create an auth provider to define the configuration and credentials for third-party applications.

To create a 2-legged auth provider, use the Google Cloud console or the Google Cloud CLI.

Console

In the Google Cloud console, go to the Agent Registry page.
Go to Agent Registry
Click the name of the agent that you want to create an auth provider for.
Click Identity .
In the Auth Providers section, click Add auth provider .
In the Add auth provider pane, enter a name and description.

The name can contain only lowercase letters, numbers, or hyphens, cannot end with a hyphen, and must start with a lowercase letter.
From the OAuth Type list, select OAuth (2 legged) .
Click Create and continue .
To grant your agent identity permission to use the auth provider, click Grant access .
This automatically assigns the Connector User ( roles/iamconnectors.user ) role to the agent identity on the auth provider resource.
In the Auth provider credentials section, enter the following information:
- Client ID
- Client Secret
- Token URL
Click Add provider config .

The newly created auth provider appears in the Auth Providers list.

Google Cloud CLI

Create the auth provider:

gcloud  
alpha  
agent-identity  
connectors  
create  
  AUTH_PROVIDER_NAME 
 
  
 \ 
  
--location = 
 "  LOCATION 
 
" 
  
 \ 
  
--two-legged-oauth-client-id = 
 "  CLIENT_ID 
 
" 
  
 \ 
  
--two-legged-oauth-client-secret = 
 "  CLIENT_SECRET 
 
" 
  
 \ 
  
--two-legged-oauth-token-endpoint = 
 "  TOKEN_ENDPOINT 
 
"

To grant your agent identity permission to use auth providers, update the IAM allow policy for either the project or the specific auth provider, and grant the Connector User ( roles/iamconnectors.user ) role to the agent principal.

Agent Identity is based on the industry-standard SPIFFE ID format. In IAM allow policies, agent identities are referred to using principal identifiers .

Project-level (gcloud)

Granting the role at the project level allows the agent to use any auth provider in that project.

To grant a single agent access to auth providers in a project, run the following command:

gcloud  
projects  
add-iam-policy-binding  
  PROJECT_ID 
 
  
 \ 
  
--role = 
 'roles/iamconnectors.user' 
  
 \ 
  
--member = 
 "principal://agents.global.org-  ORGANIZATION_ID 
 
.system.id.goog/resources/aiplatform/projects/  PROJECT_NUMBER 
 
/locations/  LOCATION 
 
/reasoningEngines/  ENGINE_ID 
 
"

To grant all agents in a project access to auth providers, run the following command:

gcloud  
projects  
add-iam-policy-binding  
  PROJECT_ID 
 
  
 \ 
  
--role = 
 'roles/iamconnectors.user' 
  
 \ 
  
--member = 
 "principalSet://agents.global.org-  ORGANIZATION_ID 
 
.system.id.goog/attribute.platformContainer/aiplatform/projects/  PROJECT_NUMBER 
 
"

Connector-level (curl)

To grant a single agent access to a specific auth provider, use the setIamPolicy API. This command overwrites any existing allow policy on the resource.

curl  
-X  
POST  
 \ 
  
-H  
 "Authorization: Bearer 
 $( 
gcloud  
auth  
print-access-token ) 
 " 
  
 \ 
  
-H  
 "Content-Type: application/json" 
  
 \ 
  
-d  
 '{ 
 "policy": { 
 "bindings": [ 
 { 
 "role": "roles/iamconnectors.user", 
 "members": ["principal://agents.global.org-  ORGANIZATION_ID 
 
.system.id.goog/resources/aiplatform/projects/  PROJECT_NUMBER 
 
/locations/  LOCATION 
 
/reasoningEngines/  ENGINE_ID 
 
"] 
 } 
 ] 
 } 
 }' 
  
 \ 
  
 "https://iamconnectors.googleapis.com/v1alpha/projects/  PROJECT_ID 
 
/locations/  LOCATION 
 
/connectors/  AUTH_PROVIDER_NAME 
 
:setIamPolicy"

Replace the following:

PROJECT_ID : Your Google Cloud project ID.
AUTH_PROVIDER_NAME : The name of the auth provider.
ORGANIZATION_ID : Your Google Cloud organization ID.
PROJECT_NUMBER : Your Google Cloud project number.
LOCATION : The location for your agent (for example, us-central1 ).
ENGINE_ID : The ID of your reasoning engine.

Authenticate in your agent code

To authenticate your agent, you can use the ADK.

ADK

Reference the auth provider in your agent's code by using the MCP toolset in the ADK.

 from 
  
 google.adk.agents.llm_agent 
  
 import 
 LlmAgent 
 from 
  
 google.adk.auth.credential_manager 
  
 import 
 CredentialManager 
 from 
  
 google.adk.integrations.agent_identity 
  
 import 
 GcpAuthProvider 
 , 
 GcpAuthProviderScheme 
 from 
  
 google.adk.tools.mcp_tool.mcp_session_manager 
  
 import 
 StreamableHTTPConnectionParams 
 from 
  
 google.adk.tools.mcp_tool.mcp_toolset 
  
 import 
 McpToolset 
 from 
  
 google.adk.auth.auth_tool 
  
 import 
 AuthConfig 
 # Register the Google Cloud Auth Provider so the CredentialManager can use it. 
 CredentialManager 
 . 
 register_auth_provider 
 ( 
 GcpAuthProvider 
 ()) 
 # Create the Google Cloud Auth Provider scheme using the auth provider's full resource name. 
 auth_scheme 
 = 
 GcpAuthProviderScheme 
 ( 
 name 
 = 
 "projects/  PROJECT_ID 
 
/locations/  LOCATION 
 
/connectors/  AUTH_PROVIDER_NAME 
 
" 
 ) 
 # Configure an MCP tool with the authentication scheme. 
 toolset 
 = 
 McpToolset 
 ( 
 connection_params 
 = 
 StreamableHTTPConnectionParams 
 ( 
 url 
 = 
 "https://YOUR_MCP_SERVER_URL" 
 ), 
 auth_scheme 
 = 
 auth_scheme 
 , 
 ) 
 # Initialize the agent with the authenticated tools. 
 agent 
 = 
 LlmAgent 
 ( 
 name 
 = 
 "YOUR_AGENT_NAME" 
 , 
 model 
 = 
 "gemini-2.0-flash" 
 , 
 instruction 
 = 
 "YOUR_AGENT_INSTRUCTIONS" 
 , 
 tools 
 = 
 [ 
 toolset 
 ], 
 )

ADK

Reference the auth provider in your agent's code using an authenticated function tool in the ADK.

 import 
  
 httpx 
 from 
  
 google.adk.agents.llm_agent 
  
 import 
 LlmAgent 
 from 
  
 google.adk.auth.credential_manager 
  
 import 
 CredentialManager 
 from 
  
 google.adk.integrations.agent_identity 
  
 import 
 GcpAuthProvider 
 from 
  
 google.adk.integrations.agent_identity 
  
 import 
 GcpAuthProviderScheme 
 from 
  
 google.adk.apps 
  
 import 
 App 
 from 
  
 google.adk.auth.auth_credential 
  
 import 
 AuthCredential 
 from 
  
 google.adk.auth.auth_tool 
  
 import 
 AuthConfig 
 from 
  
 google.adk.tools.authenticated_function_tool 
  
 import 
 AuthenticatedFunctionTool 
 from 
  
 vertexai 
  
 import 
 agent_engines 
 # First, register Google Cloud auth provider 
 CredentialManager 
 . 
 register_auth_provider 
 ( 
 GcpAuthProvider 
 ()) 
 # Create Auth Config 
 spotify_auth_config 
 = 
 AuthConfig 
 ( 
 auth_scheme 
 = 
 GcpAuthProviderScheme 
 ( 
 name 
 = 
 "projects/PROJECT_ID/locations/LOCATION/connectors/AUTH_PROVIDER_NAME" 
 ) 
 ) 
 # Use the Auth Config in Authenticated Function Tool 
 spotify_search_track_tool 
 = 
 AuthenticatedFunctionTool 
 ( 
 func 
 = 
 spotify_search_track 
 , 
 auth_config 
 = 
 spotify_auth_config 
 ) 
 # Sample function tool 
 async 
 def 
  
 spotify_search_track 
 ( 
 credential 
 : 
 AuthCredential 
 , 
 query 
 : 
 str 
 ) 
 -> 
 str 
 | 
 list 
 : 
 token 
 = 
 None 
 if 
 credential 
 . 
 http 
 and 
 credential 
 . 
 http 
 . 
 credentials 
 : 
 token 
 = 
 credential 
 . 
 http 
 . 
 credentials 
 . 
 token 
 if 
 not 
 token 
 : 
 return 
 "Error: No authentication token available." 
 async 
 with 
 httpx 
 . 
 AsyncClient 
 () 
 as 
 client 
 : 
 response 
 = 
 await 
 client 
 . 
  get 
 
 ( 
 "https://api.spotify.com/v1/search" 
 , 
 headers 
 = 
 { 
 "Authorization" 
 : 
 f 
 "Bearer 
 { 
 token 
 } 
 " 
 }, 
 params 
 = 
 { 
 "q" 
 : 
 query 
 , 
 "type" 
 : 
 "track" 
 , 
 "limit" 
 : 
 1 
 }, 
 ) 
 # Add your own logic here 
 agent 
 = 
 LlmAgent 
 ( 
 name 
 = 
 "YOUR_AGENT_NAME" 
 , 
 model 
 = 
 "YOUR_MODEL_NAME" 
 , 
 instruction 
 = 
 "YOUR_AGENT_INSTRUCTIONS" 
 , 
 tools 
 = 
 [ 
 spotify_search_track_tool 
 ], 
 ) 
 app 
 = 
 App 
 ( 
 name 
 = 
 "YOUR_APP_NAME" 
 , 
 root_agent 
 = 
 agent 
 , 
 ) 
 vertex_app 
 = 
 agent_engines 
 . 
 AdkApp 
 ( 
 app_name 
 = 
 app 
 )

ADK

Reference the auth provider in your agent's code using the Agent Registry MCP toolset in the ADK.

 from 
  
 google.adk.agents.llm_agent 
  
 import 
 LlmAgent 
 from 
  
 google.adk.auth.credential_manager 
  
 import 
 CredentialManager 
 from 
  
 google.adk.integrations.agent_identity 
  
 import 
 GcpAuthProvider 
 from 
  
 google.adk.integrations.agent_identity 
  
 import 
 GcpAuthProviderScheme 
 from 
  
 google.adk.tools.mcp_tool.mcp_session_manager 
  
 import 
 StreamableHTTPConnectionParams 
 from 
  
 google.adk.tools.mcp_tool.mcp_toolset 
  
 import 
 McpToolset 
 from 
  
 google.adk.auth.auth_tool 
  
 import 
 AuthConfig 
 from 
  
 google.adk.integrations.agent_registry 
  
 import 
 AgentRegistry 
 # First, register Google Cloud auth provider 
 CredentialManager 
 . 
 register_auth_provider 
 ( 
 GcpAuthProvider 
 ()) 
 # Create Google Cloud auth provider scheme by providing Auth Provider full resource name 
 auth_scheme 
 = 
 GcpAuthProviderScheme 
 ( 
 name 
 = 
 "projects/PROJECT_ID/locations/LOCATION/connectors/AUTH_PROVIDER_NAME" 
 ) 
 # Set Agent Registry 
 registry 
 = 
 AgentRegistry 
 ( 
 project_id 
 = 
 "PROJECT_ID" 
 , 
 location 
 = 
 "global" 
 ) 
 toolset 
 = 
 registry 
 . 
 get_mcp_toolset 
 ( 
 mcp_server_name 
 = 
 "projects/PROJECT_ID/locations/global/mcpServers/agentregistry-00000000-0000-0000-0000-000000000000" 
 , 
 auth_scheme 
 = 
 auth_scheme 
 ) 
 # Example MCP tool 
 toolset 
 = 
 McpToolset 
 ( 
 connection_params 
 = 
 StreamableHTTPConnectionParams 
 ( 
 url 
 = 
 "MCP_URL" 
 ), 
 auth_scheme 
 = 
 auth_scheme 
 , 
 ) 
 agent 
 = 
 LlmAgent 
 ( 
 name 
 = 
 "YOUR_AGENT_NAME" 
 , 
 model 
 = 
 "YOUR_MODEL_NAME" 
 , 
 instruction 
 = 
 "YOUR_AGENT_INSTRUCTIONS" 
 , 
 tools 
 = 
 [ 
 toolset 
 ], 
 )

Install dependencies for local testing

To test your agent locally in a virtual environment, install the following necessary dependencies:

Create and activate a virtual environment:

python3  
-m  
venv  
env source 
  
env/bin/activate

Install the required packages:

pip  
install  
google-cloud-aiplatform [ 
agent_engines,adk ] 
  
google-adk [ 
agent-identity ]

Deploy the agent

When you deploy your agent to Google Cloud, ensure that Agent Identity is enabled.

If you're deploying to Agent Runtime, use the identity_type=AGENT_IDENTITY flag:

  import 
  
  vertexai 
 
 from 
  
 vertexai 
  
 import 
  types 
 
 from 
  
 vertexai.agent_engines 
  
 import 
  AdkApp 
 
 # Initialize the Vertex AI client with v1beta1 API for Agent Identity support 
 client 
 = 
  vertexai 
 
 . 
 Client 
 ( 
 project 
 = 
 "PROJECT_ID" 
 , 
 location 
 = 
 "LOCATION" 
 , 
 http_options 
 = 
 dict 
 ( 
 api_version 
 = 
 "v1beta1" 
 ) 
 ) 
 # Use the proper wrapper class for your Agent Framework (e.g., AdkApp) 
 app 
 = 
 AdkApp 
 ( 
 agent 
 = 
 agent 
 ) 
 # Deploy the agent with Agent Identity enabled 
 remote_app 
 = 
 client 
 . 
  agent_engines 
 
 . 
 create 
 ( 
 agent 
 = 
 app 
 , 
 config 
 = 
 { 
 "identity_type" 
 : 
  types 
 
 . 
  IdentityType 
 
 . 
  AGENT_IDENTITY 
 
 , 
 "requirements" 
 : 
 [ 
 "google-cloud-aiplatform[agent_engines,adk]" 
 , 
 "google-adk[agent-identity]" 
 ], 
 }, 
 )