Configure custom JWT claims

In API Definitions, you can create and validate your own custom JWT claims. This allows JWTs to include any JSON-encoded data that is not already covered by the available reserved claims. For example, a claim named dept can include information about the claim issuer’s department in your organization. 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.

How to

  1. On the JSON web tokens (JWT) settings page, in the Claims section, click Add claim and select Custom for each custom claim that you want to add to your configuration.
  2. 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.
  3. Specify the Claim name of each of your required custom claims.
    Custom claims refer to both private claims and public claims. For details on each type, see JWT claims.

    You can choose any name you like, but because JWTs should be as compact as possible, the recommended maximum value of a claim name is 8 characters. In addition, every claim name that you define must be unique.

  4. Specify whether you want to validate the values of your custom claims by setting their corresponding Validate value switches to Yes.
  5. Specify the Claim type of each custom claim whose value you want to validate.
    The available claim types for custom claims are String, Integer, Boolean, Regex, and Array. 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 values specified in incoming tokens.
    Tip: To test your regex, use a free online regex validator such as regex101.

    If you set the Claim type to Array, all items that you enter in the corresponding Claim value field must be present in a JWT for the validation to be successful.

  6. For claims whose values you want to validate, fill in the fields in the Claim value column.

What you should see

Custom claims example

The figure above shows a sample custom claims configuration:

  • The dept claim contains a string value of IT. The presence of this claim in a JWT is required and its value must be IT. Otherwise, the JWT fails the validation and API Gateway will reject the request that included the token.
  • The roles claim contains an array of two items: admin and dev. The presence of this claim in a JWT is required and it must contain the exact two items mentioned. If only one of these items is present, the JWT fails the validation and API Gateway rejects the request that included the token.
  • The internal claim contains a boolean value of true. The presence of this claim in a JWT is required and its value must be true. If the value is false, the JWT fails the validation and API Gateway rejects the request that included the token.
  • The bldg claim contains an integer value of 4. The presence of this claim in a JWT is NOT required for successful validation. However, if the claim is present, its value must be 4. Otherwise, the JWT fails the validation and API Gateway rejects the request that included the token.

Next steps

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