Google Adk Auth

Google ADK — Authentication & Credentials

Overview

ADK's auth system connects tools to authenticated APIs. It handles credential construction, OAuth2 flows, and credential persistence.

Imports

from google.adk.auth import (
    AuthCredential,
    AuthCredentialTypes,
    AuthScheme,
    AuthSchemeType,
    AuthConfig,
    OAuth2Auth,
    OpenIdConnectWithConfig,
)
from google.adk.auth.auth_credential import (
    HttpAuth,
    HttpCredentials,
    ServiceAccount,
    ServiceAccountCredential,
)
from google.adk.auth.credential_service.in_memory_credential_service import InMemoryCredentialService
from google.adk.auth.credential_service.session_state_credential_service import SessionStateCredentialService
from google.adk.tools.openapi_tool.auth.auth_helpers import (
    token_to_scheme_credential,
    service_account_scheme_credential,
    service_account_dict_to_scheme_credential,
    openid_dict_to_scheme_credential,
    openid_url_to_scheme_credential,
)

AuthCredential Types

API Key

credential = AuthCredential(
    auth_type=AuthCredentialTypes.API_KEY,
    api_key="your-api-key-here",
)

HTTP Bearer Token

credential = AuthCredential(
    auth_type=AuthCredentialTypes.HTTP,
    http=HttpAuth(
        scheme="bearer",
        credentials=HttpCredentials(token="eyJhbGciOi..."),
    ),
)

HTTP Basic Auth

credential = AuthCredential(
    auth_type=AuthCredentialTypes.HTTP,
    http=HttpAuth(
        scheme="basic",
        credentials=HttpCredentials(username="user", password="pass"),
    ),
)

OAuth2 (Authorization Code Flow)

credential = AuthCredential(
    auth_type=AuthCredentialTypes.OAUTH2,
    oauth2=OAuth2Auth(
        client_id="your-client-id",
        client_secret="your-client-secret",
    ),
)

OpenID Connect

credential = AuthCredential(
    auth_type=AuthCredentialTypes.OPEN_ID_CONNECT,
    oauth2=OAuth2Auth(
        client_id="your-client-id",
        client_secret="your-client-secret",
        redirect_uri="https://example.com/callback",
    ),
)

Service Account (JSON Key)

credential = AuthCredential(
    auth_type=AuthCredentialTypes.SERVICE_ACCOUNT,
    service_account=ServiceAccount(
        service_account_credential=ServiceAccountCredential(
            type_="service_account",
            project_id="my-project",
            private_key_id="key-id",
            private_key="-----BEGIN PRIVATE KEY-----\n...",
            client_email="sa@project.iam.gserviceaccount.com",
            client_id="123456",
            auth_uri="https://accounts.google.com/o/oauth2/auth",
            token_uri="https://oauth2.googleapis.com/token",
            auth_provider_x509_cert_url="https://www.googleapis.com/oauth2/v1/certs",
            client_x509_cert_url="https://www.googleapis.com/robot/v1/metadata/x509/...",
            universe_domain="googleapis.com",
        ),
        scopes=["https://www.googleapis.com/auth/cloud-platform"],
    ),
)

Service Account (Application Default Credentials)

credential = AuthCredential(
    auth_type=AuthCredentialTypes.SERVICE_ACCOUNT,
    service_account=ServiceAccount(
        use_default_credential=True,
        scopes=["https://www.googleapis.com/auth/cloud-platform"],
    ),
)

Service Account (ID Token for Cloud Run)

credential = AuthCredential(
    auth_type=AuthCredentialTypes.SERVICE_ACCOUNT,
    service_account=ServiceAccount(
        use_default_credential=True,
        use_id_token=True,
        audience="https://my-service-xyz.run.app",
    ),
)

Auth Helpers (Convenience Builders)

API Key via Helper

from google.adk.tools.openapi_tool.auth.auth_helpers import token_to_scheme_credential

# API Key in header
auth_scheme, auth_credential = token_to_scheme_credential(
    "apikey", "header", "X-API-Key", "your-key-value"
)

# API Key in query parameter
auth_scheme, auth_credential = token_to_scheme_credential(
    "apikey", "query", "api_key", "your-key-value"
)

Bearer Token via Helper

auth_scheme, auth_credential = token_to_scheme_credential(
    "oauth2Token", "header", "Authorization", "your-bearer-token"
)

Service Account via Helper

from google.adk.tools.openapi_tool.auth.auth_helpers import service_account_scheme_credential

auth_scheme, auth_credential = service_account_scheme_credential(
    ServiceAccount(
        use_default_credential=True,
        scopes=["https://www.googleapis.com/auth/cloud-platform"],
    )
)

OpenID Connect via Discovery URL

from google.adk.tools.openapi_tool.auth.auth_helpers import openid_url_to_scheme_credential

auth_scheme, auth_credential = openid_url_to_scheme_credential(
    openid_url="https://accounts.google.com/.well-known/openid-configuration",
    scopes=["openid", "email", "profile"],
    credential_dict={
        "client_id": "your-client-id",
        "client_secret": "your-client-secret",
        "redirect_uri": "https://example.com/callback",
    },
)

Integration with OpenAPIToolset

from google.adk.tools.openapi_tool.openapi_spec_parser.openapi_toolset import OpenAPIToolset
from google.adk.tools.openapi_tool.auth.auth_helpers import token_to_scheme_credential

# Create auth scheme and credential
auth_scheme, auth_credential = token_to_scheme_credential(
    "apikey", "header", "X-API-Key", "sk-live-xxx"
)

# Pass to OpenAPIToolset
toolset = OpenAPIToolset(
    spec_str=open("openapi.yaml").read(),
    spec_str_type="yaml",
    auth_scheme=auth_scheme,
    auth_credential=auth_credential,
)

agent = Agent(
    name="api_agent",
    model="gemini-2.5-flash",
    instruction="Call the API.",
    tools=[*toolset.get_tools()],
)

OAuth2 with OpenAPIToolset

from google.adk.auth import AuthCredential, AuthCredentialTypes, OAuth2Auth

toolset = OpenAPIToolset(
    spec_str=spec_str,
    spec_str_type="json",
    auth_scheme=auth_scheme,
    auth_credential=AuthCredential(
        auth_type=AuthCredentialTypes.OAUTH2,
        oauth2=OAuth2Auth(
            client_id="your-client-id",
            client_secret="your-client-secret",
        ),
    ),
    credential_key="my_oauth_cred",
)

Credential Services

Credential services persist exchanged credentials so users don't re-authenticate every invocation.

InMemoryCredentialService (Development)

from google.adk.auth.credential_service.in_memory_credential_service import InMemoryCredentialService

credential_service = InMemoryCredentialService()

SessionStateCredentialService (Session-Backed)

Stores credentials in session state. Simple but not secure for production.

from google.adk.auth.credential_service.session_state_credential_service import SessionStateCredentialService

credential_service = SessionStateCredentialService()

Wiring Credential Service to Runner

from google.adk.runners import Runner

runner = Runner(
    agent=agent,
    session_service=session_service,
    app_name="my_app",
)
# Note: credential_service is passed to the agent's auth handler,
# not directly to the Runner. It's used internally by the auth system.

AuthConfig (Tool Auth Requirements)

AuthConfig pairs a scheme with credentials. Used internally when tools require authentication:

from google.adk.auth import AuthConfig, AuthScheme

auth_config = AuthConfig(
    auth_scheme=auth_scheme,
    raw_auth_credential=auth_credential,
    credential_key="unique_key_for_caching",
)

Fields:

• auth_scheme — How auth is applied (SecurityScheme from OpenAPI)
• raw_auth_credential — Initial credential (e.g., client_id + secret for OAuth2)
• exchanged_auth_credential — Final usable credential (e.g., access token after OAuth2 exchange)
• credential_key — Stable key for credential storage/retrieval

AuthScheme Types

AuthScheme uses FastAPI's OpenAPI security models:

from fastapi.openapi.models import APIKey, APIKeyIn, HTTPBearer, OAuth2, OAuthFlows

# API Key in header
scheme = APIKey(**{"type": "apiKey", "in": APIKeyIn.header, "name": "X-API-Key"})

# Bearer token
scheme = HTTPBearer(bearerFormat="JWT")

# OAuth2 Authorization Code
scheme = OAuth2(flows=OAuthFlows(
    authorizationCode={
        "authorizationUrl": "https://example.com/auth",
        "tokenUrl": "https://example.com/token",
        "scopes": {"read": "Read access"},
    }
))

Key Rules

• AuthCredentialTypes enum values: API_KEY, HTTP, OAUTH2, OPEN_ID_CONNECT, SERVICE_ACCOUNT
• OpenID Connect uses oauth2 field (same as OAuth2) but with auth_type=OPEN_ID_CONNECT
• Service Account requires either service_account_credential OR use_default_credential=True
• When use_id_token=True, audience is required (target service URL)
• Auth helpers return Tuple[AuthScheme, AuthCredential] — pass both to OpenAPIToolset
• Credential services are experimental (@experimental decorator)
• credential_key enables credential caching — same key = same stored credential
• The auth system auto-generates credential_key from scheme + credential if not provided

Related Skills

• google-adk-openapi-tool — OpenAPIToolset where auth is most commonly used
• google-adk-callbacks — before_tool_callback can enforce auth checks
• google-adk-session — Session services (SessionStateCredentialService stores in session)