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.
|DataPower® Gateway (v5 compatible)||1.0.0|
|DataPower API Gateway||2.0.0|
This topic describes how to configure the policy in the assembly user interface; for details on how to configure the policy in your OpenAPI source, see jwt-validate.
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.
- 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.
- 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), or JWK set, is being used, it must be referenced by a runtime variable.
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.
|Property label||Required||Description||Data type|
|Title||Yes||The title of the policy.
The default value is
|Description||No||A description of the policy.||string|
|JSON Web Token (JWT)||Yes||Context or runtime variable that contains the JWT to be validated.
The default value is:
Note: The format of the authorization header must be:
where jwt-token is the encoded JWT.
|Output Claims||Yes||Runtime variable to which the full set of claims that are contained in the JWT is assigned.
The default value is:
|Issuer Claim||No||The Perl Compatible Regular Expressions (PCRE) to use to validate the Issuer (iss) claim.||string|
|Audience Claim||No||The PCRE to use to validate the Audience (aud) claim.||string|
|Decrypt Crypto Object||No||The cryptographic object (a shared key or certificate) to use to decode the claim.1||string|
|Decrypt Crypto JWK variable name||No||Runtime variable that contains the JWK to use to decrypt the JWT.1||string|
|Verify Crypto Object||No||The cryptographic object (a shared key or certificate) to use to verify the signature.2||string|
|Verify Crypto JWK variable name||No||Runtime variable that contains the JWK, or JWK set, to use to verify the signature.2||string|
- 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
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.
Invalid-JWT-Validatefailure. The detailed error message from the underlying JOSE module can be found in the system log.