Contact Free trial Login

JWT Validation Policy

Policy Name

JWT Validation.

Summary

Validates a JWT Token.

Category

Security.

Since Mule Version

4.1.0

Returned Status Codes

400

Token was not provided in the request.

401

Failed to parse the Token.

Signature could not have been validated, or is invalid.

Some of the required claims are not present or their validation failed.

403

The client Id validation failed.

502

When the JWKS is unavailable.

JWT (JSON Web Token)

You can use a JSON Web Token (JWT) to transfer information between parties as a JSON object. Because the token is signed, you can trust the information and its emitter.

JSON Web Token (JWT) is a URL-secure method of representing claims to be transferred between two parties.
The claims in a JWT are encoded as a JSON object that is used as the payload of a JSON Web Signature (JWS), or as the plaintext of a JSON Web Encryption (JWE) structure. This enables the claims to be digitally signed or integrity protected with a Message Authentication Code (MAC).

Policy Overview

This policy validates incoming requests using a JWT with JWS format. The policy verifies the signature of the token and asserts the values of the claims. This policy does not validate JWT that uses JSON Web Encryption (JWE)

Validate Signature

The policy verifies the signature of the JWT based on the values specified in the policy configuration.
The policy rejects all JWTs if the algorithm specified in the policy configuration do not match, or if the signature of the token is invalid. However, if the None algorithm option is selected, the policy matches every signed and unsigned token.

The algorithms that support signature verification are:

  • Symmetric algorithms - HMAC using SHA-256, SHA-384, and SHA-512.

  • Asymmetric algorithms - RSA using SHA-256, SHA-384, and SHA-512.

  • None - No signature validation.

For more information about the algorithms in a JWS structure, refer to the JWA RFC standard.

Validate Claims

Claim validations enables you choose the conditions under which a token received in the policy must be rejected. The following registered claim validations are provided by default:

  • aud: The Audience validation specifies that a token must be rejected if it does not contain at least one of the values defined.

  • exp: The Expiration validation specifies that a token must be rejected if its date is past the validation date.

  • nbf: The Not before validation specifies that the token must be rejected if the validation time is before the time the token has.

In addition to these provided claims, you can also specify other claims to use in your validations. For all claims, Registered or Custom, you must provide the following details:

  • The name of the claim you want to validate.
    For example iss, for the issuer of the token.

  • The value used to test.
    You can provide a simple literal value if you only need to verify it, or you can provide a DataWeave expression for more complex comparisons.

You can define each claim validation as mandatory or non-mandatory. If a claim is defined as mandatory and is not present in the incoming JWT, the policy rejects this token. If a claim is defined as non-mandatory and is not present in the incoming JWT, the policy does not reject the token for that specific validation.
For both cases, if a claim is present, the policy validates the token value. If the validation fails, the JWT will be rejected.

Propogate Claim

After the policy parses and validates the JWT, the claims are propagated to downstream policies and flows through the claims property in the authentication object. To access the claim values you can use the following Dataweave 2.0 expression by replacing <claimName> with the name of the desired claim to access:

#[authentication.properties.claims.<claimName>]

Policy Configuration

Element Description Example

JWT Origin

Specifies from where in the request the JWT will be extracted:

  • Bearer Authentication Header

  • Custom Expression

If you set it to Bearer Authentication Header, the JWT will be expected as Bearer.
If you set this field to Custom Expression, a DataWeave Expression returning the token must be provided.

Token Expression

If you set the JWT Origin to Custom Expression, you should type the DataWeave expression returning the JWT here.

#[attributes.headers['jwt']]
This expression searches the JWT in the header named ‘jwt’.

JWT Signing Method

Specify the signing method expected in the incoming JWT. The policy rejects the token if the JWT has a different signing method.

RSA, HMAC, None

JWT Signing Key Length

Specify the length of the key (in the case of the HMAC algorithm) or the algorithm (in the case of RSA) used for the signing method.
Ignore this field if you selected none as JWT Signing Method.

256, 384, 512

JWT Key Origin

Specifies where to obtain the key for the Signature validation.
You can provide the key in the policy selecting the Text option or obtain it from a JWKS.
Ignore this field if you selected none as JWT Signing Method.

JWT Key

This field appears if you selected Text as JWT Key Origin.
Use this field to provide the key used to check the signature of the token.
Ignore this field if you selected none as JWT Signing Method.

A 32, 48 or 64 characters long shared secret in case HMAC was the selected JWT Signing Method or the PEM Public Key without the header nor the footer in case of selecting RSA.

JWKS URL

This field appears if you selected the JWKS method as JWT Key Origin.
Ignore this field if you selected none as JWT Signing Method.

The URL to the JWKS server.

JWKS Caching Time To Live

The URL to the JWKS server that contains the public keys for the signature validation.
Ignore this field if you selected none as JWT Signing Method.

This field input is the amount of time, in minutes, during which the policy considers the JWKS valid.

Skip Client ID Validation

If you check this field, the policy does not verify that the client ID extracted from the JWT matches a valid client application of the API.

Client ID Expression

If Skip Client Id Validation is not set, the client ID needs to be extracted from the token.

By default, the value will be extracted using the expression #[vars.claimSet.client_id] as specified in the Oauth 2.0 token exchange draft.

Validate Audience Claim

Indicates that the policy should check for the validity of the audience claim. You can set this "Mandatory" if you select Audience Claim Mandatory.

Validate Expiration Claim

Indicates that the policy should check for the validity of the expiration claim. You can set this claim as "Mandatory" by selecting Expiration Claim Mandatory.

Validate Not Before Claim

Indicates that the policy should check for the validity of the Not Before claim. You can set this claim as "Mandatory" by selecting Not Before Claim Mandatory

Validate Custom Claim

Enables the usage of custom validations in the policy. The JWT will be valid only if all DataWeave expressions are fulfilled.

The policy provides a claimSet variable that contains all the claims present in the incoming JWT. For example:

foo : #[vars.claimSet.foo == 'fooValue']

Note that all DataWeave expressions must return a boolean value or they will always fail.

Obtaining a policy compatible PEM public key

The policy uses public rsa key in pem format. In this section we explain how to obtain the public.pem file that contains said key. Remember that once the public.pem key is obtained, before pasting it to the policy configuration to remove the -----BEGIN PUBLIC KEY----- header and the -----END PUBLIC KEY----- footer.

Starting Point Procedure

No previous certificate

  1. Generate the private RSA key openssl genrsa -out key.pem 2048

  2. Extract the public key from the generated private key key.pem openssl rsa -in key.pem -outform PEM -pubout -out public.pem

  3. The public key will be in the file public.pem

PEM Certificate

  1. Extract the public key from the PEM certificate openssl x509 -inform pem -in cert.pem -pubkey -noout > public.pem

  2. The public key will be in the file public.pem

DER Certificate

  1. Extract the public key from the DER certificate openssl x509 -inform der -in cert.crt -pubkey -noout > public.pem

  2. The public key will be in the file public.pem

x5c field from JWKS

  1. Copy the first certificate from the chain and decode it echo <certificateString> | base64 -D > cert.crt (replace <certificateString> with the copied value)

  2. Extract the public key from the DER certificate openssl x509 -inform der -in cert.crt -pubkey -noout > public.pem

  3. The public key will be in the file public.pem

Was this article helpful?

💙 Thanks for your feedback!

Edit on GitHub