json-web-token-jwt.md

description
This page provides the technical details of the JWT policy

JSON Web Token (JWT)

Overview

You can use the jwt policy to validate the token signature and expiration date before sending the API call to the target backend.

Some authorization servers use OAuth2 protocol to provide access tokens. These access token can be in JWS/JWT format. For the RFC standards, see:

• JWS (JSON Web Signature) standard RFC: https://tools.ietf.org/html/rfc7515
• JWT (JSON Web Token) standard RFC: https://tools.ietf.org/html/rfc7519

A JWT is composed of three parts: A header, a payload and a signature. Each must be base64 encoded. Examples can be found here: http://jwt.io.

• The header contains attributes indicating the algorithm used to sign the token.
• The payload contains information inserted by the AS (Authorization Server), such as the expiration date and UID of the user.
• The third and last part is the signature (for more details, see the RFC).

Functional and implementation information for the jwt policy is organized into the following sections:

• Examples
• Configuration
• Compatibility Matrix
• Errors
• Changelogs

Examples

{% hint style="warning" %} This policy can be applied to v2 APIs and v4 HTTP proxy APIs. It cannot be applied to v4 message APIs or v4 TCP proxy APIs. {% endhint %}

{% tabs %} {% tab title="HTTP proxy API example" %} Given the following JWT claims (payload):

{
  "iss": "Gravitee.io AM",
  "sub": "1234567890",
  "name": "John Doe",
  "admin": true
}

You can extract the issuer from JWT using the following Expression Language statement:

{#context.attributes['jwt.claims']['iss']}

{% endtab %} {% endtabs %}

Configuration

To validate the token signature, the policy needs to use the associated Authorization Servers public key.

The policy prompts you to choose between three (GIVEN_KEY, GIVEN_ISSUER, GATEWAY_ISSUER) methods to retrieve the required public key.

• GIVEN_KEY — You provide the key (in ssh-rsa, pem, crt or public-key format)
• GIVEN_ISSUER — If you want to filter on several authorization servers then you only need to specify the issuer name; the gateway will only accept JWTs with a permitted issuer attribute. If GATEWAY_KEYS is set, the issuer is also used to retrieve the public key from the gravitee.yml file.
• GATEWAY_KEYS — You can set some public keys in the APIM Gateway gravitee.yml file

policy:
  jwt:
    issuer:
      my.authorization.server:
        default: ssh-rsa myValidationKey [email protected]
        kid-2016: ssh-rsa myCurrentValidationKey [email protected]

The policy will inspect the JWT:

• Header to extract the key id (kid attribute) of the public key. If no key id is found then it use the x5t field.
  • If kid is present and no key corresponding is found, the token is rejected.
  • If kid is missing and no key corresponding to x5t is found, the token is rejected.
• Claims (payload) to extract the issuer (iss attribute).

Using these two values, the Gateway can retrieve the corresponding public key.

Regarding the client_id, the standard behavior is to read it from the azp claim, then if not found in the aud claim and finally in the client_id claim. You can override this behavior by providing a custom clientIdClaim in the configuration.

Phases

The phases checked below are supported by the jwt policy:

v2 Phases	Compatible?	v4 Phases	Compatible?
onRequest	true	onRequest	true
onResponse	false	onResponse	false
onRequestContent	false	onMessageRequest	false
onResponseContent	false	onMessageResponse	false

Options

The jwt policy can be configured with the following options:

Property	Required	Description	Type	Default
publicKeyResolver	true	Used to resolve the public key needed to validate the signature	enum	GIVEN_KEY
resolverParameter	false	Needed if you use the GATEWAY_KEYS or GIVEN_ISSUER resolver (EL support)	string
useSystemProxy	false	Select this option if you want use system proxy (only useful when resolver is JWKS_URL)	boolean	false
extractClaims	false	Select this option if you want to extract claims into the request context	boolean	false
clientIdClaim	false	Required if the client_id should be read from non-standard claims (azp, aud, client_id)	string

Confirmation Method validation options

The following options are specific to Confirmation Method validation:

Property	Required	Description	Type	Default
confirmationMethodValidation.ignoreMissing	false	Will ignore CNF validation if the token doesn’t contain any CNF information.	boolean	false
confirmationMethodValidation.certificateBoundThumbprint.enabled	false	Will validate the certificate thumbprint extracted from the access_token using the one provided by the client.	boolean	false
confirmationMethodValidation.certificateBoundThumbprint.extractCertificateFromHeader	false	Enabled to extract the client certificate from request header. Necessary when the M-TLS connection is handled by a proxy.	boolean	false
confirmationMethodValidation.certificateBoundThumbprint.headerName	false	Name of the header under which to find the client certificate.	string	ssl-client-cert

Attributes

The jwt policy can be configured with the following attributes:

Name	Description
jwt.token	JWT token extracted from the Authorization HTTP header
jwt.claims	A map of claims registered in the JWT token body, used for extracting data from it. Only if extractClaims is enabled in the policy configuration.

Compatibility matrix

The following is the compatibility matrix for APIM and the jwt policy:

Plugin version	Supported APIM versions
4.x+	4.0.x+
2.x+	3.18.x to 3.20
1.22.x+	3.15.x to 3.17.x
1.20.x to 1.21.x	3.10.x to 3.14.x
Up to 1.19.x	Up to 3.9.x

Errors

HTTP status code	Error template key
401	Bad token format, content, signature, expired token or any other issue preventing the policy from validating the token

You can use the response template feature to override the default response provided by the policy. These templates must be defined at the API level (see the API Console Response Templates option in the API Proxy menu).

The error keys sent by the policy are as follows:

Key	Parameters
JWT_MISSING_TOKEN	-
JWT_INVALID_TOKEN	-

Changelogs

{% @github-files/github-code-block url="https://github.com/gravitee-io/gravitee-policy-jwt/blob/master/CHANGELOG.md" %}