What an AgentCore JWT authorizer checks
A gateway or runtime with a JWT authorizer (customJWTAuthorizer) takes a bearer token in the Authorization header and checks it against your identity provider. A runtime accepts either JWT or IAM (SigV4), never both at once.
| Authorizer field | Token claim | Rule |
|---|---|---|
discoveryUrl | iss | Must end with /.well-known/openid-configuration; its issuer must equal the token's iss. Signature and expiry are checked with the provider's keys. |
allowedClients | client_id | One of the listed client IDs. |
allowedAudience | aud | One of the token's audiences is listed. |
allowedScopes | scope | The token has one of the scopes. |
| custom claims | any | The claim has the required value. |
Every field you set is checked, so set the one your provider's access tokens actually carry. Without a token the gateway and the runtime answer 401 with a WWW-Authenticate header pointing to their OAuth protected resource metadata (RFC 9728), where a client finds the identity provider. The AgentCore Error Decoder decodes a token you paste and compares its claims with these rules.
MCP clients and client registration
An MCP client that follows the MCP authorization spec signs the user in by itself: it reads the metadata, then registers as an OAuth client with Dynamic Client Registration (RFC 7591) or a Client ID Metadata Document. The gateway and the runtime do not register clients for your provider, and Amazon Cognito has no Dynamic Client Registration - so with Cognito you create an app client for the MCP client and give it the client ID yourself, with the client's redirect URI registered exactly:
| Client | Redirect URIs |
|---|---|
| Claude (claude.ai, Desktop) | https://claude.ai/api/mcp/auth_callbackhttps://claude.com/api/mcp/auth_callback |
| Claude Code | http://localhost:8080/callback |
| VS Code | http://127.0.0.1:33418https://vscode.dev/redirect |
| Cursor | http://localhost:8787/callbackhttps://www.cursor.com/agents/mcp/oauth/callback |
Claude takes the client ID in a custom connector's advanced settings, Claude Code with --client-id and a fixed --callback-port, VS Code asks for it when registration fails, and Cursor reads it from auth.CLIENT_ID in mcp.json. Some clients stop earlier, at discovery (an open issue, awslabs/agentcore-samples#1056, asks for the missing endpoints on the gateway). Two ways around it: an OAuth facade in front of the gateway that serves the metadata and registration the client expects, or a token in a static header - Claude Code, VS Code, Cursor and MCP Inspector all accept one.
Identity providers
| Provider | Discovery URL | Match its access tokens on |
|---|---|---|
| Amazon Cognito | https://cognito-idp.REGION.amazonaws.com/POOL_ID/.well-known/openid-configuration | allowedClients |
| Okta | https://TENANT.okta.com/oauth2/AUTH_SERVER_ID/.well-known/openid-configuration | allowedAudience |
| Microsoft Entra ID | https://login.microsoftonline.com/TENANT_ID/v2.0/.well-known/openid-configuration | allowedAudience |
| Auth0 | https://DOMAIN/.well-known/openid-configuration | allowedAudience |
With IAM there is no token: callers sign each request with SigV4 for the service bedrock-agentcore and need bedrock-agentcore:InvokeGateway or InvokeAgentRuntime. MCP clients cannot sign; the MCP Proxy for AWS runs as a local MCP server and signs with your AWS credentials.
Frequently asked questions
Is anything I choose sent anywhere?
No. The plan is put together in your browser. The page only counts that the planner was used, with which client, identity provider and first problem.
Can I call a JWT runtime with boto3 or the AWS CLI?
No. The AWS SDKs and CLI always sign with SigV4, and a runtime with a JWT authorizer rejects that with "Authorization method mismatch". Send an HTTPS request with the bearer token to the invocation URL - the runtime's ARN URL-encoded in the path - and a session ID of at least 33 characters in X-Amzn-Bedrock-AgentCore-Runtime-Session-Id.
How does the agent call tools as the signed-in user?
That is outbound authorization. The runtime exchanges the inbound token for a workload access token, and the agent asks AgentCore Identity for the tool's token on the user's behalf. Behind a gateway, the target's credential provider does it - the AgentCore Gateway Target Configurator shows which one each target takes.
References
Authenticate and authorize with Inbound Auth and Outbound Auth
Set up inbound authorization for your gateway
Deploy MCP servers in AgentCore Runtime
AgentCore Identity: provider setup and configuration
Claude: authentication for connectors
MCP Proxy for AWS