jwt-validate

Use the Validate JWT security policy to enable the validation of a JSON Web Token (JWT) in a request before allowing access to the APIs.

Gateway support

Table 1. Table showing which gateways support this policy, and the corresponding policy version
Gateway Policy version
DataPower® Gateway (v5 compatible) 1.0.0
DataPower API Gateway 2.0.0

This topic describes how to configure the policy in your OpenAPI source; for details on how to configure the policy in the assembly user interface, see Validate JWT.

Note:
  • If the original message was signed with a Shared Secret Key, the cryptographic object that is specified must also be a Shared Secret Key.
  • If the original message was signed with a Private Key, the cryptographic object that is specified must be a Crypto Certificate (public certificate).
  • The cryptographic material can be provided through a JSON Web Key (JWK).
  • If a JWK header parameter is included in the header of the JWT, the parameter must match the JWK or cryptographic object that is specified in the policy, or the JWT validation will fail.
  • If both a cryptographic object and a JWK are specified, the cryptographic object is used to decrypt or verify the JWT.
  • The JWT validate action on the DataPower API Gateway can verify a JWT by using either a single JWK, or a JWK set.

About

The jwt-validate policy has the following structure:
- jwt-validate:
  version: version
  title: title
  description: description
  jwt: json_web_token
  output-claims: output_full_set_of_jwt_claims
  iss-claim: issuer_claim
  aud-claim: audience_claim
  jwe-crypto: decrypt_crypto_object
  jwe-jwk: decrypt_crypto_jwk_variable_name
  jws-crypto: verify_crypto_object
  jws-jwk: verify_crypto_jwk_variable_name

Properties

The following table describes the policy properties:
Table 2. Validate JWT policy properties
Property Required Description Data type
version Yes The policy version number string
title Yes The title of the policy. string
description No A description of the policy. string
jwt Yes Context or runtime variable that contains the JWT to be validated.

The default value is: request.headers.authorization. However, if this property is not set, the policy looks for the JWT in the request.headers.authorization location by default.

Note: The format of the authorization header must be:
"Authorization: Bearer jwt-token"
where jwt-token is the encoded JWT.
string
output-claims Yes Runtime variable to which the full set of claims that are contained in the JWT is assigned.

The default value is: decoded.claims.

 string
iss-claim No The Perl Compatible Regular Expressions (PCRE) to use to validate the Issuer (iss) claim. string
aud-claim No The PCRE to use to validate the Audience (aud) claim. string
jwe-crypto No The cryptographic object (a shared key or certificate) to use to decode the claim. A JWK and a Crypto Object are both valid ways of providing the cryptographic data necessary to decrypt the JWT. However, if both data types are specified, only the Crypto Object is used. string
jwe-jwk No Runtime variable that contains the JWK to use to decrypt the JWT. A JWK and a Crypto Object are both valid ways of providing the cryptographic data necessary to decrypt the JWT. However, if both data types are specified, only the Crypto Object is used. string
jws-crypto No The cryptographic object (a shared key or certificate) to use to verify the signature. A JWK, or JWK set, and a Crypto Object are both valid ways of providing the cryptographic data necessary to verify the JWT. However, if both data types are specified, only the Crypto Object is used. string
jws-jwk No Runtime variable that contains the JWK, or JWK set, to use to verify the signature. A JWK, or JWK set, and a Crypto Object are both valid ways of providing the cryptographic data necessary to verify the JWT. However, if both data types are specified, only the Crypto Object is used. string

Example

The following is an example of a jwt-validate policy:
- jwt-validate:
    version: 1.0.0
    title: jwt-validate
    jwt: request.headers.authorization
    output-claims: decoded.claims
    iss-claim: "'^data.*'"
    aud-claim: "'^id.*'"
    jwe-crypto: jweCryptoObjectName
    jwe-jwk: jwe.jwk
    jws-crypto: jwsCryptoObjectName
    jws-jwk: jws.jwk

For more information about how to use a jwt-validate security policy, see Validate JWT in the built-in policies section.