To grant your agent access to external tools and services (such as Jira tasks or GitHub repositories) on behalf of a specific end user, configure a 3-legged OAuth auth provider in the Agent Identity auth manager.
3-legged OAuth auth providers manage user redirection and tokens for you. This removes the need to write custom code to handle complex OAuth 2.0 flows.
3-legged OAuth workflow
3-legged OAuth auth providers require user consent because the agent accesses resources on behalf of the user.
- Prompt and redirection: The chat interface prompts the user to sign in and then redirects the user to the third-party application's consent page.
- Consent and storage: After the user grants permission, the Agent Identity auth manager stores the resulting OAuth tokens in a Google-managed credential vault.
- Injection: When you use the Agent Development Kit (ADK), the agent automatically retrieves the token from the auth provider and injects it 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 theserviceusage.services.enablepermission. Learn how to grant roles . - Create and deploy an agent .
- Ensure that you have a frontend application to handle user sign-in prompts and redirection to third-party consent pages.
- 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 3-legged 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)
- IAM Connector Admin
(
- To use auth providers:
- IAM Connector User
(
roles/iamconnectors.user) - Vertex AI User
(
roles/aiplatform.user) - Service Usage Consumer
(
roles/serviceusage.serviceUsageConsumer)
- IAM Connector User
(
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 3-legged 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 3-legged 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 3-legged auth provider
Create an auth provider to define the configuration and credentials for third-party applications.
To create a 3-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.
- 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 (3 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. - Copy the callback URL.
- In a separate tab, register the callback URL on your third-party OAuth client application .
- In the Auth provider credentials
section, enter the following
information:
- Client ID
- Client Secret
- Token URL
- Authorization URL
- Click Add provider config .
The newly created auth provider appears in the Auth Providers list.
gcloud CLI
-
Configure your OAuth client application to register your client and obtain a client ID and client secret. Specify the redirect URI using the template in that section.
-
Create the auth provider using your client credentials:
gcloud alpha agent-identity connectors create
AUTH_PROVIDER_NAME\ --project = "PROJECT_ID" \ --location = "LOCATION" \ --three-legged-oauth-client-id = "CLIENT_ID" \ --three-legged-oauth-client-secret = "CLIENT_SECRET" \ --three-legged-oauth-authorization-url = "AUTHORIZATION_URL" \ --three-legged-oauth-token-url = "TOKEN_URL" - Verify that your auth provider appears in the list and its state is
ENABLED:gcloud alpha agent-identity connectors list \ --project = "
PROJECT_ID" \ --location = "LOCATION" -
Grant access permissions to allow your agent and local development environment to retrieve credentials from the auth provider. To allow your deployed agent and your personal user account to access the auth provider, grant the Connector User (
roles/iamconnectors.user) role on the auth provider resource:-
Grant access to your deployed agent's SPIFFE ID (Agent Identity):
gcloud alpha agent-identity connectors add-iam-policy-binding
AUTH_PROVIDER_NAME\ --project = "PROJECT_ID" \ --location = "LOCATION" \ --role = "roles/iamconnectors.user" \ --member = "principal://agents.global.org-ORGANIZATION_ID.system.id.goog/resources/aiplatform/projects/PROJECT_NUMBER/locations/LOCATION/reasoningEngines/ENGINE_ID" -
Grant access to your personal user account for local development and testing (
adk web):gcloud alpha agent-identity connectors add-iam-policy-binding
AUTH_PROVIDER_NAME\ --project = "PROJECT_ID" \ --location = "LOCATION" \ --role = "roles/iamconnectors.user" \ --member = "user:USER_EMAIL"
-
Replace the following:
-
PROJECT_ID: Your Google Cloud project ID. -
LOCATION: The location where your auth provider and agent are deployed (for example,us-west1). -
AUTH_PROVIDER_NAME: The name for your auth provider (for example,bigquery-mcp-3lo-authprovider). -
AUTHORIZATION_URL: The authorization server URL (for example,https://accounts.google.com/o/oauth2/v2/auth). -
TOKEN_URL: The token server URL (for example,https://oauth2.googleapis.com/token). -
CLIENT_ID: The OAuth client ID you generated from the third-party service. -
CLIENT_SECRET: The OAuth client secret you generated from the third-party service. -
ORGANIZATION_ID: Your Google Cloud organization ID. -
PROJECT_NUMBER: Your Google Cloud project number. -
ENGINE_ID: The ID of your deployed reasoning engine agent. -
USER_EMAIL: Your personal user account email address.
Configure your OAuth client application
Before you register your OAuth client credentials, obtain a client ID and client secret from the third-party authorization server (for example, Google, GitHub, or Jira).
If you're connecting to a third-party service outside of Google Cloud, obtain the OAuth client credentials from that service's developer portal and skip the steps in this section.
Register the redirect URI
When you configure your OAuth client credentials, you must register the auth provider's dedicated callback redirect URI.
-
Construct the redirect URI using the following template:
https://iamconnectorcredentials.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/connectors/CONNECTOR_NAME/oauthcallbackReplace the following:
-
PROJECT_ID: Your Google Cloud project ID. -
LOCATION : The region where your auth provider will be deployed (for example,us-west1`). -
CONNECTOR_NAME: The name of your auth provider.
For example:
https://iamconnectorcredentials.googleapis.com/v1/projects/my-project/locations/us-west1/connectors/bigquery-mcp-3lo-authprovider/oauthcallback -
-
If you're connecting to Google Cloud services (such as BigQuery), you can configure the consent screen and create OAuth client credentials in the Google Cloud console:
-
Configure the OAuth consent screen:
- In the Google Cloud console, go to the APIs & Services > OAuth consent screen page.
- In the App information section, enter an application name (such as BigQuery Manager Application) and a support email.
- In the Audience section, select Internal or External .
- Enter your contact information to receive notifications.
- Read and accept the Google API Services User Data Policy .
- Click Finish .
-
Create your OAuth client credentials:
- In the Google Cloud console, go to the APIs & Services > OAuth consent screen > Clients page.
- Click Create credentials > OAuth client ID .
- Select the Web application option from the list.
- Enter a recognizable name for your OAuth client.
- In the Authorized redirect URIs section, click Add URI and enter your constructed redirect URI.
- Click Create . In the OAuth client created dialog, copy your generated Client ID and Client Secret values.
-
Authenticate in your agent code
To authenticate your agent, you can use the ADK or call the Agent Identity API directly.
ADK
Reference the auth provider in your agent's code 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 ()) # The URI to redirect the user to after consent is granted and the # callback is received by the auth provider. CONTINUE_URI = "https://YOUR_FRONTEND_URL/validateUserId" # Create the Auth Provider scheme using the auth provider's full resource name. auth_scheme = GcpAuthProviderScheme ( name = "projects/PROJECT_ID/locations/LOCATION/connectors/AUTH_PROVIDER_NAME" , continue_uri = CONTINUE_URI ) # 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 = "AGENT_NAME" , model = "gemini-2.5-flash" , instruction = "AGENT_INSTRUCTIONS" , tools = [ toolset ], )
Example: Connecting to BigQuery MCP
The following example shows an agent.py
configuration that connects an agent to the BigQuery MCP server using 3-legged OAuth:
import os from google.adk.agents import Agent from google.adk.apps import App from google.adk.auth.credential_manager import CredentialManager from google.adk.integrations.agent_identity import GcpAuthProvider , GcpAuthProviderScheme from google.adk.models import Gemini from google.adk.tools.mcp_tool.mcp_session_manager import StreamableHTTPConnectionParams from google.adk.tools.mcp_tool.mcp_toolset import McpToolset import google.auth from google.genai import types _ , project_id = google . auth . default () os . environ [ "GOOGLE_CLOUD_PROJECT" ] = "PROJECT_ID" os . environ [ "GOOGLE_GENAI_USE_VERTEXAI" ] = "True" bigquery_mcp_auth_provider_id = "AUTH_PROVIDER_NAME" bigquery_mcp_endpoint = os . environ . get ( "BIGQUERY_MCP_ENDPOINT" , "https://bigquery.googleapis.com/mcp" ) # Register Google Cloud auth provider for Agent Identity Credentials service CredentialManager . register_auth_provider ( GcpAuthProvider ()) # The URI to redirect the user to after consent is granted and the callback is received. CONTINUE_URI = "http://127.0.0.1:8501/validateUserId" bigquery_mcp_auth_scheme = GcpAuthProviderScheme ( name = f "projects/ { project_id } /locations/LOCATION/connectors/ { bigquery_mcp_auth_provider_id } " , scopes = [ "https://www.googleapis.com/auth/bigquery" ], continue_uri = CONTINUE_URI , ) bigquery_mcp_tools = McpToolset ( connection_params = StreamableHTTPConnectionParams ( url = bigquery_mcp_endpoint ), auth_scheme = bigquery_mcp_auth_scheme , errlog = None , ) root_agent = Agent ( name = "root_agent" , model = Gemini ( model = "gemini-2.5-flash" , retry_options = types . HttpRetryOptions ( attempts = 3 ), ), instruction = ( "You are a helpful AI assistant designed to provide accurate and useful" " information. You can also use your BigQuery MCP tools to look up" " BigQuery data." ), tools = [ bigquery_mcp_tools ], ) app = App ( root_agent = root_agent , name = "AGENT_NAME" , )
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 ()) # The URI to redirect the user to after consent is completed. CONTINUE_URI = "WEB_APP_VALIDATE_USER_URI" # Create Auth Config spotify_auth_config = AuthConfig ( auth_scheme = GcpAuthProviderScheme ( name = "projects/PROJECT_ID/locations/LOCATION/connectors/AUTH_PROVIDER_NAME" , continue_uri = CONTINUE_URI ) ) # 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 = "AGENT_NAME" , model = "gemini-2.5-flash" , instruction = "AGENT_INSTRUCTIONS" , tools = [ spotify_search_track_tool ], ) app = App ( name = "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 ()) # The URI to redirect the user to after consent is completed. CONTINUE_URI = "WEB_APP_VALIDATE_USER_URI" # Create Google Cloud auth provider by providing auth provider full resource name auth_scheme = GcpAuthProviderScheme ( name = "projects/PROJECT_ID/locations/LOCATION/connectors/AUTH_PROVIDER_NAME" , continue_uri = CONTINUE_URI ) # 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 = "AGENT_NAME" , model = "MODEL_NAME" , instruction = "AGENT_INSTRUCTIONS" , tools = [ toolset ], )
Call the API directly
If you aren't using the ADK, your agent must call the iamconnectorcredentials.retrieveCredentials
API to get the token.
Because this is a multi-step OAuth flow, the API returns a Long Running Operation (LRO) . Your agent must handle the lifecycle of the operation:
- Initial request
: The agent calls
retrieveCredentials. - Consent required
: If the user hasn't granted consent, the API returns an
LRO where the metadata contains the
auth_uriand aconsent_nonce. - Frontend redirection
: Your application must redirect the user to the
auth_uri. - Completion
: After the user grants consent, call
FinalizeCredentialusing theconsent_nonceto complete the flow and obtain the token.
Update your client-side application
To handle user sign-in and redirection for 3-legged OAuth, your client-side application must implement the following steps to manage user consent and resume the conversation:
Sample UI server
You can download and run a complete sample UI server that uses uvicorn
. Before you begin, ensure that you have a GitHub
account and pip
installed.
To set up and run the sample UI server, do the following:
-
Clone the
adk-pythonGitHub repository:git clone https://github.com/google/adk-python.git
-
Navigate to the repository and activate a Python virtual environment:
cd adk-python python3 -m venv .venv source .venv/bin/activate
-
Navigate to the sample UI client directory:
cd contributing/samples/integrations/gcp_auth/client
-
Install the client dependencies:
pip install -r requirements.txt
-
Before starting the server, set the
AGENT_PROJECT_DIRenvironment variable to specify the directory where your agent code is located. Otherwise, the application defaults to looking for agents in the parent folder of the client directory.Launch the sample UI server using
uvicorn. Ensure that the port matches the redirect URI configured in your OAuth client:export AGENT_PROJECT_DIR = "/path/to/your/agent_project" uvicorn main:app --port 8501 --reload
-
Open
http://localhost:8501in your browser. (Note: You must uselocalhostand not127.0.0.1, as the OAuth redirect URL specifically requires it.) Specify your settings, click Save & Apply Settings , and then interact with your agent.
Custom UI application
To implement these capabilities directly in a custom UI application, perform the following steps:
Handle the authorization trigger
When an agent needs user consent, it returns an adk_request_credential
function call. Your application must
intercept this call to initiate a user authorization dialog or redirect.
Manage the session context by recording the consent_nonce
provided by the auth provider. This nonce is required to verify the user during
the validation step. Save the auth_config
and auth_request_function_call_id
values within the session to
facilitate resuming the flow after the user grants consent.
if ( fc := get_auth_request_function_call ( event_data )): print ( "--> Authentication required by agent." ) try : auth_config = get_auth_config ( fc ) auth_uri , consent_nonce = handle_adk_request_credential ( auth_config , AUTH_PROVIDER_NAME , request . user_id ) if auth_uri : event_data [ 'popup_auth_uri' ] = auth_uri fc_id = ( fc . get ( 'id' ) if isinstance ( fc , dict ) else getattr ( fc , 'id' , None ) ) event_data [ 'auth_request_function_call_id' ] = fc_id event_data [ 'auth_config' ] = auth_config . model_dump () # Store session state if session_id : consent_sessions [ session_id ] = { "user_id" : request . user_id , "consent_nonce" : consent_nonce } except Exception as e : print ( f "Error handling adk_request_credential: { e } " ) # Optionally, add logic to inform the user about the error. def handle_adk_request_credential ( auth_config , auth_provider_name , user_id ): ec = auth_config . exchanged_auth_credential if ec and ec . oauth2 : oauth2 = ec . oauth2 return oauth2 . auth_uri , oauth2 . nonce return None , None
Implement a user validation endpoint
Implement a validation endpoint on your web server (the same URI provided as continue_uri
during configuration). This endpoint must do the
following:
- Receive
user_id_validation_stateandauth_provider_nameas query parameters. - Retrieve the
user_idandconsent_noncevalues from the session context. - Call the auth provider's
FinalizeCredentialsAPI with these parameters. - Close the authorization window upon receiving a success response.
Example: FastAPI validation endpoint ( main.py
)
The following example shows a complete FastAPI validation endpoint that handles the OAuth callback and finalizes user credentials:
@app . api_route ( "/validateUserId" , methods = [ "GET" ]) async def validate_user ( request : Request ): auth_provider_name = request . query_params . get ( "auth_provider_name" ) session_id = request . cookies . get ( "session_id" ) session = consent_sessions . get ( session_id , {}) payload = { "userId" : session . get ( "user_id" ), "userIdValidationState" : request . query_params . get ( "user_id_validation_state" ), "consentNonce" : session . get ( "consent_nonce" ), } base_url = "https://iamconnectorcredentials.googleapis.com/v1alpha" finalize_url = f " { base_url } / { auth_provider_name } /credentials:finalize" try : async with httpx . AsyncClient ( timeout = 30.0 ) as client : resp = await client . post ( finalize_url , json = payload ) resp . raise_for_status () except httpx . HTTPError as e : err_text = e . response . text if hasattr ( e , "response" ) else str ( e ) status = e . response . status_code if hasattr ( e , "response" ) else 500 return HTMLResponse ( err_text , status_code = status ) return HTMLResponse ( """ <script> window.close(); </script> <p>Success. You can close this window.</p> """ )
Resume the agent conversation
After the user grants consent and the authorization window closes, retrieve
the auth_config
and auth_request_function_call_id
values from your session data. To continue the conversation, include these
details in a new request to the agent as a function_response
.
if ( request . is_auth_resume and session . auth_request_function_call_id and session . auth_config ): auth_content = types . Content ( role = 'user' , parts = [ types . Part ( function_response = types . FunctionResponse ( id = session . auth_request_function_call_id , name = 'adk_request_credential' , response = session . auth_config ) ) ], ) # Send message to agent async for event in agent . async_stream_query ( user_id = request . user_id , message = auth_content , session_id = session_id , ): # ...
Deploy the agent
When you deploy your agent to Google Cloud, ensure that Agent Identity is enabled.
If you're deploying to
Agent Runtime on Gemini Enterprise Agent Platform
, 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]"
],
},
)
