Skip to content

Agent Identity Auth Manager for ADK

Supported in ADKPython v1.30.0Preview

The Google Cloud Agent Identity service provides a streamlined, Google-managed solution for managing the complete lifecycle of auth credentials, including storing credential configurations, generating and storing tokens, and auditing access. This approach allows for a secure and simplified agent development experience.

Preview release

The Agent Identity Auth Manager feature is a Preview release. For more information, see the launch stage descriptions.

Use cases

  • Simplified OAuth Flow: Manage the complete lifecycle of auth credentials without building custom infrastructure.
  • Secure Exchange and Storage of Tokens: Securely store credential configurations and exchange tokens.
  • Audit Logging: View and audit access to stored credentials.

Prerequisites

Installation

Install the agent-identity extra package group to download the necessary client libraries.

pip install "google-adk[agent-identity]"

Use with agent

Follow these steps to use the Agent Identity Auth Manager within ADK:

Register auth provider

To enable ADK to determine which BaseAuthProvider to use for a given CustomAuthScheme, register the GcpAuthProvider instance with the CredentialManager. This needs to be done only once in the agent code.

from google.adk.auth.credential_manager import CredentialManager
from google.adk.integrations.agent_identity import GcpAuthProvider

CredentialManager.register_auth_provider(GcpAuthProvider())

Configure tools

Configure the Agent Identity auth provider using a GcpAuthProviderScheme object, then pass it to the auth_scheme parameter of any supported Tool or Toolset. The following example shows usage with McpToolset, but GcpAuthProviderScheme also works with other tools like AuthenticatedFunctionTool. See the GCP Auth sample for a complete example.

from google.adk.integrations.agent_identity import GcpAuthProviderScheme
from google.adk.tools.mcp import McpToolset

auth_scheme = GcpAuthProviderScheme(
    name="projects/PROJECT_ID/locations/LOCATION/connectors/AUTH_PROVIDER_NAME",
    # continue_uri is only needed for 3-legged OAuth flows. This URI receives
    # the redirect after user consent and must be hosted by your application.
    continue_uri=CONTINUE_URI
)

toolset = McpToolset(
    connection_params=StreamableHTTPConnectionParams(url="https://YOUR_MCP_SERVER_URL"),
    auth_scheme=auth_scheme,
)
  • Detecting the Auth Request: Similar to the existing flow, whenever user consent is required, a FunctionCall event named adk-request-credential is generated containing the auth_uri field. The user app should open the auth_uri in a popup window to continue the user consent flow.
  • Continue URI Handler:
    • Once the user completes the OAuth consent flow on the third-party provider's website, the system redirects to the continue_uri callback defined earlier in the GcpAuthProviderScheme. The agent application service must implement this redirect. To finalize issuance, your handler must submit a POST request to the credentials endpoint: https://iamconnectorcredentials.googleapis.com/v1alpha/{connector_name}/credentials:finalize.
    • After credentials are successfully finalized, the web application should resume the agent by sending a FunctionResponse. For a sample implementation, refer to the sample code. Unlike the native user consent flow, no authorization code is required to resume the agent.
    • For more details, refer to the sample handler implementation.
  • Resume the conversation: Irrespective of the status of the consent flow (successful or unsuccessful), the agent app should resume the agent to complete the conversation turn. The ADK automatically determines whether consent was successfully completed and raise an error if it was not.

Resources