JWT Validator rule

Authenticates requests with a JSON Web Token (JWT) token. Service consumers must use their JWT credentials to sign their JWT. The rule automatically detects the signing algorithm using the JWT token header and key.
You can configure the rule to extract values from the JWT claim to add and pass in the request header to the underlying pipeline. The token value can then be passed to downstream systems. Tokens passed in the request header don't appear in logs nor are they visible in Monitor.
Before allowing API access to the consumer, the policy does the following:
  • Checks if the JWT token is valid.
    • If valid, processes the request.
    • If invalid, discards the request.
The JWT token works with the Authorize by Role policy. Use the value for the JWT role as the value for the Role field in the Authorize by Role Policy.

Policy execution order

This JWT Validator policy executes after the request has been authorized.

Supported algorithms

This rule only supports the following cryptographic algorithms:
  • Elliptic Curve Digital Signature Algorithm (ECDSA): ES256, ES384, ES512
  • Rivest–Shamir–Adleman (RSA): RS256, RS384, RS512
  • Hash-Based Message Authentication Code using SHA (HSA): HS256, HS384, HS512
The JWT rule contains these common properties, the others depend on whether you select the RAW_TEXT or the URL format.
Field Name Description
When this rule should be applied An expression that defines one or more conditions that must be true for the rule to execute.

Example: The expression request.method == "POST" causes the rule to execute only on POST requests.
Key Input Format Select one of the following two options:
  • RAW_TEXT
  • URL
Note: The option you select determines the subsequent fields.

Default value: RAW_TEXT

Raw text format properties

With the RAW_TEXT format selected, the following fields display.

Field Name Description
Key

Paste the contents of the public key, which can be a PEM Encoded key, a JSON Web Key (JWK), or a Client Secret.

Default value: N/A

Example: -----BEGIN PUBLIC KEY-----

MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAu1SU1LfVLPHCozMxH2Mo

4lgOEePzNm0tRgeLezV6ffAt0gunVTLw7onLRnrq0/IzW7yWR7QkrmBL7jTKEn5u

+qKhbwKfBstIs+bMY2Zkp18gnTxKLxoS2tFczGkPLPgizskuemMghRniWaoLcyeh

kd3qqGElvW/VDL5AaWTg0nLVkjRo9z+40RQzuVaE8AkAFmxZzow3x+VJYKdjykkJ

0iT9wCS0DRTXu269V264Vf/3jvredZiKRkgwlL9xNAwxXFg0x/XFw005UWVRIkdg

cKWTjpBP2dPwVZ4WWC+9aGVd+Gyn1o0CLelf4rEjGoXbAAEgAqeGUxrcIlbjXfbcmwIDAQAB

-----END PUBLIC KEY-----
Extract into $token Required. Use one or more of the custom key properties to specify the location of the token in the request. If none are found, this rule passes the request to the next rule.
Custom Header Keys The name of one or more header keys to check for the token. Click + to add more.

Default value: N/A

Example: x-jwt-key
Custom Query String Parameter Keys The names of one or more query parameter keys to check for the token. Click + to add more.

Default value: N/A

Example: Auth

Custom Cookie Key The names of one or more cookie keys to check for the token. Click + to add more custom cookies.
Tip: In the request, the cookie value should contain the JWT.

Default value: N/A

Example: My_jwt
Authorization Header Type If the key is in the Authorization header, this value is used as the “type” to check. Bearer is the correct type for JWTs.

Default value: Bearer
Extract User Info Required. Specifies how to extract information about the user from the token claim.
User ID Expression Required. Where to find the user ID in the token claim.

Default value: N/A

Example: sub
Roles Expression Required. Where to find the user role in the token claim.

Default value: N/A

Example: role
Headers to add Optional. Name-value pairs to pass information from the token in the request header to pipeline parameters. For example, you might pass the user ID from the token claim so that the underlying pipeline can retrieve it in a parameter.

Example:

To pass the role and token in the header:
  • Name: role Value: $aud
  • Name: tempKey Value: request.uri.path
  • Name: keyID Value: $kid
  • Name: all Value: $
To retrieve the token in pipeline parameters, add a Mapper Snap and map the header values:
  • _ROLE > $aud
  • _TEMPKEY > $tempKey
  • _KEYID > $kid
  • _ALL > $all
Description The purpose of the rule.

URL format properties

With the URL format selected, the following properties are available.

Field Name Description
URL

Enter the URL endpoint or click = to enter an expression to obtain the key.

Default value: N/A

Example: https://login.microsoftonline.com/%3Ctenant%3E/discovery/v2.0/keys
Extract Keys from URL Specifies where to store the extracted token.
Note: This policy only supports a list of JWK Keys or one JWK key and verifies against the kid field in the JWT header to support URL. If you pass in a list of keys, then only the key whose kid matches with that of the JWT Header’s kid is used for verification.

Default value: Expression enabled$

Example: $keys
Extract into $token Required. Use one or more of the custom key properties to specify the location of the token in the request. If none are found, this rule passes the request to the next rule.
Custom Header Keys The name of one or more header keys to check for the token. Click + to add more.

Default value: N/A

Example: x-jwt-key
Custom Query String Parameter Keys The names of one or more query parameter keys to check for the token. Click + to add more.

Default value: N/A

Example: Auth

Custom Cookie Key The names of one or more cookie keys to check for the token. Click + to add more custom cookies.
Tip: In the request, the cookie value should contain the JWT.

Default value: N/A

Example: My_jwt
Authorization Header Type If the key is in the Authorization header, this value is used as the “type” to check. Bearer is the correct type for JWTs.

Default value: Bearer
Extract User Info Required. Specifies how to extract information about the user from the token claim.
User ID Expression Required. Where to find the user ID in the token claim.

Default value: N/A

Example: sub
Roles Expression Required. Where to find the user role in the token claim.

Default value: N/A

Example: role
Headers to add Optional. Name-value pairs to pass information from the token in the request header to pipeline parameters. For example, you might pass the user ID from the token claim so that the underlying pipeline can retrieve it in a parameter.

Example:

To pass the role and token in the header:
  • Name: role Value: $aud
  • Name: tempKey Value: request.uri.path
  • Name: keyID Value: $kid
  • Name: all Value: $
To retrieve the token in pipeline parameters, add a Mapper Snap and map the header values:
  • _ROLE > $aud
  • _TEMPKEY > $tempKey
  • _KEYID > $kid
  • _ALL > $all
Description The purpose of the rule.