JWT Policy

Description

The JWT Policy helps you to validate JWT Tokens by providing a signing key and also via JSON Web Key Set (JWK(S)).

You can also require claims, strip them, and/or forward them as header values to the backend API.

Plugin

{
    "groupId": "io.apiman.plugins",
    "artifactId": "apiman-plugins-jwt-policy",
    "version": "3.2.0-SNAPSHOT"
}

Configuration

Table 1. JWT Policy configuration
Option Type Description Default

requireJwt

Boolean

Require JWT Terminate request if no JWT is provided.

true

requireSigned

Boolean

Require Signed JWT (JWS). Require JWTs be cryptographically signed and verified (JWS). It is strongly recommended to enable this option.

true

requireTransportSecurity

Boolean

Require Transport Security Any request used without transport security will be rejected. JWT requires transport security (e.g. TLS, SSL) to provide protection against a variety of attacks. It is strongly advised this option be switched on.

true

stripTokens

Boolean

Strip tokens Remove any Authorization header or token query parameter before forwarding traffic to the API

true

signingKeyString

String

Signing Key or URL to a JWK(S) To validate JWT. Must be Base-64 encoded or you specify a URL to a JWK(S)

Empty

kid

String

Key ID (kid) of JWK(S) Only set this if you provided a JWK(S) URL. Specify here the kid of the JWK(S).

Empty

allowedClockSkew

Integer

Maximum Clock Skew Maximum allowed clock skew in seconds when validating exp (expiry) and nbf (not before) claims. Zero implies default behaviour.

0

requiredClaims

items[]

Required Claims Set whether to forward roles to an authorization policy.

None

forwardAuthInfo

forwardAuthInfo[]

Forward Claim Information Set auth information from the token into header(s).

None

items

Table 2. Require standard claims, custom claims and ID token fields (case sensitive).
Option Type Description Default

header

String

Claim Fields that the token must contain.

Empty

field

String

Value Value that must match with the value of the claim.

Empty

forwardAuthInfo

Fields from the JWT can be set as headers and forwarded to the API. All standard claims, custom claims and ID token fields are available (case-sensitive).

A special value of access_token will forward the entire encoded token. Nested claims can be accessed by using javascript dot syntax (e.g: address.country, address.formatted).

Table 3. Forward Keycloak token information
Option Type Description Default

headers

String

Header The header value to set (to paired field).

None

field

String

Field The token field name.

None

Sample Configuration

Example 1 (Signing Key)

{
  "requireJWT": true,
  "requireSigned": false,
  "requireTransportSecurity": true,
  "stripTokens": true,
  "signingKeyString": "Y29uZ3JhdHVsYXRpb25zLCB5b3UgZm91bmQgdGhlIHNlY3JldCByb29tLiB5b3VyIHByaXplIGlzIGEgZnJlZSBkb3dubG9hZCBvZiBhcGltYW4h",
  "allowedClockSkew": 0,
  "requiredClaims": [
    {
      "claimName": "sub",
      "claimValue": "aride"
    }
  ],
  "forwardAuthInfo": [
    {
      "header": "X-Foo",
      "field": "sub"
    }
  ]
}

Example 2 (JWK(S))

{
  "requireJWT": true,
  "requireSigned": true,
  "requireTransportSecurity": true,
  "stripTokens": false,
  "signingKeyString": "http://127.0.0.1:1080/jwks.json",
  "kid": null,
  "allowedClockSkew": 0,
  "requiredClaims": [
    {
      "claimName": "sub",
      "claimValue": "france frichot"
    }
  ]
}