Controlling access to HTTP APIs with JWT authorizers
You can use JSON Web Tokens (JWTs) as a part of OpenID Connect
(OIDC)
If you configure a JWT authorizer for a route of your API, API Gateway validates the JWTs that clients submit with API requests. API Gateway allows or denies requests based on token validation, and optionally, scopes in the token. If you configure scopes for a route, the token must include at least one of the route's scopes.
You can configure distinct authorizers for each route of an API, or use the same authorizer for multiple routes.
Note
There is no standard mechanism to differentiate JWT access tokens from other types of JWTs, such as OpenID Connect ID tokens. Unless you require ID tokens for API authorization, we recommend that you configure your routes to require authorization scopes. You can also configure your JWT authorizers to require issuers or audiences that your identity provider uses only when issuing JWT access tokens.
Authorizing API requests
API Gateway uses the following general workflow to authorize requests to routes that are configured to use a JWT authorizer.
-
Check the
identitySource
for a token. TheidentitySource
can include only the token, or the token prefixed withBearer
. -
Decode the token.
-
Check the token's algorithm and signature by using the public key that is fetched from the issuer's
jwks_uri
. Currently, only RSA-based algorithms are supported. API Gateway can cache the public key for two hours. As a best practice, when you rotate keys, allow a grace period during which both the old and new keys are valid. -
Validate claims. API Gateway evaluates the following token claims:
-
kid
– The token must have a header claim that matches the key in the jwks_uri
that signed the token. -
iss
– Must match the issuer
that is configured for the authorizer. -
aud
or client_id
– Must match one of theaudience
entries that is configured for the authorizer. -
exp
– Must be after the current time in UTC. -
nbf
– Must be before the current time in UTC. -
iat
– Must be before the current time in UTC. -
scope
or scp
– The token must include at least one of the scopes in the route'sauthorizationScopes
.
-
If any of these steps fail, API Gateway denies the API request.
After validating the JWT, API Gateway passes the claims in the token to the API route’s integration. Backend
resources, such as Lambda functions, can access the JWT claims. For example, if the JWT includes an identity claim
emailID
, it's available to a Lambda integration in
$event.requestContext.authorizer.jwt.claims.emailID
. For more information about the payload that
API Gateway sends to Lambda integrations, see Working with AWS Lambda proxy integrations for
HTTP APIs.
Create a JWT authorizer
Before you create a JWT authorizer, you must register a client application with an
identity provider. You must also have created an HTTP API. For examples of creating
an HTTP API, see Creating an HTTP API. For an example AWS CloudFormation template that creates an
HTTP API with a JWT authorizer that uses Amazon Cognito as an identity provider, see http-with-jwt-auth.yaml
The following AWS CLI command creates a JWT authorizer. For jwt-configuration
, specify the Audience
and Issuer
for your identity provider.
aws apigatewayv2 create-authorizer \ --name
authorizer-name
\ --api-idapi-id
\ --authorizer-type JWT \ --identity-source '$request.header.Authorization
' \ --jwt-configuration Audience=audience
,Issuer=https://cognito-idp.us-east-2
.amazonaws.com/userPoolID
Update a route to use a JWT authorizer by using the AWS CLI
The following command updates a route to use a JWT authorizer.
aws apigatewayv2 update-route \ --api-id
api-id
\ --route-idroute-id
\ --authorization-type JWT \ --authorizer-idauthorizer-id
\ --authorization-scopesuser.email