Inbound Auth

Inbound auth is the bouncer at the door: it authenticates and authorizes the caller invoking your agent runtime. AgentCore Identity gives you exactly two mechanisms, and a single runtime version can wear only one of them:

• IAM SigV4 (the default). Callers sign the request with AWS credentials. Authorization is governed by the IAM action bedrock-agentcore:InvokeAgentRuntime. This is the right call for service-to-service traffic inside AWS, where the caller already has a role.
• JWT Bearer (OAuth 2.0 / OIDC). Callers present a bearer token in an Authorization header. A customJWTAuthorizer you attach at create time validates the token against your identity provider. This is the right call when end users (web/mobile apps, third-party clients) need to reach the agent directly.

The rule that trips everyone up: a runtime version supports either SigV4 OR JWT, not both. If a version has a customJWTAuthorizer, it is JWT-only; if it has none, it is SigV4-only. There is no "accept either" mode on one version.

The escape hatch is the runtime's version/endpoint model. CreateAgentRuntime auto-creates Version 1 and a DEFAULT endpoint; each update creates a new immutable version. So if you genuinely need both auth styles — say, internal SigV4 callers and external OAuth users hitting the same agent code — you deploy two versions (or two runtimes) of the same container, one configured for SigV4 and one for JWT, and route callers to the appropriate ARN/qualifier.

If you say nothing about authorization at create time, your runtime is SigV4-protected. Callers must sign their InvokeAgentRuntime requests with AWS credentials, and whether the call is allowed comes down to one IAM action: bedrock-agentcore:InvokeAgentRuntime.

Invoking a SigV4 runtime is exactly the boto3 path you'd expect — the data-plane client is bedrock-agentcore, and SigV4 signing happens transparently:

import boto3, json

# Data-plane client: bedrock-agentcore.{region}.amazonaws.com
client = boto3.client("bedrock-agentcore", region_name="us-east-1")

resp = client.invoke_agent_runtime(
    agentRuntimeArn="arn:aws:bedrock-agentcore:us-east-1:111122223333:runtime/HelloAgent-abc123",
    runtimeSessionId="a-unique-session-id-at-least-33-characters-long",  # >= 33 chars
    payload=json.dumps({"prompt": "Hello"}).encode("utf-8"),
    qualifier="DEFAULT",
)
# The response field is an iterable of byte chunks; join + decode them.
print("".join(c.decode("utf-8") for c in resp.get("response", [])))

Least-privilege IAM for the caller (the principal that invokes the agent) looks like this — note you scope it to the specific runtime ARN, not *:

{
  "Version": "2012-10-17",
  "Statement": [{
    "Effect": "Allow",
    "Action": "bedrock-agentcore:InvokeAgentRuntime",
    "Resource": "arn:aws:bedrock-agentcore:us-east-1:111122223333:runtime/HelloAgent-abc123"
  }]
}

How a SigV4 auth failure looks on the wire matters for debugging. A SigV4 agent that rejects a caller returns HTTP 403 with ACCESS_DENIED and — importantly — no WWW-Authenticate header. That absence is the quick tell that you're on a SigV4 endpoint, not a JWT one (JWT failures behave differently, as we'll see next).

To accept OAuth/OIDC bearer tokens instead, you attach a customJWTAuthorizer in the authorizerConfiguration when you call create_agent_runtime on the control-plane client (bedrock-agentcore-control):

import boto3
client = boto3.client("bedrock-agentcore-control", region_name="us-east-1")

client.create_agent_runtime(
    agentRuntimeName="HelloAgent",
    agentRuntimeArtifact={
        "containerConfiguration": {"containerUri": "...ecr.../my-agent:latest"}
    },
    authorizerConfiguration={"customJWTAuthorizer": {
        "discoveryUrl": "COGNITO_DISCOVERY_URL",
        "allowedClients": ["COGNITO_CLIENT_ID"]
    }},
    networkConfiguration={"networkMode": "PUBLIC"},
    roleArn="arn:aws:iam::111122223333:role/AgentRuntimeRole",
    lifecycleConfiguration={"idleRuntimeSessionTimeout": 300, "maxLifetime": 1800},
)

The authorizer validates incoming JWTs against these fields:

You typically provide either allowedClients or allowedAudience (plus optionally allowedScopes and any required custom claims), depending on how your IdP populates the token. The discoveryUrl is always required — that is how AgentCore discovers the issuer's signing keys and validates the iss.

Any standards-compliant OIDC provider works as the inbound IdP: Cognito, Microsoft Entra ID, Okta, Auth0, Keycloak, or PingFederate. The dossier example uses Cognito; the config shape is identical for the others — you just point discoveryUrl at that provider's .well-known/openid-configuration.

Here is the single most surprising thing about JWT inbound auth: the boto3 bedrock-agentcore client cannot invoke a JWT/bearer-protected agent. boto3 always SigV4-signs the request; it has no notion of attaching an Authorization: Bearer <jwt> header. So you must drop down to a plain HTTPS client and build the request by hand.

Two things make the raw request unusual:

1. The agent runtime ARN is URL-encoded into the request path (not passed as a parameter).
2. You pass the OAuth token in the standard Authorization: Bearer <jwt> header — no AWS signing at all.

import requests, urllib.parse, json

region = "us-east-1"
agent_arn = "arn:aws:bedrock-agentcore:us-east-1:111122223333:runtime/HelloAgent-abc123"
escaped_arn = urllib.parse.quote(agent_arn, safe="")  # ARN URL-encoded into the path

url = (
    f"https://bedrock-agentcore.{region}.amazonaws.com"
    f"/runtimes/{escaped_arn}/invocations?qualifier=DEFAULT"
)

resp = requests.post(
    url,
    headers={
        "Authorization": f"Bearer {bearer_token}",          # the OAuth/OIDC JWT
        "Content-Type": "application/json",
        "X-Amzn-Bedrock-AgentCore-Runtime-Session-Id": session_id,  # >= 33 chars
    },
    data=json.dumps({"prompt": "Hello"}),
)
print(resp.status_code, resp.text)

Reading an auth failure. A JWT/OAuth agent that rejects you returns HTTP 401 with a WWW-Authenticate: Bearer header that points at the agent's Protected Resource Metadata (PRM) endpoint:

HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer resource_metadata="https://.../.well-known/oauth-protected-resource?qualifier={QUALIFIER}"

That PRM endpoint (.well-known/oauth-protected-resource, exposed by the control API GetRuntimeProtectedResourceMetadata) tells a client which authorization server to go get a token from. Contrast this with SigV4, which fails with 403 ACCESS_DENIED and no WWW-Authenticate header — a one-glance way to tell which kind of door you hit.

Sometimes you want per-user behavior (per-user memory, per-user outbound tokens) but the caller is a trusted backend authenticating with SigV4, not the end user with a JWT. For that, AgentCore offers the X-Amzn-Bedrock-AgentCore-Runtime-User-Id header: the SigV4 caller asserts which user this request is for, and AgentCore derives a workload identity for that user via GetWorkloadAccessTokenForUserId.

This is real delegation, so it is gated by an extra IAM action beyond the normal invoke permission:

{
  "Version": "2012-10-17",
  "Statement": [{
    "Effect": "Allow",
    "Action": "bedrock-agentcore:InvokeAgentRuntimeForUser",
    "Resource": "arn:aws:bedrock-agentcore:us-east-1:111122223333:runtime/HelloAgent-abc123"
  }]
}

resp = client.invoke_agent_runtime(
    agentRuntimeArn=agent_arn,
    runtimeSessionId=session_id,
    payload=payload,
    # The asserted user id — opaque and UNVERIFIED by AgentCore.
    # Must be derived from YOUR authenticated principal, never raw client input.
    runtimeUserId="user-7f3c",  # surfaces as X-Amzn-Bedrock-AgentCore-Runtime-User-Id
)

Why this is dangerous if you're sloppy. The user-id value is an opaque, unverified identifier — AgentCore does not check that the caller "really is" that user; it trusts the asserting principal. If you let untrusted input flow into this header, a caller can impersonate any user. Treat it with the discipline its power demands:

• Restrict the action. Grant bedrock-agentcore:InvokeAgentRuntimeForUser only to specific, trusted principals and only on specific runtimes. Explicitly Deny it everywhere delegation isn't needed.
• Derive the user-id from the authenticated principal in your backend — never pass a value supplied directly by an end client.
• Audit it. CloudTrail records the runtimeUserId, so you can review who delegated as whom.
• Prefer JWT in production. When the end user can authenticate directly, a validated JWT (with a real, signed sub) is strictly safer than a backend asserting an unverified id.