AWS bedrock-agentcore documentation change
Summary
Added documentation for scope advertisement in authentication challenges, detailing how JWT-authorized gateways return WWW-Authenticate headers with OAuth scope information for 401 and 403 errors.
Security assessment
This change documents a security feature (OAuth scope advertisement in authentication challenges) that follows RFC 6750 and RFC 9728 standards. It enhances security by enabling clients to automatically discover required scopes for token acquisition, improving authentication flows. However, there is no evidence this addresses a specific security vulnerability or incident.
Diff
diff --git a/bedrock-agentcore/latest/devguide/gateway-inbound-auth.md b/bedrock-agentcore/latest/devguide/gateway-inbound-auth.md index 85e3acb6f..d15a64f07 100644 --- a//bedrock-agentcore/latest/devguide/gateway-inbound-auth.md +++ b//bedrock-agentcore/latest/devguide/gateway-inbound-auth.md @@ -105,0 +106,2 @@ You can use the AgentCore CLI to set up a default JWT, or create one manually wi + * Scope advertisement in authentication challenges + @@ -154,0 +157,15 @@ You’ll need these values to do the following: +### Scope advertisement in authentication challenges + +When a client sends a request to a JWT-authorized gateway without a valid access token, the gateway returns an error response with a `WWW-Authenticate` header that advertises the required OAuth scopes. This follows the [RFC 6750 Bearer token challenge](https://datatracker.ietf.org/doc/html/rfc6750#section-3) format and enables MCP-compliant clients to automatically discover the scopes needed for token acquisition. + +The gateway returns the following responses depending on the error: + + * **401 Unauthorized** – The request has no token or an invalid token. The `WWW-Authenticate` header includes `resource_metadata` and `scope` parameters. + + * **403 Forbidden** – The token is valid but does not contain the required scopes. The `WWW-Authenticate` header includes `error="insufficient_scope"`, `scope`, and `resource_metadata` parameters. + + + + +The `scope` value contains the space-delimited scopes configured as **Allowed scopes** in the gateway’s [CustomJWTAuthorizerConfiguration](https://docs.aws.amazon.com/bedrock-agentcore-control/latest/APIReference/API_CustomJWTAuthorizerConfiguration.html). The `resource_metadata` value points to the gateway’s [OAuth Protected Resource Metadata](https://datatracker.ietf.org/doc/html/rfc9728) document at `/.well-known/oauth-protected-resource`, which clients can fetch to discover the authorization server and supported scopes. +