Check an Amazon Bedrock AgentCore Gateway MCP endpoint's OAuth setup: Cognito, Okta, Auth0 or Entra ID JWT authorizers, RFC 9728 metadata, CloudFront domainOverride.
Amazon Bedrock AgentCore Gateway turns APIs, Lambda functions and other targets into a single MCP endpoint that agents can call. Every gateway is a remote MCP server, and every remote MCP server has the same first question: what does it say to a caller who shows up with no token?
This post maps the four inbound authorization modes of AgentCore Gateway to what an outside caller can observe, walks the OAuth discovery chain for a JWT-protected gateway with curl, and lists the checks worth running before you hand the gateway URL to an agent. It is based on the AgentCore Gateway inbound authorization documentation; check that page for the current field names, since the service is new and changes quickly.
The gateway endpoint #
An AWS-managed gateway URL has this shape:
https://<gateway-id>.gateway.bedrock-agentcore.<region>.amazonaws.com/mcp
MCP traffic goes to /mcp. For a JWT-protected gateway, the OAuth metadata lives at /.well-known/oauth-protected-resource on the same host.
Four inbound modes, four different views from outside #
The authorizerType you choose when creating the gateway decides what an unauthenticated caller sees.
authorizerType |
What the gateway checks | What an unauthenticated scan can observe |
|---|---|---|
CUSTOM_JWT |
A bearer token, validated against the identity provider's discovery URL, plus allowed clients, audience and scopes | A 401 with aWWW-Authenticate challenge and a link to protected resource metadata, so the whole discovery chain is testable |
IAM |
A SigV4 signature, and the bedrock-agentcore:InvokeGateway permission on the gateway ARN |
Requests must be signed, so an unsigned scan cannot list tools |
AUTHENTICATE_ONLY |
A valid SigV4 signature, with no authorization decision of its own | Same as IAM : signed requests only |
NONE |
Nothing | tools/list answers anonymously |
Only the first and last rows are visible to a passive, unauthenticated check. The NONE row is the one to look at twice. The AWS documentation is explicit that with NONE the gateway enforces nothing and authorization has to live in a policy engine, an interceptor Lambda function or the downstream target. If none of those exist, any caller reaches your targets.
Walking the discovery chain for a JWT gateway #
For a CUSTOM_JWT gateway, AWS documents that a request without a valid token gets a 401 whose WWW-Authenticate header carries resource_metadata and scope parameters, following the RFC 6750 Bearer challenge format. A valid token that lacks the required scopes gets a 403 with error="insufficient_scope".
Step 1: send an unauthenticated MCP request and read the headers.
curl -si -X POST https://<gateway-id>.gateway.bedrock-agentcore.<region>.amazonaws.com/mcp \
-H 'content-type: application/json' \
-H 'accept: application/json, text/event-stream' \
-d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"probe","version":"0"}}}'
You want a 401 and a WWW-Authenticate: Bearer ... resource_metadata="..." scope="..." header.
Step 2: fetch the protected resource metadata named in resource_metadata (RFC 9728).
curl -s https://<gateway-id>.gateway.bedrock-agentcore.<region>.amazonaws.com/.well-known/oauth-protected-resource | jq
This document names the resource and the authorization_servers.
Step 3: fetch the authorization server's metadata (RFC 8414 or OpenID Connect discovery) from each listed server, for example <issuer>/.well-known/openid-configuration. For an Amazon Cognito user pool that is the pool's issuer URL plus that path; for Okta, Auth0 or Microsoft Entra ID it is the tenant's issuer.
The chain is the same one covered in how to debug an MCP server that returns 401. What is specific to AgentCore is how the gateway is configured behind the scenes: the discoveryUrl in the gateway's customJWTAuthorizer is where the gateway fetches the identity provider's metadata, and allowedClients and allowedAudience decide which tokens it accepts.
The checks worth running #
The MCP Inspector runs this chain automatically and reports what the endpoint publishes. For an AgentCore gateway, these are the findings that matter:
- A challenge with
resource_metadata. Without it, an MCP client has no standard way to find the authorization server. - The authorization server is the one you configured. The protected resource metadata names the issuer clients will send credentials to. It should be the identity provider behind the gateway's
discoveryUrl, and nothing else. Clients should pin that issuer rather than trust whatever the server advertises; seePin the Issuer for why. - The
resourcehost matches the endpoint host. This one catches a real AgentCore deployment pattern, covered in the next section. - Scopes are published. The gateway advertises its allowed scopes in the challenge. If neither the challenge nor the metadata lists any, a reviewer cannot tell what a token would carry.
- OpenID Connect or bare OAuth 2.0. Whether the authorization server publishes
/.well-known/openid-configurationor only OAuth 2.0 metadata decides whether you can map standard identity claims. The inspector also reads the server's published metadata for PKCE with S256, pushed authorization requests, and DPoP, and reports each as published or not published. That is a read of published metadata, not a conformance test. - Anonymous tool inventory for
NONEgateways. Iftools/listanswers without a token, the inspector lists the tools it returned and marks the view as anonymous.
The CloudFront and domainOverride case #
Many teams put a custom domain or CloudFront in front of a gateway. AWS documents what happens next: by default the gateway advertises its AWS-managed hostname in the protected resource metadata and in WWW-Authenticate challenges. A client calling https://mcp.example.com/mcp is then told the resource lives at <gateway-id>.gateway.bedrock-agentcore.<region>.amazonaws.com, and OAuth discovery or token validation can fail.
The fix is the gateway's domainOverride setting, with the proxy setting the x-amzn-bedrock-agentcore-gateway-domain header to the public hostname and overwriting any copy the client sent. Because the metadata names a host and the request went to another, this is directly observable from outside: the inspector flags it when the protected resource metadata names a different host than the MCP endpoint that issued the challenge. Path differences are not flagged, since a resource at the origin and an endpoint at /mcp is normal.
What an outside scan cannot see #
Be clear about the limits before you treat a clean scan as a clearance:
- Token acceptance.
allowedClients,allowedAudienceand required scopes are checked server-side on a real token. A passive scan sees none of them. A gateway that accepts tokens with a broad audience looks the same as a strict one. - Token passthrough. AWS notes that with
JWT_PASSTHROUGHoutbound authorization the same token is accepted by both the gateway and the target, so each token'saudshould be scoped to the intended resource. Whether your tokens are scoped that way is a property of your identity provider, not of the gateway's public metadata. - IAM-protected gateways. The inspector does not sign SigV4 requests, so it cannot inventory tools behind
IAMorAUTHENTICATE_ONLY. - Private identity providers. A
customJWTAuthorizercan use aprivateEndpointfor an identity provider inside your VPC. Its metadata is not reachable from the public internet, so a public scan cannot read it. - Policy engines and interceptors. Authorization offloaded to a policy engine or an interceptor Lambda function is invisible from outside.
- Per-caller tool lists. The MCP specification lets servers return different tools to different callers. A scan without a token shows the anonymous view only.
A short pre-launch checklist #
- Pick the mode on purpose. Production gateways should be
CUSTOM_JWTorIAM, with a policy engine or interceptor whereAUTHENTICATE_ONLYorNONEis used. - Send the unauthenticated request. Confirm the
401, theresource_metadataparameter and thescopeparameter. - Fetch the protected resource metadata. Confirm the
resourcehost is the host your clients call. - Fetch the authorization server metadata. Confirm the issuer is your identity provider and that it publishes the endpoints and PKCE method your clients need.
- Scope tokens to the gateway's audience, and prefer on-behalf-of token exchange over passthrough for production, as the AWS documentation recommends.
- Re-run the check after every change to the identity provider, the proxy or the gateway configuration.
Scan a gateway URL to see what it publishes today.
Follow Trango Compute on LinkedIn
We post updates on new tools, context engineering patterns, and LLM cost research.