Json Web Token validator Policy documentation.

Phase

onRequest	onResponse
X

Context

Some authorization servers use oauth2 protocole to provide access tokens.

These access token can be on JWS/JWT format. (see below RFC)

JWS (Json Web Signature) standard RFC : https://tools.ietf.org/html/rfc7515

JWT (Json Web Token) standard RFC : (https://tools.ietf.org/html/rfc7519

JWT Example

A JWT is composed of three part : header, payload, signature. You can see some sample here : http://jwt.io

The header will contain attributes indicating the algorithm used to sign the token.

The payload contains some informations inserted by the AS (Authorization Server) such as expiration date, uid of the user, etc…

Both header & payload are encoded on Base64, so anyone can read the content.

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

Policy aim

Policy aims to validate the token signature & expiration date before sending the api call to the target backend.

Configuration

Property	Required	Description	Type	Default
publicKeyResolver	X	The way 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. (support EL)	string
extractClaims		Tick this option if you want to extract claims into the request context	boolean	false

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

The policy ask you to select among three (GIVEN_KEY, GIVEN_ISSUER, GATEWAY_ISSUER) way of retrieving the needed public key.

• GIVEN_KEY : You will provide a key (ssh-rsa KEY [email protected]) format.

• GIVEN_ISSUER : If you want to filter on a few authorization servers, then you only need to specify the issuer name. Thanks to that, the gateway will only accept JWTs having an allowed issuer attribute. As for the GATEWAY_KEYS, the issuer is also used to retrieve the public key from the gravitee.yml gateway settings.

• GATEWAY_KEYS : Some public key can be set into gravitee gateway settings

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

On this mode, the policy will inspect the jwt :

• header in order to extract the key id (kid attribute) of the public key. If none then we set it as ‘default’.

• claims (payload) in order to extract the issuer (iss attribute)

Thanks to both values, the gateway will be able to retrieve the corresponding public key.

Attributes

Name	Description
jwt.token	JWT token extracted from Authorization HTTP header.
jwt.claims	A map of claims registered into the JWT token body. Useful when you want to extract data from it. Only if extractClaims is enabled from policy configuration.

Extract data from JWT claims

If JWT claims (payload) are as follow:

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

You can extract the issuer from JWT by using EL:

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

Http Status Code

Code	Message
401	In case of bad token format, content, signature, expired token or any others problem which forbid the policy to validate the token

Contributors

For any comments, please use this github issue link : gravitee-io/issues#46