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 use a policy with a JWT Validator rule for authentication with the Try it out feature in APIM 3.0 Developer Portal.
You can configure the rule to extract values from the JWT claim to add and pass in the request header to the underlying pipeline. Selected JWT claims (or optionally the original token) can be forwarded 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 or expired, returns HTTP 401 Unauthorized.
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 rule authenticates the request and provides the security context that downstream policies (such as Authorize by Role) require. If another authentication policy has already set the security context, this rule skips itself.

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 following properties to specify where to find the token in the request. The rule checks locations in this order and uses the first match: Custom Header Keys, Custom Query String Parameter Keys, Authorization Header, Custom Cookie Key. If the token isn't found in any location, 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. Expressions that extract the user identity and role from the JWT claims. Both fields use JSONPath syntax where $ represents the root of the claims document.
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 A JSONPath expression that extracts the key material from the URL response. The default $ uses the entire response body as the key set.
Note: This rule supports a list of JWK keys or a single JWK key and verifies against the kid field in the JWT header. If you pass in a list of keys, only the key whose kid matches the JWT header’s kid is used for verification.

Default value: $

Example: $keys
Extract into $token Required. Use one or more of the following properties to specify where to find the token in the request. The rule checks locations in this order and uses the first match: Custom Header Keys, Custom Query String Parameter Keys, Authorization Header, Custom Cookie Key. If the token isn't found in any location, 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. Expressions that extract the user identity and role from the JWT claims. Both fields use JSONPath syntax where $ represents the root of the claims document.
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.