Skip to content

Gravitee Policy - JSON Web Tokens

License

Notifications You must be signed in to change notification settings

gravitee-io/gravitee-policy-jwt

Folders and files

NameName
Last commit message
Last commit date
Nov 23, 2024
Jul 20, 2023
Nov 7, 2024
Apr 16, 2021
Jan 21, 2022
Nov 7, 2024
Jan 21, 2022
Jul 13, 2016
Jul 31, 2024
Aug 2, 2016
Oct 7, 2020
Dec 7, 2024

Repository files navigation

JSON Web Token validator policy

Phase

onRequest onResponse

X

Description

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:

Compatibility with APIM

Plugin version APIM version

Up to 1.19.x

Up to 3.9.x

1.20.x to 1.21.x

3.10.x to 3.14.x

1.22.x

3.15.x to 3.17.x

2.x

3.18.x to 3.20

4.x

4.0.x to 4.3.x

5.x

4.4.x to latest

JWT

A JWT is composed of three parts: a header, a payload and a signature. You can see some examples here: http://jwt.io.

  • The header contains attributes indicating the algorithm used to sign the token.

  • The payload contains some information inserted by the AS (Authorization Server), such as the expiration date and UID of the user.

Both the header and payload are encoded with Base64, so anyone can read the content.

  • The third and last part is the signature (for more details, see the RFC).

Configuration

Property Required Description Type Default

publicKeyResolver

X

Used to resolve the public key needed to validate the signature

enum

GIVEN_KEY

resolverParameter

Needed if you use the GATEWAY_KEYS or GIVEN_ISSUER resolver (EL support)

string

useSystemProxy

Select this option if you want use system proxy (only useful when resolver is JWKS_URL)

boolean

false

extractClaims

Select this option if you want to extract claims into the request context

boolean

false

clientIdClaim

Required if the client_id should be read from non-standard claims (azp, aud, client_id)

string

Specific configuration for Confirmation Method validation

Property Required Description Type Default

confirmationMethodValidation.ignoreMissing

-

Will ignore CNF validation if the token doesn’t contain any CNF information.

boolean

false

confirmationMethodValidation.certificateBoundThumbprint.enabled

-

Will validate the certificate thumbprint extracted from the access_token with the one provided by the client.

boolean

false

confirmationMethodValidation.certificateBoundThumbprint.extractCertificateFromHeader

-

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

-

Name of the header where to find the client certificate.

string

ssl-client-cert

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 anEmail@domain.com
        kid-2016: ssh-rsa myCurrentValidationKey anEmail@domain.com

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.

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.

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']}

Errors

HTTP status code

Code Message

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

-