Credential Providers & SDK Decorators

The single most common confusion in AgentCore Identity is treating "who can call my agent" and "how my agent calls Google" as the same setting. They are two completely separate mechanisms that happen to both involve OAuth, and wiring one where you needed the other produces a 401 you will stare at for an hour.

• Inbound identity provider (IdP) — the OIDC provider whose JWTs gate who can invoke your agent, tool, Runtime, or Gateway. This is the bouncer at the door. Examples: Cognito, Entra ID, Okta, Auth0, Keycloak, PingFederate. You configure it as a customJWTAuthorizer (discovery URL, allowed clients, allowed audience/scopes). It answers: is this caller allowed in?
• Outbound credential provider — configuration that lets your agent get a token for a downstream resource (Google Drive, GitHub, Slack, an internal API). This is the valet who fetches the user's keys from a locked vault. You create it with CreateOauth2CredentialProvider or CreateApiKeyCredentialProvider. It answers: how does the agent authenticate to the thing it's about to call?

The same vendor name can appear on both sides and still mean different things. Auth0 as an inbound IdP validates the JWT that lets a user invoke your agent. Auth0Oauth2 as an outbound credential provider is how your agent obtains a token to call an Auth0-protected downstream API. Same brand, opposite direction of trust.

   Caller ──(JWT from inbound IdP: Cognito/Entra/Okta)──▶  [ Your Agent ]
                                                               │
                                                               │ outbound credential provider
                                                               ▼
                                              Google Drive / GitHub / Slack / internal API

Keep the mental split sharp: inbound = authenticate the caller; outbound = authenticate the agent to a downstream service. Everything else in this lesson is the outbound side.

AgentCore Identity ships first-class config blocks for the common OAuth2 providers so you don't hand-roll discovery URLs and endpoints. You pick a credentialProviderVendor and supply the matching provider-config block.

For providers without a named built-in, CustomOauth2 accepts any OIDC-compliant authorization server via its discovery URL — that's your escape hatch for self-hosted IdPs like Keycloak or PingFederate, which are supported for both inbound JWT and outbound credential providers.

Not everything is OAuth. Some services authenticate with a single static API key — OpenAI is the canonical example. For those, you create an API-key credential provider with CreateApiKeyCredentialProvider; the key lives in the token vault (encrypted with KMS) and is fetched at call time with @requires_api_key. Use OAuth providers when the downstream service does delegated user consent; use API-key providers when it's just a bearer secret.

Credential providers are control-plane resources. You create them once (per provider, per account/region) on the bedrock-agentcore-control API — via the AWS CLI, boto3, or the lower-level SDK IdentityClient.

OAuth2 provider (CLI):

aws bedrock-agentcore-control create-oauth2-credential-provider --region us-east-1 \
  --name "google-provider" --credential-provider-vendor "GoogleOauth2" \
  --oauth2-provider-config-input '{"googleOauth2ProviderConfig":{"clientId":"...","clientSecret":"..."}}'
# IMPORTANT: register the returned callbackUrl in the provider's "Authorized redirect URIs"

Lower-level SDK (IdentityClient):

from bedrock_agentcore.services.identity import IdentityClient

identity = IdentityClient(region="us-east-1")

# OAuth2 (delegated, 3LO-capable)
identity.create_oauth2_credential_provider(...)

# Static API key (e.g. OpenAI)
identity.create_api_key_credential_provider(...)

The clientId / clientSecret you pass are the OAuth app credentials you registered with the provider (Google Cloud Console, a GitHub OAuth App, etc.). AgentCore stores them in the vault and uses them to drive the authorization-code (3LO) or client-credentials (2LO) flow.

The call returns a callbackUrl — and that return value is the single most-missed step in the whole feature, covered next.

When you create an OAuth2 credential provider, AgentCore returns a callback URL of this shape:

https://bedrock-agentcore.<region>.amazonaws.com/identities/oauth2/callback/<uuid>

This is the redirect URI the provider (Google, GitHub, Slack...) will send the user back to after they grant consent. You must register that exact URL in the provider's "Authorized redirect URIs" list. If you don't, the 3LO authorization-code flow breaks: the user authenticates, the provider tries to redirect to a URI it doesn't recognize, and the flow dies with a redirect-mismatch error before AgentCore ever sees the code.

Concretely, for a Google provider in us-east-1:

# 1. create-oauth2-credential-provider returns something like:
https://bedrock-agentcore.us-east-1.amazonaws.com/identities/oauth2/callback/3f2c1a9e-...-d4

# 2. In Google Cloud Console → your OAuth client → Authorized redirect URIs:
#    paste that exact URL (region + uuid must match)

This only bites 3LO (user-delegated, authorization-code) flows — pure 2LO/M2M client-credentials flows have no browser redirect, so there's no callback to register. But the failure mode is sneaky precisely because everything looks configured: the provider exists, the decorator runs, the consent page even renders. The break happens at the redirect hop, which is exactly the step people forget to wire up.

Once the provider exists, you almost never call the vault APIs by hand. The Python SDK gives you two decorators in bedrock_agentcore.identity.auth that run the entire workload-identity → vault → consent flow and inject the resolved credential as a keyword argument — so your function body, and the LLM driving it, never see the raw token.

OAuth access token (3LO / user-delegated):

from bedrock_agentcore.identity.auth import requires_access_token

@requires_access_token(
    provider_name="google-provider",
    scopes=["https://www.googleapis.com/auth/drive.metadata.readonly"],
    auth_flow="USER_FEDERATION",                     # 3LO; "M2M" for client-credentials/2LO
    on_auth_url=lambda url: print("Authorize:\n" + url),
    force_authentication=False,
    callback_url="<oauth2_callback_url>")
async def read_from_google_drive(*, access_token: str):
    # access_token is injected by the decorator — never passed by the LLM,
    # never stored in code. Use it to call the downstream API.
    ...

The full @requires_access_token signature: provider_name, scopes, auth_flow ("M2M" | "USER_FEDERATION"), into="access_token" (the kwarg name to inject into), on_auth_url, callback_url, force_authentication=False, token_poller, custom_state, custom_parameters. Set into="..." if you want the token under a different parameter name.

Static API key (e.g. OpenAI):

from bedrock_agentcore.identity.auth import requires_api_key

@requires_api_key(provider_name="openai-provider")
async def call_openai(*, api_key: str):
    # api_key fetched from the vault and injected as a kwarg
    ...

Why the kwarg injection matters: the credential is resolved at call time from the vault and handed to the function as a parameter. It is not embedded in the prompt, not returned to the model, and not logged in your business logic. That's the whole security pitch — the agent reasons about what to do, the decorator handles how to authenticate, and the secret stays out of context.

Token caching & refresh: under 3LO, AgentCore caches the access + refresh tokens in the vault keyed by (agent workload identity + user id), so subsequent calls skip consent until expiry and auto-refresh. If a provider revokes a token, the call fails — set force_authentication=True to force a fresh consent.

Lower-level escape hatch: if you need finer control, IdentityClient exposes create_oauth2_credential_provider, create_api_key_credential_provider, create_workload_identity, get_workload_access_token(...), async get_token(...), async get_api_key(...), and complete_resource_token_auth(session_uri, user_identifier).

The on_auth_url=lambda url: print(...) in the examples is a demo affordance. In production there is no terminal to print to — the agent is a serverless Runtime handling a request. Printing the consent URL means the user never sees it and the 3LO flow stalls forever.

The production pattern is to stream the consent URL back to the caller so your front end can render it as a clickable "Connect your Google account" link:

async def entrypoint(payload, *, stream):
    async def surface_consent(url: str):
        # send the URL to the caller instead of printing it
        await stream.send({"type": "auth_required", "consent_url": url})

    @requires_access_token(
        provider_name="google-provider",
        scopes=["https://www.googleapis.com/auth/drive.metadata.readonly"],
        auth_flow="USER_FEDERATION",
        on_auth_url=surface_consent,        # stream it, do not print it
        callback_url="<oauth2_callback_url>")
    async def read_drive(*, access_token: str):
        ...
    return await read_drive()

How this relates to Gateway. AgentCore Gateway aggregates downstream tools (Lambda, OpenAPI, MCP servers, Smithy, API Gateway, Runtime) behind one MCP endpoint, and its outbound (egress) auth is powered by the same AgentCore Identity machinery you just learned. When a Gateway target uses OAuth, the gateway's service role calls into Identity exactly as the decorators do — its role needs bedrock-agentcore:GetWorkloadAccessToken, bedrock-agentcore:GetResourceOauth2Token, and secretsmanager:GetSecretValue (swap GetResourceOauth2Token → bedrock-agentcore:GetResourceApiKey for API-key targets). So the credential providers you create here are reused whether the agent calls a downstream API directly via a decorator or through a Gateway target. Identity is the credential layer; Gateway is one consumer of it.