Outbound Auth & the Token Vault

Your agent needs to read the user's Google Drive, open a GitHub issue, or post to a Slack channel. The naive approaches all fail in production:

• Hard-code an API key. Now every user shares one identity, the secret lives in your image, and it leaks into logs and the LLM context the moment something gets printed.
• Pass the user's OAuth token in the prompt. The token is now in plaintext in the model's context window — exfiltratable by prompt injection, logged by observability, and impossible to scope or revoke per call.
• Ask the user to paste credentials. Consent fatigue, no refresh, and you are storing other people's tokens yourself.

Outbound Auth (the egress side of AgentCore Identity) solves this. The agent never holds a long-lived secret. Instead it proves who it is acting for, and AgentCore's token vault hands back a short-lived downstream token — fetched, refreshed, and isolated by the service. The raw token is injected as a function argument, not into the model.

Teaching framing from the dossier: Inbound = the bouncer at the door. Outbound = the valet who fetches the user's keys from a locked vault. Identity makes agentic auth delegated, not impersonated-with-a-shared-secret.

Two problems get solved at once: the agent reaches downstream resources (Google Drive, GitHub, Slack, internal APIs, other MCP servers) on behalf of the user (3LO) or as itself (2LO/M2M), and it does so without any secret in code or in LLM context.

A Workload Identity is auto-created with every runtime (ARN shape arn:aws:bedrock-agentcore:<region>:<account>:workload-identity/directory/default/workload-identity/<agent-name>). It is the agent's first-class identity — the thing the vault keys credentials against. The end-to-end outbound flow has five steps:

1. Inbound: the Runtime authorizes the inbound token (a JWT, or SigV4 for IAM callers). This is the upstream step covered in the inbound-auth lesson.
2. Exchange: the Runtime exchanges that inbound token for a Workload Access Token via bedrock-agentcore:GetWorkloadAccessTokenForJWT (JWT path — it derives user identity from the ISS/SUB claims). The token is delivered in the payload header WorkloadAccessToken. (SigV4 callers use GetWorkloadAccessToken; the opaque user-id header path uses GetWorkloadAccessTokenForUserId.)
3. Outbound: the agent uses that Workload Access Token to call the token vault via bedrock-agentcore:GetResourceOauth2Token. For 3LO, the vault generates the provider's authorization URL.
4. Consent: the agent surfaces the URL (via the on_auth_url callback); the user grants consent in their browser.
5. Storage: Identity caches the downstream token in the vault, keyed by (agent workload identity + user id), so future calls skip the consent step until the token expires.

Under the hood the decorator orchestrates three APIs: CreateWorkloadIdentity, GetWorkloadAccessToken, and GetResourceOauth2Token. You rarely call them directly — the SDK decorator runs the whole sequence and injects the resulting token as a kwarg:

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 — user-delegated
    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 here — it never enters the model's context
    ...

The key property: the raw token is delivered straight into your business logic as the access_token argument and never touches the LLM context.

Outbound auth comes in exactly two legged-OAuth shapes, and the only knob you flip is the decorator's auth_flow:

2LO (Client Credentials / M2M). The agent authenticates as itself — there is no end user in the loop. Pick this for machine-to-machine calls where the downstream resource trusts the agent's own identity.

@requires_access_token(
    provider_name="internal-api-provider",
    scopes=["orders:read"],
    auth_flow="M2M",                 # 2LO — agent acts as itself, no consent URL
)
async def fetch_orders(*, access_token: str):
    ...

3LO (Authorization Code). The agent acts on behalf of a user who consents via an authorization URL. This is the flow for user-scoped data in Google, GitHub, Slack, and similar. Crucially, AgentCore stores both the access token and the refresh token and auto-refreshes them, which is what minimizes consent fatigue — the user grants access once and subsequent calls reuse the cached, refreshed token until it can no longer be renewed.

The selection is per-decorated-function, so one agent can do M2M to an internal API and USER_FEDERATION to Google within the same codebase.

3LO only minimizes consent fatigue if the provider issues a refresh token. Most OAuth providers do not hand one out by default — you have to opt in, and the switch is different for every vendor. These settings are volatile (providers change their consoles); treat the list as a starting point and verify against the live provider docs and the AgentCore resource-providers page.

For Google, the offline access-type rides along in the decorator's custom_parameters:

@requires_access_token(
    provider_name="google-provider",
    scopes=["https://www.googleapis.com/auth/drive.metadata.readonly"],
    auth_flow="USER_FEDERATION",
    custom_parameters={"access_type": "offline"},   # Google must be told to issue a refresh token
    on_auth_url=lambda url: stream_to_client(url),
)
async def read_from_google_drive(*, access_token: str):
    ...

Tokens are not guaranteed to stay valid. A provider can revoke a token (user changed password, admin pulled the app, rotation kicked in). When a cached token fails, force a fresh consent by setting force_authentication=True, which bypasses the cache and re-runs the authorization flow:

@requires_access_token(
    provider_name="google-provider",
    scopes=["https://www.googleapis.com/auth/drive.metadata.readonly"],
    auth_flow="USER_FEDERATION",
    force_authentication=True,        # bypass the cached/expired token, re-prompt for consent
    on_auth_url=lambda url: stream_to_client(url),
)
async def read_from_google_drive(*, access_token: str):
    ...

The token vault is the secure credential store at the center of Outbound Auth. It holds:

• OAuth access tokens and refresh tokens
• OAuth client credentials
• API keys (static keys for services like OpenAI, fetched with the @requires_api_key decorator)

Three properties make it production-grade:

1. Encryption everywhere. Credentials are encrypted at rest and in transit using AWS KMS — either a service-managed key or your own customer-managed key (CMK) if you need control over the key policy and rotation.
2. Strict per-(agent identity + user id) isolation. Every credential is keyed to a specific (agent workload identity, user id) pair, giving zero token sharing across agents or across users. User A's Google token is unreachable by user B, and your billing agent's tokens are unreachable by your support agent.
3. Independent validation. Every access request to the vault is validated on its own — there is no ambient "already authenticated" trust.

And the cardinal rule that ties it all together: tokens are never embedded in code or config, and never exposed to the LLM context. The decorator pulls the credential from the vault and injects it directly into your function as the access_token (or api_key) argument; it does not flow through the prompt.

Agent  --GetResourceOauth2Token-->  Token Vault  (KMS-encrypted)
                                       |  keyed by (agent identity + user id)
  <--access_token injected as kwarg----+  zero token sharing

Because isolation is per-(agent + user), the same physical vault safely serves a multi-tenant agent: each user's downstream tokens are partitioned, and revoking or rotating one user's grant never touches another's.

How the agent's execution role is allowed to fetch the Workload Access Token changed at GA, and this is a volatile fact tied to a specific date — verify the live runtime-oauth page before relying on it.

Agents created before Oct 13 2025 need the workload-token actions granted explicitly in the execution role:

{
  "Version": "2012-10-17",
  "Statement": [{
    "Effect": "Allow",
    "Action": [
      "bedrock-agentcore:GetWorkloadAccessToken",
      "bedrock-agentcore:GetWorkloadAccessTokenForJWT",
      "bedrock-agentcore:GetWorkloadAccessTokenForUserId"
    ],
    "Resource": [
      "arn:aws:bedrock-agentcore:<region>:<account>:workload-identity-directory/default",
      "arn:aws:bedrock-agentcore:<region>:<account>:workload-identity-directory/default/workload-identity/agentname-*"
    ]
  }]
}

Agents created on or after Oct 13 2025 rely instead on a Service-Linked Role (SLR) named AWSServiceRoleForBedrockAgentCoreRuntimeIdentity (trusted principal runtime-identity.bedrock-agentcore.amazonaws.com). You no longer hand-write the GetWorkloadAccessToken* grants — the SLR carries them. The caller creating the runtime via the control API just needs iam:CreateServiceLinkedRole for that service so the role can be provisioned.

Keep the two planes straight: IAM governs AWS-level access — the control/data-plane APIs, credential-provider creation, KMS, and the execution role (SigV4 is one inbound option). Identity governs the agent/workload identity — the directory, the token vault, and OAuth 2LO/3LO to non-AWS services. The key IAM actions you will see across outbound auth are GetWorkloadAccessToken* (the exchange) and GetResourceOauth2Token (the vault call); InvokeAgentRuntime / InvokeAgentRuntimeForUser sit on the inbound side.