/
JWT Authorization

This space is deprecated and no longer supported. Please use the latest available version here.

JWT Authorization

Owned by Chris Michael
Last updated: 05 Aug 2024
3 min read

This document sets out how a requestor should construct a jwt-auth header and how a receiver must validate the header.

1. Requirements for the requestor

1.1 Publication of signing keys on a JWKS

  1. The requestor must publish the URL of the JWKS that must be used to verify messages to the receiver.

  2. The JWKS must be publicly accessible over HTTPS.

  3. The requestor must use an asymmetric RSA key of 2048 bits or more.

  4. The requestor must ensure that the JWKS must have at least one signing key published. The key must have a unique kid on the JWKS.

  5. When publishing a new key, the requestor must wait for 10 minutes before issuing a message with the key (to allow the receiver’s caches to refresh).

1.2 Creating the authorisation header

  1. The requestor must ensure that the machine on which the signature is generated uses NTP to synchronise its clock.

  2. The requestor must construct the header and payload for the JWT as specified in JWT Authorization | JWT Auth Claims Reference .

  3. The JWT must be signed using the PS256 algorithm using a private key whose public part has been published on the JWKS.

  4. The JWT must be included as a bearer token in the authorization http header.

  5. The https request must be made over mutual tls. The client certificate used to initiate the mutual tls session must have a DN and OU that matches the values placed in the signature.

2. Requirements for the receiver

2.1 Verifying the authorisation header

  1. The receiver must ensure that the machine on which the signature is verified uses NTP to synchronise its clock.

  2. The receiver must ensure that the request was received over a mutual tls connection.

  3. The receiver must extract the jwt-auth token from the authorization http header.

  4. The JWT must verify the signature on the JWT using the kid specified in the JWS and the JWKS pre-specified by the sender.

  5. The receiver may cache the JWKS for up to ten minutes.

  6. The receiver must verify each of the claims in the JWT has the expected value specified in JWT Authorization | JWT Auth Claims Reference .

3. JWT Auth Claims Reference

3.1 Header

Claim Name

Expected Value

Mandatory

Notes

alg

PS256

Yes

 

typ

JOSE

Yes

 

cty

json

Yes

 

kid

The key ID of key-pair used to sign the message as published on the JWKS.

Yes

The specification does not support the use of other means of identifying the key as they are not considered to be secure enough (e.g. x5c and x5u are not supported).

3.2 Body

Claim Name

Expected Value

Mandatory

Example value for JWT issued by Ozone

Notes

iss

The organization O in the TLS certificate Subject that was used in the transport layer.

Yes

Ozone Financial Technology Limited

For a certificate with Subject of CN=931d3825-d7af-44d6-a59c-cff1ebb1131a,OU=94271194-ad90-4c39-b564-a080e7cb0bf1,O=RAIDIAM SERVICES LIMITED,C=UK, this would be set to RAIDIAM SERVICES LIMITED

sub

The organization unit OU in the TLS certificate Subject that was used in the transport layer.

Yes

 

For a certificate with Subject of CN=931d3825-d7af-44d6-a59c-cff1ebb1131a,OU=94271194-ad90-4c39-b564-a080e7cb0bf1,O=RAIDIAM SERVICES LIMITED,C=UK, this would be set to 94271194-ad90-4c39-b564-a080e7cb0bf1

aud

Identifier for the party receiving the JWT.

Yes

 

This must be set to the PROVIDER_ID specified by Ozone during configuration.

exp

Time when the JWT will expire in UTC seconds since epoch.

Yes

30

We recommend an expiry time of 10-30s.

When validating the JWT, allow for a 10s clock skew.

The JWT is considered invalid if the current time is greater than this value.

iat

Time when the JWT was issued in UTC seconds since epoch.

Yes

 

When validating the JWT, allow for a 10s clock skew.

The JWT is considered invalid if the current time is less than this value.

nbf

Time before which the JWT is invalid.

No

 

When validating the JWT, allow for a 10s clock skew.

The JWT is considered invalid if the current time is less than this value (when specified).

jti

A unique identifier for the JWT.

Yes

 

We recommend that the requestor populates this value with a uuidv4. This increases the entropy for the JWT.

© Ozone Financial Technology Limited 2024
Ozone Non Commercial Software EULA