
I Tried Validating Cognito and Firebase Tokens with a JWT Authorizer in API Gateway REST API
This page has been translated by machine translation. View original
Introduction
On 2026-11-17, JWT authorizers became available for API Gateway REST APIs.
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.
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.
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.
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.
