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:

If you don’t plan to use the default authorization configuration using Amazon Cognito, 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

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.

You can use the AgentCore CLI to set up a default JWT, or create one manually with a supported identity provider. To learn more about different methods for setting up a JWT, select from the following topics:

Set up a default JWT

The AgentCore CLI lets you easily create a default authorization configuration using Amazon Cognito that you can then use when creating a gateway. When you run agentcore create , the CLI prompts you to configure inbound authorization and can automatically set up a Amazon Cognito user pool for you.

agentcore create

After the command completes, the AgentCore CLI provides authentication and authorization information:

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:

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 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:

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.

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 OIDC 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. Currently, privateEndpointOverrides is only supported 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:

AgentCore offers two offloaded types:

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

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.

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.

Security Best Practices

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: