View a markdown version of this page

Create a JWT authorizer for a REST API - Amazon API Gateway

Create a JWT authorizer for a REST API

You can create a JWT authorizer by using the API Gateway console, the AWS CLI, an AWS SDK, AWS CloudFormation, or an OpenAPI definition. Before you create a JWT authorizer, you must create a REST API. For more information, see Tutorial: Create a REST API with a Lambda proxy integration.

Collect the following values from your identity provider before you begin:

  • The issuer URL, exactly as it appears in the token's iss claim. The issuer must be an absolute https URL with no query string or fragment.

  • One or more audience values that you accept from the issuer.

  • The signing algorithms that the issuer uses.

Your identity provider must publish an OIDC discovery document at the issuer URL followed by /.well-known/openid-configuration, for example, https://identity.example.com/.well-known/openid-configuration. API Gateway reads this document when you create the authorizer. The document must be reachable from the public internet. The discovery document and the key set must use a certificate issued by a certificate authority that API Gateway supports. For the list, see API Gateway-supported certificate authorities for HTTP and HTTP proxy integrations in API Gateway.

Important

The issuer that you configure must match the token's iss claim exactly, including any trailing slash. To find the value, decode a token from your identity provider and copy its iss claim.

Additional claims

You can require that a token carries other claims beyond the standard claims that API Gateway validates. You can configure up to 10 claim rules for each issuer. Each rule names a claim and sets whether the claim is required and which values API Gateway accepts. A claim name must be unique within the issuer, and it cannot be iss, aud, exp, nbf, iat, scope, or scp. A claim rule uses the SINGLE_STRING format and accepts at most one expected value, which you set as the only item in expectedValues. API Gateway matches the value exactly, and the match is case-sensitive. If expectedValues contains more than one value, API Gateway returns a 400 error. A claim rule matches only a claim whose value in the token is a single string. If the token's claim is an array, such as "groups": ["admins", "users"], the token fails the rule and receives a 403 response.

The combination of the required setting and the expected value determines how API Gateway evaluates a claim:

  • Required, no expected value – The token must contain the claim. API Gateway does not check its value.

  • Required, with an expected value – The token must contain the claim, and the value must match the expected value exactly.

  • Not required, with an expected value – API Gateway checks the value only when the token contains the claim.

  • Not required, no expected value – API Gateway doesn't check the claim.

To reject tokens that don't carry a claim, select required. To also check the claim's value, set an expected value.

A token that fails a claim rule receives a 403 Forbidden response.

Create a JWT authorizer using the console

The following steps show how to create a JWT authorizer by using the console.

To create a JWT authorizer using the console
  1. Sign in to the API Gateway console at https://console.aws.amazon.com/apigateway.

  2. Choose a REST API.

  3. In the main navigation pane, choose Authorizers.

  4. Choose Create authorizer.

  5. For Authorizer name, enter a name for the authorizer.

  6. For Authorizer type, choose JWT.

  7. For Identity source, enter the request header that carries the token, for example, Authorization. The header value can be the token alone or the token prefixed with Bearer. The prefix isn't case-sensitive.

  8. For Allowed signing algorithms, select the algorithms that you accept. API Gateway rejects tokens that are signed with any other algorithm.

  9. Under Issuers, configure each identity provider that issues tokens for this API:

    1. For Issuer URL, enter the issuer that matches the token's iss claim. Use an absolute HTTPS URL with no query string or fragment.

    2. For Audiences, enter the values that you accept from the issuer as a comma-separated list. You can enter up to 100 audiences.

    3. (Optional) Add claim rules for the issuer:

      1. Expand Additional claims - optional, and then choose Add additional claims.

      2. Choose Add claim, and then for Claim name, enter the name of the claim.

      3. (Optional) Select Required if the claim must be present.

      4. (Optional) For Expected value, enter the value that the claim must have.

      5. Repeat these steps for each claim, and then choose Save.

      The Additional claims dialog box with one claim rule: the claim name department, Required selected, and the expected value engineering.

    To accept tokens from more than one issuer, choose Add issuer and repeat this step. You can add up to 10 issuers.

    The Create authorizer page with JWT selected as the authorizer type, showing the identity source, allowed signing algorithms, issuer URL, audiences, and additional claims fields.
  10. Choose Create authorizer.

Create a JWT authorizer using the AWS CLI

First, describe the authorizer configuration in a file. The configuration lists the trusted issuers, the audiences that you accept from each issuer, and the signing algorithms that you allow. The following example defines one issuer.

{ "issuers": [ { "issuer": "https://identity.example.com", "audiences": ["api://orders"] } ], "defaultAlgorithms": ["RS256"] }

To require an additional claim, add an additionalClaims entry to the issuer. The following issuer accepts only tokens whose department claim equals eng.

{ "issuer": "https://identity.example.com", "audiences": ["api://orders"], "additionalClaims": [ { "claimName": "department", "format": "SINGLE_STRING", "required": true, "expectedValues": ["eng"] } ] }

Next, run the create-authorizer command. For the identity source, specify the request header that carries the token.

aws apigateway create-authorizer \ --rest-api-id api-id \ --name authorizer-name \ --type JWT \ --identity-source method.request.header.Authorization \ --jwt-configuration file://jwt-config.json

When you create the authorizer, API Gateway reads the issuer's discovery document and records the location of its key set. For more information, see Signing keys and troubleshooting JWT authorizers.

Create a JWT authorizer using AWS CloudFormation

In CloudFormation, the AWS::ApiGateway::Authorizer resource includes a JwtConfiguration property that mirrors the API. A method references the authorizer with AuthorizationType: JWT.

Parameters: IdpIssuer: Type: String Description: Issuer URL exactly as it appears in the token's iss claim IdpAudience: Type: String Resources: OrdersAuthorizer: Type: AWS::ApiGateway::Authorizer Properties: RestApiId: !Ref OrdersApi Name: orders-jwt Type: JWT IdentitySource: method.request.header.Authorization JwtConfiguration: DefaultAlgorithms: [RS256] Issuers: - Issuer: !Ref IdpIssuer Audiences: [!Ref IdpAudience] GetOrders: Type: AWS::ApiGateway::Method Properties: RestApiId: !Ref OrdersApi ResourceId: !Ref OrdersResource HttpMethod: GET AuthorizationType: JWT AuthorizerId: !GetAtt OrdersAuthorizer.AuthorizerId AuthorizationScopes: [orders:read] Integration: Type: MOCK RequestTemplates: application/json: '{"statusCode": 200}'

Create a JWT authorizer using OpenAPI

In an OpenAPI definition, a JWT authorizer uses the x-amazon-apigateway-authorizer extension with type: jwt. The scopes that you list in each operation's security entry become that method's authorization scopes. For more information about the extension, see x-amazon-apigateway-authorizer object.

components: securitySchemes: orders-jwt: type: apiKey name: Authorization in: header x-amazon-apigateway-authtype: jwt x-amazon-apigateway-authorizer: type: jwt jwtConfiguration: issuers: - issuer: https://identity.example.com audiences: [ "api://orders" ] defaultAlgorithms: [ "RS256", "ES256" ] paths: /orders: get: security: - orders-jwt: [ "orders:read" ]

When you import an OpenAPI definition, API Gateway ignores the jwksUri field. When you export an API, API Gateway omits the jwksUri field.