api_gateway target type rejects cognito_user_pools auth — only allows apiKey/awsSigv4

[olliewild]

Description

The api_gateway target type on AgentCore Gateway rejects API Gateway REST APIs that use COGNITO_USER_POOLS authorization. Target creation fails with:

Operation at path /api/customers/search method GET has unsupported auth type
'cognito_user_pools'. Only auth types [apiKey, awsSigv4] are supported

This is a creation-time validation issue — AgentCore reads the OpenAPI spec exported from the API Gateway stage and rejects any method whose auth type is not apiKey or awsSigv4.

Conflict between two AWS-recommended patterns

AWS recommends COGNITO_USER_POOLS as the standard authorization pattern for REST APIs where the backend needs user identity — Lambda handlers receive decoded JWT claims (email, name, groups) directly in event.requestContext.authorizer.claims. This is the documented pattern for web and mobile apps calling API Gateway.

AWS also recommends the api_gateway target type as the way to expose REST APIs as MCP tools via AgentCore Gateway. These two recommendations are incompatible — following both results in a creation-time failure.

At runtime, there is no conflict. REST APIs evaluate resource policies with OR logic against method-level authorizers (docs). A resource policy that allows the gateway role's SigV4 requests succeeds even though the methods have a Cognito authorizer. The Cognito authorizer continues to protect browser/SPA traffic. The creation-time validation is rejecting a configuration that would work correctly at runtime.

Reproduction

1. Create an API Gateway REST API with COGNITO_USER_POOLS authorization on methods
2. Add aws_api_gateway_method_response resources (required for valid OpenAPI export)
3. Add a resource policy allowing the gateway's IAM role
4. Create an AgentCore Gateway with CUSTOM_JWT auth
5. Create a gateway target with api_gateway target type and gateway_iam_role credential provider

resource "aws_bedrockagentcore_gateway_target" "api" {
  name               = "my-api"
  gateway_identifier = aws_bedrockagentcore_gateway.main.gateway_id

  credential_provider_configuration {
    gateway_iam_role {}
  }

  target_configuration {
    mcp {
      api_gateway {
        rest_api_id = aws_api_gateway_rest_api.main.id
        stage       = "prod"

        api_gateway_tool_configuration {
          tool_filter {
            filter_path = "/api/*"
            methods     = ["GET", "POST", "PUT"]
          }
          tool_override {
            path   = "/api/example"
            method = "GET"
            name   = "exampleTool"
          }
        }
      }
    }
  }
}

Result: Target creation fails with unsupported auth type 'cognito_user_pools'.

Expected: Target creation succeeds. AgentCore invokes via SigV4, resource policy allows the gateway role, Cognito authorizer is bypassed for IAM-authenticated requests per standard API Gateway evaluation logic.

Why switching to AWS_IAM is not a viable workaround

The obvious suggestion is to switch methods from COGNITO_USER_POOLS to AWS_IAM authorization (adding a Cognito Identity Pool for the frontend to obtain temporary credentials). But these serve different use cases:

• COGNITO_USER_POOLS is identity-centric — JWT claims (email, sub, groups) flow through to Lambda in event.requestContext.authorizer.claims. AWS recommends this for APIs where the backend needs to know who the user is.
• AWS_IAM + Identity Pool is permissions-centric — designed for clients that need temporary AWS credentials to call AWS services directly. User identity is not propagated natively; Lambda receives a cognitoIdentityId instead of claims.

Switching to AWS_IAM means every Lambda handler that reads user identity from the authorizer context (a standard pattern) would need to be rewritten to recover that information through other means (extra Cognito API calls, custom headers, etc.). This is not a simple migration — it changes the fundamental auth architecture of the application.

Other workaround

Use the open_api_schema target type with a hand-maintained OpenAPI spec that omits the Cognito auth annotations. AgentCore invokes via SigV4, and the resource policy allows it at runtime. This works but loses the auto-discovery benefit that makes the api_gateway target type attractive.

Environment

• Region: us-east-1
• terraform-provider-aws: v6.38.0
• Gateway auth: CUSTOM_JWT with Cognito User Pool
• Target credential provider: gateway_iam_role

Related

• Gateway missing MCP OAuth spec endpoints (RFC 8414, RFC 7591) - blocks Claude Desktop/claude.ai connector integration #1056 — Gateway missing RFC 8414/7591 endpoints (OAuth/DCR gaps with Cognito)