View a markdown version of this page

📢 แจ้งเตือน: bedrock agentcore/latest/devguide/gateway inbound auth.html - Kapook Update 2025

Set up inbound authorization for your gateway

Before you create your gateway, you must set up inbound authorization. Inbound authorization validates users who attempt to access targets through your AgentCore gateway. AgentCore supports the following types of inbound authorization:

  • JSON Web Token (JWT) – A secure and compact token used for authorization. After creating the JWT, you specify it as the authorization configuration when you create the gateway. You can create a JWT with any of the identity providers at Provider setup and configuration.

  • IAM identity – Authorizes through the credentials of the AWS IAM identity trying to access the gateway.

  • Offloaded authorization types – The gateway makes no authorization decision of its own and instead offloads authorization to another component, such as the downstream target, a policy engine attached to the gateway, or an interceptor Lambda function. This category includes Authenticate only and No Authorization. For details and guidance, see Offloaded inbound authorization.

Note

Create or select an identity provider before you use the AgentCore CLI to add a gateway with JWT authorization.

Select the topic that corresponds to the type of authorization that you plan to use to learn how to set it up:

IAM-based inbound authorization

IAM-based inbound authorization lets you use the gateway caller’s IAM credentials for authorization. You can use this option if you want to create an IAM identity through which users that call your gateway can be authenticated.

To set up IAM-based inbound authorization

  1. Create or use an existing IAM identity for your gateway callers.

  2. Create an identity-based IAM policy that contains the following permissions:

    • bedrock-agentcore:InvokeGateway – After you create the gateway, you should modify this policy such that the Resource field is scoped to the gateway that you create as a security best practice.

  3. Attach the policy to the gateway caller identity.

Example policy

The following example shows a policy you could attach to an identity to allow it to invoke a gateway with the ID my-gateway-12345

{ "Version": "2012-10-17", "Statement": [ { "Sid": "AllowGatewayInvocation", "Effect": "Allow", "Action": [ "bedrock-agentcore:InvokeGateway" ], "Resource": [ "arn:aws:bedrock-agentcore:us-east-1:123456789012:gateway/my-gateway-12345" ] } ] }

Resources

JSON Web Token (JWT)-based inbound authorization

A JSON Web Token (JWT) is a secure and compact token used for authorization. You can create a JWT with a supported identity provider. After you create a JWT, you can retrieve it and specify it as the authorization configuration when you create the gateway.

Important

Using inbound authorization based on JWT tokens will result in logging of some claims of the JWT token in CloudTrail. The entry includes the Subject of the provided web identity token. We recommend that you avoid using any personally identifiable information (PII) in this field. For example, you could instead use a GUID or a pairwise identifier, as suggested in the OIDC specification.

You can use the AgentCore CLI to configure a gateway with an existing JWT identity provider. To learn more about JWT configuration methods, select from the following topics:

Configure a JWT authorizer

Create an application and client with a supported identity provider. For an Amazon Cognito example, see Get started with Amazon Cognito. Note the OpenID Connect (OIDC) or OAuth 2.0 Authorization Server Metadata (RFC 8414) discovery URL and client ID.

Run the following command in an AgentCore project directory:

agentcore add gateway \ --name MyGateway \ --protocol-type MCP \ --authorizer-type CUSTOM_JWT \ --authorizer-configuration '{ "customJwtAuthorizer": { "discoveryUrl": "<DISCOVERY_URL>", "allowedClients": ["<CLIENT_ID>"] } }'

The AgentCore CLI uses the configuration of your existing identity provider. To invoke the gateway, obtain an access token from your provider. For Amazon Cognito, see The token issuer endpoint in the Amazon Cognito Developer Guide.

Set up a JWT manually

Amazon Bedrock AgentCore supports JWTs from all identity providers. You can see some examples at Provider setup and configuration.

In the process of creating the JWT, take note of the following values, which you’ll fill out in the CustomJWTAuthorizerConfiguration when you create a gateway, if they’re applicable to your use case:

  • Discovery URL – The URL from which login credentials and the token endpoint can be retrieved.

  • Client ID – The public identifier of a client application that requests a token, validated against the client_id claim.

  • Client secret – The private key that authenticates access for the client application to retrieve a token.

  • Allowed audience – The identifier that validates the intended recipients or consumers of a token via the aud claim.

  • Allowed scopes – The scopes that define the limitations of an application’s access to a user’s account. For more information, see OAuth Scopes.

  • Other required claim values – Depending on the authorizer you use, you might need to specify required custom claim fields and rules to match the claim field value to for authentication.

You’ll need these values to do the following:

  • Create the gateway by specifying values in the authorizer configuration.

  • Obtain authorization credentials to invoke the gateway. To learn how to obtain your credentials, look up your identity provider’s documentation. For example, if you used Amazon Cognito, see The token issuer endpoint in the Amazon Cognito Developer Guide.

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 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. The resource_metadata value points to the gateway’s OAuth Protected Resource Metadata document at /.well-known/oauth-protected-resource, which clients can fetch to discover the authorization server and supported scopes.

Advertise a custom domain for gateways behind a proxy

With a proxy in front of your gateway, you can provide a custom domain or edge security. For example, you might use Amazon CloudFront. The public URL that clients call then differs from the AWS managed gateway URL. Clients might call https://mcp.example.com/mcp, while the AWS managed URL is https://gateway-id.gateway.bedrock-agentcore.region.amazonaws.com/mcp.

By default, your gateway advertises its AWS managed hostname in its OAuth Protected Resource Metadata and in WWW-Authenticate authentication challenges. Clients that call through a proxy then see a different hostname than the one they called, so OAuth discovery or token validation might fail. To advertise the public domain instead, configure the domainOverride setting. This setting applies to CUSTOM_JWT gateways.

The domainOverride setting

You provide domainOverride when you create or update a gateway with CreateGateway or UpdateGateway, and GetGateway returns it. It is a top-level gateway configuration field, a sibling of the authorizer configuration.

The setting contains the following values:

default

(Required) The public domain that the gateway advertises. If you have one public domain, set only this value.

alternateDomains

(Optional) A list of up to 10 additional public domains that the gateway can advertise. If you have more than one public domain, add the others here.

The following rules apply to the values:

  • The default domain must not also appear in alternateDomains.

  • Use hostnames only. Do not include a scheme, path, or credentials.

The following example configures a default public domain and one alternate domain:

{ "domainOverride": { "default": "mcp.example.com", "alternateDomains": [ "mcp-eu.example.com" ] } }

For the complete request syntax, see CreateGateway in the Amazon Bedrock AgentCore Control API Reference.

Identify the public domain for each request

The proxy forwards requests to the AWS managed gateway hostname for routing. The gateway therefore cannot infer which public URL the client used. Your proxy identifies the public domain for each request by setting the x-amzn-bedrock-agentcore-gateway-domain request header to the public hostname.

The gateway resolves the domain to advertise in the following order:

  1. If the x-amzn-bedrock-agentcore-gateway-domain header is present and exactly matches default or an entry in alternateDomains, the gateway uses that value.

  2. If the header is absent, the gateway uses default.

  3. If the header is present but matches neither default nor an entry in alternateDomains, the gateway returns a 4xx response. The gateway does not accept or silently ignore the value.

After it selects the domain, the gateway builds its endpoint URLs as before. It uses HTTPS and appends /mcp for the MCP resource, with the selected public hostname. In this example, the header is x-amzn-bedrock-agentcore-gateway-domain: mcp.example.com. The gateway advertises the public OAuth resource https://mcp.example.com/mcp. It points clients to the OAuth metadata location https://mcp.example.com/.well-known/oauth-protected-resource. The domain cannot include a custom path. The MCP endpoint path is the default /mcp.

Your proxy should send the header only for requests that arrive on an alternate domain. The header selects an owner-approved domain from the configured values. It does not authorize an arbitrary value. Your proxy must also continue to forward requests to the AWS managed gateway hostname. The domainOverride setting and the header change only the URLs that the gateway advertises, not request routing.

Overwrite the caller-supplied domain header

Your proxy must set the x-amzn-bedrock-agentcore-gateway-domain header itself and remove any copy of it that the client sent, before it forwards the request. Otherwise, a client could set the header and choose which of your configured domains the gateway advertises for the request.

Backward compatibility

The domainOverride setting is optional. When you do not configure it, the gateway keeps its current AWS managed hostname behavior, so existing gateways are unchanged. A configured domainOverride does not require every request to carry the header. Without the header, the gateway uses default.

Remove or change the setting

UpdateGateway uses full-replacement semantics:

  1. To remove all overrides, send an update request without domainOverride.

  2. To change the default, or to add or remove an alternate domain, send the complete replacement domainOverride with the new default and alternateDomains.

Identity provider configuration

Configuring domainOverride changes only what the gateway advertises to OAuth clients. It does not change how the gateway validates tokens. Identity providers differ in whether they use the requested resource URL as the token audience. Make sure that your identity provider accepts the advertised resource URL and issues a token for it. That token works only if its claims, such as its audience, match the gateway’s allowed audience or allowed clients configuration, so confirm that the configuration accepts them.

Use a private (VPC-hosted) identity provider

AgentCore Gateway supports JWT-based inbound authorization with identity providers hosted inside your VPC. You can configure a privateEndpoint on the customJWTAuthorizer to enable AgentCore to reach your private discovery, token, and JWKS endpoints without exposing them to the public internet.

Your IAM principal must have the iam:CreateServiceLinkedRole permission for identity-network.bedrock-agentcore.amazonaws.com, so that AgentCore Identity can create the AWSServiceRoleForBedrockAgentCoreIdentity service-linked role on your behalf if it does not already exist.

The privateEndpoint applies to the domain in the discoveryUrl. If your identity provider uses different domains for other endpoints (for example, the token or JWKS endpoint resolves to a different domain than the discovery URL), use privateEndpointOverrides to specify a separate private endpoint configuration for each additional domain.

The following example creates a gateway with a private identity provider using managed Lattice:

{ "name": "my-private-idp-gateway", "protocolType": "MCP", "roleArn": "arn:aws:iam::123456789012:role/my-gateway-role", "authorizerType": "CUSTOM_JWT", "authorizerConfiguration": { "customJWTAuthorizer": { "allowedAudience": [ "my-audience" ], "discoveryUrl": "https://my-idp.internal.example.com/.well-known/openid-configuration", "privateEndpoint": { "managedVpcResource": { "vpcIdentifier": "vpc-0abc123def456", "subnetIds": ["subnet-0abc123", "subnet-0def456"], "endpointIpAddressType": "IPV4", "securityGroupIds": ["sg-0abc123def"] } } } } }

If your token or JWKS endpoints use a different domain than the discovery URL, add a privateEndpointOverrides entry for each additional domain. privateEndpointOverrides is supported only with self-managed Lattice resources:

{ ... "authorizerConfiguration": { "customJWTAuthorizer": { "allowedAudience": ["my-audience"], "discoveryUrl": "https://my-idp.internal.example.com/.well-known/openid-configuration", "privateEndpoint": { "selfManagedLatticeResource": { "resourceConfigurationIdentifier": "arn:aws:vpc-lattice:us-east-1:123456789012:resourceconfiguration/rcfg-abc123" } }, "privateEndpointOverrides": [ { "domain": "my-token-server.internal.example.com", "privateEndpoint": { "selfManagedLatticeResource": { "resourceConfigurationIdentifier": "arn:aws:vpc-lattice:us-east-1:123456789012:resourceconfiguration/rcfg-def456" } } } ] } } }

For self-managed Lattice, cross-account setups, and advanced configurations, see Connect to private resources in your VPC using VPC Lattice. For a comprehensive guide covering both inbound and outbound private IdP scenarios, see Connect to private identity providers.

Offloaded inbound authorization

With offloaded inbound authorization, the gateway does not make any authorization decision of its own. Instead, it offloads authorization to another component:

  • The downstream target service, which authorizes the request it receives.

  • A policy engine attached to the gateway, which evaluates access policies.

  • An interceptor Lambda function, which runs your custom authentication or authorization logic before requests reach your targets.

AgentCore offers two offloaded types:

  • Authenticate only (AUTHENTICATE_ONLY) – The gateway verifies the caller’s SigV4 signature to authenticate the caller, but makes no authorization decision. Requests must be signed, but any authenticated caller is forwarded to the target.

  • No Authorization (NONE) – The gateway performs no inbound authentication or authorization. Requests can be unauthenticated, and any caller is forwarded to the target.

With either type, you decide where authorization is actually enforced:

  • Policy engine – Attach a policy engine to the gateway to evaluate access policies centrally. This is a recommended pattern for production gateways and is frequently used together with OAuth.

  • Interceptor Lambda function – Run your own authentication or authorization logic before requests reach your targets. This is recommended for production gateways when the built-in inbound authorization options do not meet your requirements.

  • Downstream target – Let the target enforce authorization on the request it receives. This is useful for experimentation and progressive onboarding — for example, putting a gateway in front of an existing runtime without changing the runtime’s authentication and authorization — so you can adopt gateway capabilities incrementally while the runtime continues to enforce the auth it already trusts.

Important

If you offload inbound authorization by choosing either AUTHENTICATE_ONLY or NONE, AgentCore Gateway does not enforce authorization on its own. In this scenario, you must offload authorization to a separate component — a policy engine, an interceptor Lambda function, or the downstream target — otherwise any caller can reach your target.

Authenticate-only authorization

With authenticate-only authorization (AUTHENTICATE_ONLY), the gateway verifies the caller’s Signature Version 4 (SigV4) signature to confirm their identity, but does not make any authorization decision of its own. Any authenticated IAM principal can invoke the gateway regardless of their permissions, and the request is forwarded to the target. Authorization is delegated to the downstream target service or to a policy engine attached to the gateway.

Important

With AUTHENTICATE_ONLY, the gateway does not enforce any authorization policies. Any valid SigV4-signed request will be forwarded to the target. Ensure that your downstream targets implement their own authorization logic, or attach a policy engine to the gateway to control access. Without proper authorization at the target or gateway policy level, any authenticated caller can reach your backend services.

No Authorization

You can create a gateway that is configured with no authorization by using authorizerType=NONE . The gateway will not perform any authorization on the incoming gateway request and the request can be unauthenticated.

Important

Do not use No Authorization gateways for production workloads unless you have implemented all the security best practices listed below. If you need custom authentication logic, consider using an interceptor Lambda function to handle authentication before requests reach your targets.

Security Best Practices

  1. Use the bedrock-agentcore:GatewayAuthorizerType condition key to selectively allow/deny access within your organization for creating gateways with authorizerType=NONE

  2. Do not use No Authorization gateways out of convenience for testing. They should be used for gateways you intend to make public but have implemented your own custom throttling rules and checks to ensure your public gateway can handle unauthenticated users

  3. Do not use No Authorization gateways with targets that may respond with sensitive information. Although targets are configured with their own authorization configurations, it is best to add another security layer on the gateway.

Onboard an existing runtime without changing its auth

When you pair an offloaded inbound type with a matching outbound authorization type that forwards the caller’s identity to the runtime, onboarding to a gateway can be as simple as setting an endpoint override on your existing client — no auth changes required:

  • IAM runtimes – Combine AUTHENTICATE_ONLY inbound authorization with Caller IAM credentials (CALLER_IAM_CREDENTIALS) outbound authorization. The gateway authenticates the SigV4 caller and then signs the request to the runtime with that same caller identity, so the runtime’s existing IAM authorization continues to apply unchanged. For more information, see Caller IAM credentials.

  • OAuth runtimes – Combine No Authorization inbound authorization with Token passthrough (JWT_PASSTHROUGH) outbound authorization. The gateway forwards the inbound JWT to the runtime without modification, so the runtime validates the token exactly as it does without the gateway. (Token passthrough forwards a bearer token, so it requires a JWT-bearing inbound type — JWT inbound authorization or NONE. It is not available with AUTHENTICATE_ONLY, which is SigV4-based and carries no bearer token.) For more information, see Token passthrough.

    Note

    Token passthrough (JWT_PASSTHROUGH) is not the recommended approach for production. When you forward the inbound token unchanged, the same token is accepted by both the gateway and the downstream target, so it should be tightly scoped — for example, each token’s audience (aud) should be restricted to the intended resource. The recommended pattern is on-behalf-of (OBO) token exchange, where the gateway exchanges the caller’s token for a fresh, audience-scoped token for the target instead of replaying the caller’s token. Use token passthrough for easy experimentation, testing, and onboarding, and move to OBO for long-term production workloads.

Warning

The identity-forwarding configurations in this section rely solely on the downstream runtime to authorize requests; the gateway adds no authorization of its own. They are intended for testing, experimentation, and low-disruption onboarding. For a production gateway, enforce authorization at the gateway — configure JWT or IAM inbound authorization, attach a policy engine, or use an interceptor Lambda function. To ensure callers cannot bypass the gateway once you adopt it, see Enforcing traffic through the gateway.