Configure JWT validation

JSON web token (JWT) validation maximizes identity provider offload and lets you authorize users who send requests to your API. You can enable protection for the entire API, choose specific JWT reserved claims that you want to verify at the edge, and exempt individual resources from requiring validation.

Try the API: You can also complete this task by using the API Endpoints API. Run the Update JWT settings operation. Learn more about Akamai’s APIs.

How to

  1. On the API Definitions page, in the Registered APIs section, click the ellipsis icon () associated with the API configuration you want to configure JWT validation settings for.
  2. From the menu, select Manage versions.
  3. In the Version history panel, click the ellipsis icon () associated with the API configuration version you want to configure JWT validation settings for.
  4. From the list of delivery options, select JSON web tokens (JWT).
  5. On the JSON web tokens (JWT) settings page, set the Enable JWT switch to Yes.
    By setting this switch to Yes for the first time, you enable JWT validation for all resources associated with your API.
  6. From the JWT location menu, select the location for the JWT in the HTTP request.
  7. In the location name field, enter a name for the JWT location.
    where location is either Header, Cookie, or Query parameter.
  8. Do one of these steps:
    If you want to upload RSA public keys manually, do these steps:
    1. In the Public key format area, select RSA public key.
    2. In the Primary RSA public key area, click Choose file and upload the primary RSA public key for the JWT signature verification.
    3. Optionally in the Backup RSA public key area, click Choose file and upload the backup RSA public key for use during key rotations.
    If you want to use JSON web key sets (JWKSs) for a dynamic RSA public key upload, do these steps:
    1. In the Public key format area, select JWKS URI.
    2. In the Certificate chain area, click Choose file and upload a certificate chain to authenticate the hostnames in JWKS URIs with. Note that the certificate chain must exclude the leaf node. This will facilitate the renewal of the certificate corresponding to the hostname.

      A certificate chain is a list of certificates that allows edge servers to authenticate your hostnames and verify that a secure connection can be established. Edge servers authenticate the hostnames by verifying the Common Name (CN) of your origin SSL certificate. You should include a valid certificate chain in a PEM file and upload it here. The file should start with "----BEGIN CERTIFICATE-----" and end with "-----END CERTIFICATE-----".

    3. In the JWK set URL area, specify a URL that refers to a resource for a set of JSON-encoded public keys.
    4. In the Allowed JWKS URLs text box, enter up to 50 URLs where JWKSs reside.
      Note: If your hostname uses a different port for secure connections than the default 443, you can indicate it after a colon. For example:

      Whenever you update JSON web key sets, make sure to send a purge request with your old JWKS URI via the Fast Purge feature (a sample JWKS URI may look like this: This will prevent tokens with old signatures from retaining access to your API content. For details on Fast Purge, see the Fast Purge web help.

    5. Click the Validate button to validate the API Gateway connectivity to the JWKS URL. If the connection is successful, the Validate button is displayed with a green checkmark.
    6. In the Public key max age field, enter the maximum time for caching a public key.
      Note: You can specify this parameter in seconds, minutes, hours, or days. In each case, the value must be between 1 and 1000000.

      Keeping a public key in edge servers' cache negates the need to search for the public key in subsequent requests of a particular JWT issuer. This in turn reduces the time needed to validate the JWT.

  9. In the Clock skew amount (0-60 seconds) field, enter a value between 0 and 60.
    Clock skew amount specifies the allowed time difference (in seconds) between the server and client clocks when validating the exp and nbf claims. The recommended default value is 5.
  10. Optional: Configure JWT claims.
  11. Optional: If you want to validate only particular resources, specify them in the Enable JWT validation for resources section by setting their corresponding Validate JWT switches to Yes.
    If you decide to reset JWT settings for all resources to the API level at any point, you can click Reset to API settings. You can also control which individual resources inherit the top-level settings by selecting their Inherit check boxes.
  12. Click Save.