Configure reserved JWT claims

Reserved claims constitute the payload of a JWT and contain information such as time constraints for accepting a token or the parties involved in the processing of a token. You can specify which claims are required and which claim values must be validated in incoming API requests.

Before you begin

Ensure that you enabled JWT settings at the API level.

Ensure that you are familiar with the available reserved JWT claims. For details, see JWT reserved claims.

How to

  1. On the JSON web tokens (JWT) settings page, in the Claims section, click Add claim and select the reserved claims that you want to add to your configuration.
    You can only add one instance of each reserved claim.
  2. Optional: If you want to treat the iat claim as the nbf claim, enable the Treat iat as nbf switch.
    The iat claim indicates the time a JWT was issued at. Normally, it serves an informational purpose, but you have an option to make it act as the nbf claim. The nbf claim identifies the time before which the token is not accepted for processing. If you decide to enable this switch, the iat claim will act as nbf regardless of the presence of nbf in the JWT.
  3. Specify the mandatory claims by setting their corresponding Required switches to Yes.
    If you set a claim’s Required switch to Yes, it means that this claim must be present in an incoming JWT. Otherwise, JWT validation fails and API Gateway rejects the request that included the token.

    If you enabled the Treat iat as nbf switch, the iat is automatically required. You can still mark the nbf claim as required and tell edge servers to check for the presence of both claims in incoming JWTs. If required, both iat and nbf must pass the validation for API Gateway to accept a request.

  4. If applicable, specify whether you want to validate the values of aud, iss, and sub claims by setting their corresponding Validate value switches to Yes.
  5. If applicable, specify the Claim type of iss and sub claims.
    The available claim types for iss and sub claims are String and Regex. When you decide to match a claim’s value against a regular expression, enter the regular expression in the corresponding Claim value field. This allows you to broaden the number of acceptable issuers or subjects specified in incoming tokens.
  6. If applicable, for claims whose values you want to validate, fill in the fields in the Claim value column:
    • For the aud claim, enter the allowed JWT audiences.
    • For the iss claim, enter the allowed JWT issuer.
    • For the sub claim, enter the allowed JWT subject.
    Note: The values of the above claims are case sensitive.

What you should see

Reserved claims example

The figure above shows a sample reserved claims configuration:

  • The iss claim contains a string value of akamai. The presence of this claim in a JWT is optional. However, if the claim is present, its value must be akamai. Otherwise, the JWT fails the validation and API Gateway rejects the request that included the token.
  • The sub claim contains a regex value of ^[a-zA-Z0-9_]*$. The regex matches all alphanumeric characters and underscores. The presence of this claim in a JWT is optional. However, if the claim is present, its string value must be matched by the regex. Otherwise, the JWT fails the validation and API Gateway rejects the request that included the token.
  • The exp and nbf contain a predefined timestamp value. The presence of these claims in a JWT is optional but their values are validated.
  • The aud claim is not required and it does not contain a specific value. This means that it may or may not be included in a JWT without any impact on the request validation.

Next steps

Finish the JWT validation configuration. Return to Configure JWT validation.