I Tried Validating Cognito and Firebase Tokens with a JWT Authorizer in API Gateway REST API

I Tried Validating Cognito and Firebase Tokens with a JWT Authorizer in API Gateway REST API

I tried JWT authorizers for Amazon API Gateway REST APIs with Cognito and Firebase Authentication tokens. Tokens from multiple identity providers can be validated through configuration alone, with no Lambda authorizer.
2026.11.18

This page has been translated by machine translation. View original

Introduction

On 2026-11-17, JWT authorizers became available for API Gateway REST APIs.

https://aws.amazon.com/jp/about-aws/whats-new/2026/11/amazon-api-gateway-rest-jwt-authorizers/

With a JWT authorizer, API Gateway validates the token's signature, issuer, audience, expiration, and claims.

In this article, I tested how JWT authorizers behave using tokens from Cognito and Firebase Authentication.

Test prerequisites

Test setup

I created the API in us-east-1 and the Cognito user pools in ap-northeast-1. I used two user pools as issuers. Pool A is the main one, and pool B was added as a second issuer in the multiple issuers section. In pool A, I created a resource server orders (with scopes read and write). The scope names that appear in the tokens are orders/read and orders/write. There are four kinds of app clients.

Name Purpose Scopes Authorizer audiences
rw Client credentials flow orders/read, orders/write Included from creation
ro Client credentials flow orders/read Included from creation
other Client credentials flow orders/read Not included
user User authentication (obtain an ID token and a user access token) - Added with update-authorizer before checking the ID token

The methods are as follows, and all integrations are MOCK.

  • GET /orders (scope orders/read)
  • POST /orders (scope orders/write)
  • GET /open (no scope)
  • GET /legacy (for checking conversion from a Cognito authorizer)
  • GET /cog (for comparison with a Cognito authorizer)

In pool B, I also created the resource server orders and one app client in the same way. The access tokens for rw, ro, and other were obtained with the client credentials flow, with a validity period of 5 minutes. How to write the token request is described in the AWS Compute Blog.

https://aws.amazon.com/blogs/compute/securing-rest-apis-with-jwt-authorizers-in-amazon-api-gateway/

Cognito setup commands
aws cognito-idp create-user-pool --pool-name jwt-verify-pool-a
aws cognito-idp create-resource-server --user-pool-id ap-northeast-1_<POOL_ID> --identifier orders --name orders --scopes ScopeName=read,ScopeDescription=read ScopeName=write,ScopeDescription=write
aws cognito-idp create-user-pool-domain --user-pool-id ap-northeast-1_<POOL_ID> --domain <DOMAIN_PREFIX>
aws cognito-idp create-user-pool-client --user-pool-id ap-northeast-1_<POOL_ID> --client-name jwt-verify-a-rw --generate-secret --allowed-o-auth-flows client_credentials --allowed-o-auth-flows-user-pool-client --allowed-o-auth-scopes orders/read orders/write --access-token-validity 5 --token-validity-units AccessToken=minutes
aws cognito-idp create-user-pool-client --user-pool-id ap-northeast-1_<POOL_ID> --client-name jwt-verify-a-user --explicit-auth-flows ALLOW_USER_PASSWORD_AUTH ALLOW_REFRESH_TOKEN_AUTH --id-token-validity 60 --token-validity-units IdToken=minutes

I created ro and other in the same way as rw, except with only orders/read as the scope.

Creating the authorizer

Configuration file

The list of configuration items is in the developer guide.

https://docs.aws.amazon.com/apigateway/latest/developerguide/rest-api-jwt-authorizer.html

API Gateway matches the client_id of a Cognito access token against audiences, so list the app client IDs in audiences. I saved the initial configuration as jwt-config.json.

{
  "issuers": [
    {
      "issuer": "https://cognito-idp.ap-northeast-1.amazonaws.com/ap-northeast-1_<POOL_ID>",
      "audiences": [
        "<CLIENT_ID_RW>",
        "<CLIENT_ID_RO>"
      ]
    }
  ],
  "defaultAlgorithms": [
    "RS256"
  ]
}

Creating it and attaching it to methods

Create the authorizer by specifying --type JWT and passing the configuration file with --jwt-configuration.

aws apigateway create-authorizer --rest-api-id <API_ID> --region us-east-1 --name jwt-verify-authorizer --type JWT --identity-source method.request.header.Authorization --jwt-configuration file://jwt-config.json

For methods, specify --authorization-type JWT and the authorizer ID. A method with --authorization-scopes only lets through tokens that have those scopes. Apply the configuration to the stage with create-deployment.

aws apigateway put-method --region us-east-1 --rest-api-id <API_ID> --resource-id <RESOURCE_ID> --http-method GET --authorization-type JWT --authorizer-id <AUTHORIZER_ID> --authorization-scopes orders/read
aws apigateway put-method --region us-east-1 --rest-api-id <API_ID> --resource-id <RESOURCE_ID> --http-method POST --authorization-type JWT --authorizer-id <AUTHORIZER_ID> --authorization-scopes orders/write
aws apigateway put-method --region us-east-1 --rest-api-id <API_ID> --resource-id <RESOURCE_ID> --http-method GET --authorization-type JWT --authorizer-id <AUTHORIZER_ID>
aws apigateway create-deployment --region us-east-1 --rest-api-id <API_ID> --stage-name test

For --resource-id, specify the resource IDs of /orders and /open respectively.

Preparing the MOCK integration

These are the integration commands for GET /orders. For POST /orders, run the same commands changing only --http-method.

aws apigateway put-integration --region us-east-1 --rest-api-id <API_ID> --resource-id <RESOURCE_ID> --http-method GET --type MOCK --request-templates '{"application/json":"{\"statusCode\": 200}"}'
aws apigateway put-method-response --region us-east-1 --rest-api-id <API_ID> --resource-id <RESOURCE_ID> --http-method GET --status-code 200
aws apigateway put-integration-response --region us-east-1 --rest-api-id <API_ID> --resource-id <RESOURCE_ID> --http-method GET --status-code 200 --response-templates file://response-templates.json

response-templates.json is a template that outputs the method and claims in the response body.

{
  "application/json": "{\"method\":\"$context.httpMethod\",\"client_id\":$context.authorizer.claims.client_id,\"scope\":$context.authorizer.claims.scope,\"iss\":$context.authorizer.claims.iss,\"token_use\":$context.authorizer.claims.token_use}"
}

Checking the responses

Responses by token

I checked with only pool A as the issuer and RS256 as the allowed algorithm. The rows for the ID token and the user access token are the results after adding the user client to audiences (jwt-config-v2.json). Requests take the form curl -i -H "Authorization: Bearer $TOKEN" https://<API_ID>.execute-api.us-east-1.amazonaws.com/test/<path>.

Request Status error_description
GET /orders with the rw access token 200 -
POST /orders with the rw access token 200 -
GET /orders with the ro access token 200 -
GET /open with an ID token 200 -
POST /orders with the ro access token 403 (insufficient_scope) expected scopes within the token
GET /orders with the user's access token 403 (insufficient_scope) expected scopes within the token
No token 401 - (www-authenticate is only Bearer)
Malformed token (abc.def.ghi) 401 the token is malformed
Token with alg none 401 the token is malformed
Token with alg HS256 401 the token's signing algorithm is not allowed
Expired token 401 the token has expired
Token from a client (other) not included in audiences 401 the token does not have a valid audience
Token from an unregistered issuer (pool B) 401 issuer does not match
GET /orders with an ID token 401 the token's token_use is not valid for this method
GET /open with an access token (both user and client credentials) 401 the token's token_use is not valid for this method

When Cognito is the issuer, only access tokens pass for methods with scopes specified, and only ID tokens pass for methods without scopes specified.

Response headers and body

The reason for rejection is placed in the error and error_description of www-authenticate. The shape of the body differs between 401 and 403. The 401 without a token is as follows.

HTTP/2 401
x-amzn-errortype: UnauthorizedException
www-authenticate: Bearer

{"message":"Unauthorized"}

When a token is sent and the result is 401, the www-authenticate header gets error="invalid_token" and an error_description. The expired-token response is as follows. The body message differed from the {"message":"Unauthorized"} of the other 401s.

HTTP/2 401
x-amzn-errortype: UnauthorizedException
www-authenticate: Bearer error="invalid_token" error_description="the token has expired"

{"message":"The incoming token has expired"}

The 403 for insufficient scope gets error="insufficient_scope", and the required scope is also included in www-authenticate.

HTTP/2 403
x-amzn-errortype: AccessDeniedException
www-authenticate: Bearer scope="orders/write" error="insufficient_scope" error_description="expected scopes within the token"

{"Message":"Access Denied"}

The body key is message for 401 and Message for 403, so the capitalization of the first letter differs. If a client reads the body and branches on it, it needs to handle both.

Expiration

The access token's validity period is 5 minutes. Requests 30 seconds and 40 seconds after exp still returned 200, while those 75 seconds and 80 seconds after returned 401.

Claims referenced in response templates

The developer guide explains that claims can be referenced from the integration with $context.authorizer.claims.

https://docs.aws.amazon.com/apigateway/latest/developerguide/rest-api-jwt-authorizer-claims.html

I created GET /cog with a Cognito authorizer in the same API, and compared its response with the JWT authorizer's GET /orders using the ro token. In the MOCK integration's response template, the Cognito authorizer filled in the claim values, but the JWT authorizer's were empty, unlike what the developer guide describes.

Cognito authorizer (GET /cog):

{"method":"GET","client_id":<CLIENT_ID_RO>,"scope":orders/read,"iss":https://cognito-idp.ap-northeast-1.amazonaws.com/ap-northeast-1_<POOL_ID>,"token_use":access}

JWT authorizer (GET /orders):

{"method":"GET","client_id":,"scope":,"iss":,"token_use":}

Changing the configuration

Replacing the configuration with update-authorizer

update-authorizer replaces the entire configuration, so even when changing only part of it, you pass the entire configuration. However, the jwtConfiguration returned by get-authorizer includes jwksUri, and passing it as is was rejected with the following error.

aws: [ERROR]: An error occurred (BadRequestException) when calling the UpdateAuthorizer operation: Invalid value for patch operation 'replace' and path '/jwtConfiguration'. The value should be the JWT configuration as JSON.

A configuration file without jwksUri can be used to update. This is an example of updating with jwt-config-v2.json, which adds the user client to audiences.

{
  "issuers": [
    {
      "issuer": "https://cognito-idp.ap-northeast-1.amazonaws.com/ap-northeast-1_<POOL_ID>",
      "audiences": [
        "<CLIENT_ID_RW>",
        "<CLIENT_ID_RO>",
        "<CLIENT_ID_USER>"
      ]
    }
  ],
  "defaultAlgorithms": [
    "RS256"
  ]
}
aws apigateway update-authorizer --region us-east-1 --rest-api-id <API_ID> --authorizer-id <AUTHORIZER_ID> --patch-operations "$(jq -n --rawfile v jwt-config-v2.json '[{op:"replace",path:"/jwtConfiguration",value:$v}]')"

For later configuration changes too, I used commands of this form with only the file name changed, and ran create-deployment after each change. Right after deployment, responses based on either the new or the old configuration were returned. For example, when I added pool B in the next section, calling POST /orders with B's token about 1 minute after deployment still returned the old configuration's 401 (issuer does not match).

Multiple issuers

I updated with jwt-config-two-issuers.json, which adds pool B to issuers. For B's audiences, put B's app client ID.

{
  "issuers": [
    {
      "issuer": "https://cognito-idp.ap-northeast-1.amazonaws.com/ap-northeast-1_<POOL_ID>",
      "audiences": [
        "<CLIENT_ID_RW>",
        "<CLIENT_ID_RO>",
        "<CLIENT_ID_USER>"
      ]
    },
    {
      "issuer": "https://cognito-idp.ap-northeast-1.amazonaws.com/ap-northeast-1_<POOL_B_ID>",
      "audiences": [
        "<CLIENT_ID_B>"
      ]
    }
  ],
  "defaultAlgorithms": [
    "RS256"
  ]
}

B's token returned 200 for both GET /orders and POST /orders. A's ro returned 200 for GET and 403 for POST. After removing B from issuers and updating, B's token returned 401 (issuer does not match), and A's rw remained 200.

Additional claims

For each issuer, you can require that a specific claim has an expected value. I tried this with jwt-config-additional-claims.json, which uses ro's client_id as the expected value.

{
  "issuers": [
    {
      "issuer": "https://cognito-idp.ap-northeast-1.amazonaws.com/ap-northeast-1_<POOL_ID>",
      "audiences": [
        "<CLIENT_ID_RW>",
        "<CLIENT_ID_RO>",
        "<CLIENT_ID_USER>"
      ],
      "additionalClaims": [
        {
          "claimName": "client_id",
          "format": "SINGLE_STRING",
          "required": true,
          "expectedValues": [
            "<CLIENT_ID_RO>"
          ]
        }
      ]
    }
  ],
  "defaultAlgorithms": [
    "RS256"
  ]
}

Calling GET /orders with the rw token, whose client_id does not match the expected value, returned 403. The www-authenticate header gets error="insufficient_scope" error_description="the token does not satisfy the required claims". The matching ro token returned 200.

An update specifying scope as the claimName was rejected with the following error.

aws: [ERROR]: An error occurred (BadRequestException) when calling the UpdateAuthorizer operation: Invalid claim name: scope. Claim name should not be one of iss, aud, exp, nbf, iat, scope, scp.

Signing algorithm

An update setting defaultAlgorithms to only ES256 was rejected when running update-authorizer. This is because both signing keys in pool A's JWKS are RS256, and there is no ES256 key.

aws: [ERROR]: An error occurred (BadRequestException) when calling the UpdateAuthorizer operation: Invalid issuer: https://cognito-idp.ap-northeast-1.amazonaws.com/ap-northeast-1_<POOL_ID>. Issuer's JSON Web Key Set should have a signing key with a key ID for at least one of these algorithms: ES256.

Converting from a Cognito authorizer

An authorizer of type COGNITO_USER_POOLS can be converted to type JWT with a single update-authorizer. The patch consists of three operations: replacing type, replacing jwtConfiguration, and removing providerARNs. I saved it as convert-patch-operations.json.

[
  {"op": "replace", "path": "/type", "value": "JWT"},
  {"op": "replace", "path": "/jwtConfiguration", "value": "{\n  \"issuers\": [\n    {\n      \"issuer\": \"https://cognito-idp.ap-northeast-1.amazonaws.com/ap-northeast-1_<POOL_ID>\",\n      \"audiences\": [\n        \"<CLIENT_ID_RW>\",\n        \"<CLIENT_ID_RO>\",\n        \"<CLIENT_ID_USER>\"\n      ]\n    }\n  ],\n  \"defaultAlgorithms\": [\n    \"RS256\"\n  ]\n}\n"},
  {"op": "remove", "path": "/providerARNs", "value": "arn:aws:cognito-idp:ap-northeast-1:<ACCOUNT_ID>:userpool/ap-northeast-1_<POOL_ID>"}
]
aws apigateway update-authorizer --region us-east-1 --rest-api-id <API_ID> --authorizer-id <AUTHORIZER_ID> --patch-operations file://convert-patch-operations.json

In the update-authorizer response at conversion, authType remained cognito_user_pools (a newly created JWT authorizer shows jwt).

Even after converting and deploying, the authorizationType of GET /legacy remained COGNITO_USER_POOLS. The ro token still returned 401 about 1.5 minutes after deployment. The authorizationType must be updated separately.

aws apigateway update-method --region us-east-1 --rest-api-id <API_ID> --resource-id <RESOURCE_ID> --http-method GET --patch-operations op=replace,path=/authorizationType,value=JWT

After redeploying, ro returned 200. With the Cognito authorizer before conversion, the other token also passed with 200, but after conversion it returns 401 (the token does not have a valid audience) because it is not in audiences. A request without a token is 401 both before and after conversion. When migrating, put all the app clients you want to allow into audiences.

Non-Cognito issuer (Firebase Authentication)

Token and issuer configuration

I enabled Firebase Authentication's anonymous authentication in a Google Cloud project and issued an API key. I obtained an ID token with anonymous sign-up. Replace <API_KEY> with the issued key.

curl -s -X POST -H 'Content-Type: application/json' -d '{"returnSecureToken":true}' "https://identitytoolkit.googleapis.com/v1/accounts:signUp?key=<API_KEY>"

The idToken in the response is the ID token. The alg in the header is RS256, and the signing algorithm shown in the issuer's discovery document was also RS256. The payload without sub and user_id is as follows. It does not include scope or scp.

{"provider_id":"anonymous","iss":"https://securetoken.google.com/<PROJECT_ID>","aud":"<PROJECT_ID>","auth_time":1795002572,"iat":1795002572,"exp":1795006172,"firebase":{"identities":{},"sign_in_provider":"anonymous"}}

Using this iss as the second issuer and aud as its audiences, I placed it alongside Cognito's pool A. The file name is jwt-config-cognito-and-firebase.json.

{
  "issuers": [
    {
      "issuer": "https://cognito-idp.ap-northeast-1.amazonaws.com/ap-northeast-1_<POOL_ID>",
      "audiences": [
        "<CLIENT_ID_RW>",
        "<CLIENT_ID_RO>",
        "<CLIENT_ID_USER>"
      ]
    },
    {
      "issuer": "https://securetoken.google.com/<PROJECT_ID>",
      "audiences": [
        "<PROJECT_ID>"
      ]
    }
  ],
  "defaultAlgorithms": [
    "RS256"
  ]
}

Results for methods and additional claims

Configuration Request Status error_description
The two issuers above GET /open with a Firebase token 200 -
The two issuers above GET /orders with a Firebase token 403 (insufficient_scope) expected scopes within the token
The two issuers above POST /orders with a Firebase token 403 (insufficient_scope) expected scopes within the token
The two issuers above GET /orders with Cognito's ro token 200 -
Additional claim provider_id = anonymous on the Firebase issuer GET /open with a Firebase token 200 -
Additional claim provider_id = google.com on the Firebase issuer GET /open with a Firebase token 403 (insufficient_scope) the token does not satisfy the required claims
Firebase audiences changed to a different value GET /open with a Firebase token 401 the token does not have a valid audience

The Firebase token this time has no scope, so it got 403 on methods with scopes. For methods that let Firebase tokens through, don't specify scopes, and do the narrowing with additional claims.

Signature validation

Based on the Firebase token, I sent the following three to GET /open.

  • The original token
  • A token with the payload's provider_id rewritten and the signature left as the original
  • A token with the signature replaced by a different value

The original token returned 200, and both tampered ones returned 401 (the token signature is invalid).

Summary

Until now, validating tokens from non-Cognito identity providers such as Firebase required a Lambda authorizer, and you had to write and operate the validation code.

With API Gateway REST APIs now supporting JWT authorizers, token validation can be done with configuration alone.

Please make use of it in cases such as multi-tenant APIs that need to accept tokens from multiple identity providers.

Share this article

AWSのお困り事はクラスメソッドへ