Validate JWT (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.

Restriction: The Validate JWT policy can be used only with the DataPower® Gateway.

About

JSON Web Token (JWT) is a compact, URL-safe way of representing claims that are to be transferred between two parties. The Validate JWT policy enables you to secure access to your APIs by using JWT validation. For example, when an input request that contains a JWT in the header is received, the Validate JWT policy extracts the token, verifies, and decrypts (if appropriate) the signature, and validates the claim. If valid, the claim is put in a runtime variable (for subsequent use if required), and access is allowed to the API. If the claim is not valid, access is denied.

All claims that are specified in the Validate JWT policy are validated, but this is not necessarily all the claims that are contained in the JWT. Not all claims that are in the JWT must be validated, but if any one of the claims that are specified in the Validate JWT policy fail, the whole validation fails. If the validation succeeds, the full set of claims that are contained in the JWT are written to the runtime variable specified in the Output Claims property. Thereby allowing any subsequent action to use this runtime variable to further validate the full set of claims that were in the JWT, as necessary.

You can attach this policy to the following API flows:

REST
SOAP

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.

Prerequisites

The following prerequisites apply:

IBM® API Connect Version 5.0.1 or later.
IBM DataPower V7.5 with the Application Optimization (AO) option.
If you are using one or more cryptographic objects, they must be located in the IBM API Connect domain on the DataPower appliance. The cryptographic objects must reference the Shared Secret Key or public certificate that is needed to decrypt the JWT contents or verify the signature.
If a JSON Web Key (JWK) is being used, it must be referenced by a runtime variable.

Properties

The following table lists the policy properties, indicates whether a property is required, specifies the valid and default values for input, and specifies the data type of the values.

Table 1. Validate JWT policy properties
Property label	Property name	Required	Description	Data type
Title	title	Yes	The title of the policy. The default value is `jwt-validate`.	string
Description	description	No	A description of the policy.	string
JSON Web Token (JWT)	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	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
Issuer Claim	iss-claim	No	The Pearl Compatible Regular Expression (PCRE) to use to validate the Issuer (iss) claim.	string
Audience Claim	aud-claim	No	The PCRE to use to validate the Audience (aud) claim.	string
Decrypt Crypto Object	jwe-crypto	No	The cryptographic object (a shared key or certificate) to use to decode the claim.^¹	string
Decrypt Crypto JWK variable name	jwe-jwk	No	Runtime variable that contains the JWK to use to decrypt the JWT.^¹	string
Verify Crypto Object	jws-crypto	No	The cryptographic object (a shared key or certificate) to use to verify the signature.^²	string
Verify Crypto JWK variable name	jws-jwk	No	Runtime variable that contains the JWK to use to verify the signature.^²	string

Example

- jwt-validate:
    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

Errors

The following error can be thrown while the policy is being executed:

RuntimeError - a generic error that captures all errors that occur during the execution of the policy. Upon a validation failure, the detailed error message that is received from the underlying JOSE module is written to the default system log as an error message. This detailed error message is also assigned to the runtime variable jwt-validate.error-message, so it can be retrieved via catch.

If a catch is not configured, in the case of a validation failure the Validate JWT policy returns an HTTP code 500 Invalid-JWT-Validate failure. The detailed error message from the underlying JOSE module can be found in the system log.

Attention: If you are an API developer who is troubleshooting a failure that one of your customers had with your API, consider the security risks before sending a customer the exact content of the log message. You can avoid the possibility of someone launching an attack based on the information that they receive from the log message by sending the customer only general information about the message.

¹ 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.

² A JWK 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.