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.

By managing credentials and tokens, 2-legged OAuth auth providers remove the need for 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

  1. Verify that you have chosen the correct authentication method.

  2. Enable the Agent Identity API.

    Roles required to enable APIs

    To enable APIs, you need the serviceusage.services.enable permission. If you created the project, then you likely already have this permission through the Owner role (roles/owner). Otherwise, you can get this permission through the Service Usage Admin role (roles/serviceusage.serviceUsageAdmin). Learn how to grant roles.

    Enable the API

  3. Create and deploy an agent.

  4. Obtain the client ID and client secret from the third-party application that you want to connect to.

  5. 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:

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 permissions section:

Required permissions

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

  • To create auth providers: agentidentity.authProviders.create
  • To use auth providers:
    • agentidentity.authProviders.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

  1. In the Google Cloud console, go to the Agent Registry page.

    Go to Agent Registry

  2. Click the name of the agent that you want to create an auth provider for.
  3. Click Identity.
  4. In the Auth Providers section, click Add auth provider.

  5. 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.

  6. From the OAuth Type list, select OAuth (2 legged) .
  7. Click Create and continue.
  8. To grant your agent identity permission to use the auth provider, click Grant access.

    This process automatically assigns the Agent Identity User (roles/agentidentity.user) role to the agent identity on the auth provider resource.

  9. In the Auth provider credentials section, enter the following information:
    • Client ID
    • Client Secret
    • Token URL
  10. Click Add provider config.

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

gcloud CLI

  1. Create the auth provider:

    gcloudagent-identityauth-providerscreateAUTH_PROVIDER_NAME\
--location="LOCATION"\
--two-legged-oauth-client-id="CLIENT_ID"\
--two-legged-oauth-client-secret="CLIENT_SECRET"\
--two-legged-oauth-token-url="TOKEN_URL"
  2. Verify that your auth provider appears in the list and its state is ENABLED: 
    gcloudagent-identityauth-providerslist\
--project="PROJECT_ID"\
--location="LOCATION"

  3. 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 Agent Identity User (roles/agentidentity.user) role on the auth provider resource:

    1. Grant access to your deployed agent's SPIFFE ID (Agent Identity):

      gcloudagent-identityauth-providersadd-iam-policy-bindingAUTH_PROVIDER_NAME\
--project="PROJECT_ID"\
--location="LOCATION"\
--role="roles/agentidentity.user"\
--member="principal://agents.global.org-ORGANIZATION_ID.system.id.goog/resources/aiplatform/projects/PROJECT_NUMBER/locations/LOCATION/reasoningEngines/ENGINE_ID"

    2. Grant access to your personal user account for local development and testing (adk web):

      gcloudagent-identityauth-providersadd-iam-policy-bindingAUTH_PROVIDER_NAME\
--project="PROJECT_ID"\
--location="LOCATION"\
--role="roles/agentidentity.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, jira-mcp-2lo-authprovider).
  • 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.
  • TOKEN_URL: The token server URL (for example, https://oauth2.googleapis.com/token).
  • 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.

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.

fromgoogle.adk.agentsimport Agent
fromgoogle.adk.auth.credential_managerimport CredentialManager
fromgoogle.adk.integrations.agent_identityimport GcpAuthProvider, GcpAuthProviderScheme
fromgoogle.adk.tools.mcp_tool.mcp_session_managerimport StreamableHTTPConnectionParams
fromgoogle.adk.tools.mcp_tool.mcp_toolsetimport McpToolset
fromgoogle.adk.auth.auth_toolimport 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
# Note: If using the legacy V1 API, the resource name uses 'connectors'
# instead of 'authProviders': projects/.../connectors/...
auth_scheme = GcpAuthProviderScheme(
 name="projects/PROJECT_ID/locations/LOCATION/authProviders/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 = Agent(
 name="AGENT_NAME",
 model="gemini-2.5-flash",
 instruction="AGENT_INSTRUCTIONS",
 tools=[toolset],
)

ADK

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

importhttpx
fromgoogle.adk.agentsimport Agent
fromgoogle.adk.auth.credential_managerimport CredentialManager
fromgoogle.adk.integrations.agent_identityimport GcpAuthProvider
fromgoogle.adk.integrations.agent_identityimport GcpAuthProviderScheme
fromgoogle.adk.appsimport App
fromgoogle.adk.auth.auth_credentialimport AuthCredential
fromgoogle.adk.auth.auth_toolimport AuthConfig
fromgoogle.adk.tools.authenticated_function_toolimport AuthenticatedFunctionTool
fromvertexaiimport agent_engines
# First, register Google Cloud auth provider
CredentialManager.register_auth_provider(GcpAuthProvider())
# Create Auth Config
# Note: If using the legacy V1 API, the resource name uses 'connectors'
# instead of 'authProviders': projects/.../connectors/...
spotify_auth_config = AuthConfig(
 auth_scheme=GcpAuthProviderScheme(
 name=(
 "projects/PROJECT_ID/locations/"
 "LOCATION/authProviders/"
 "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 defspotify_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 = Agent(
 name="AGENT_NAME",
 model="MODEL_NAME",
 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.

fromgoogle.adk.agentsimport Agent
fromgoogle.adk.auth.credential_managerimport CredentialManager
fromgoogle.adk.integrations.agent_identityimport GcpAuthProvider
fromgoogle.adk.integrations.agent_identityimport GcpAuthProviderScheme
fromgoogle.adk.tools.mcp_tool.mcp_session_managerimport StreamableHTTPConnectionParams
fromgoogle.adk.tools.mcp_tool.mcp_toolsetimport McpToolset
fromgoogle.adk.auth.auth_toolimport AuthConfig
fromgoogle.adk.integrations.agent_registryimport AgentRegistry
# First, register Google Cloud auth provider
CredentialManager.register_auth_provider(GcpAuthProvider())
# Create Google Cloud auth provider scheme
# Note: If using the legacy V1 API, the resource name uses 'connectors'
# instead of 'authProviders': projects/.../connectors/...
auth_scheme = GcpAuthProviderScheme(
 name=(
 "projects/PROJECT_ID/locations/"
 "LOCATION/authProviders/"
 "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 = Agent(
 name="AGENT_NAME",
 model="MODEL_NAME",
 instruction="AGENT_INSTRUCTIONS",
 tools=[toolset],
)

Install dependencies for local testing

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

  1. Create and activate a virtual environment: 
    python3-mvenvenv
sourceenv/bin/activate
  2. Install the required packages: 
    pipinstallgoogle-cloud-aiplatform[agent_engines,adk]google-adk[agent-identity]

Deploy the agent

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

Agent CLI

If you're using the Agent Development Kit (ADK) and the Agent CLI, do the following to deploy your agent with Agent Identity enabled:

  1. In your agent application folder, create a configuration file named .agent_engine_config.json to enable Agent Identity:

    echo'{ "identity_type": "AGENT_IDENTITY" }' > AGENT_NAME/.agent_engine_config.json

  2. Deploy your agent to Agent Runtime on Gemini Enterprise Agent Platform :

    uvrunadkdeployagent_engineAGENT_NAME\
--project="PROJECT_ID"\
--region="LOCATION"

    Replace the following:

    • AGENT_NAME: The name of your agent application folder (for example, maps_agent).
    • PROJECT_ID: Your Google Cloud project ID.
    • LOCATION: The supported region where you want to deploy the agent (for example, us-west1).

Python SDK

If you're deploying programmatically using the Vertex AI Python SDK, use the identity_type=AGENT_IDENTITY flag:

importvertexai
fromvertexaiimport types
fromvertexai.agent_enginesimport 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,mcp]>=2.7.1",
 ],
 },
)

Replace the following:

  • PROJECT_ID: Your Google Cloud project ID.
  • LOCATION: The supported region where you want to deploy the agent (for example, us-west1).

What's next

Except as otherwise noted, the content of this page is licensed under the Creative Commons Attribution 4.0 License, and code samples are licensed under the Apache 2.0 License. For details, see the Google Developers Site Policies. Java is a registered trademark of Oracle and/or its affiliates.

Last updated 2026年08月28日 UTC.