Versions Compared

Version Old Version 1 New Version Current
Changes made by

Freddi Gyara

Isla Humphreys

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.
Expand
titleMENU
Table of Contents
stylenone

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

Requirements for the requestor

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).

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

...

When using JWT Authentication, the following claims should be included:

...

  1. as specified in https://openfinanceuae.atlassian.net/wiki/spaces/APIHubDocsv2/pages/edit-v2/126877708#JWT-Auth-Claims-Reference.

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

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

  4. 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.

Requirements for the receiver

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 https://openfinanceuae.atlassian.net/wiki/spaces/APIHubDocsv2/pages/edit-v2/126877708#JWT-Auth-Claims-Reference.

JWT Auth Claims Reference

Header

Claim Name

Expected Value

Mandatory

Notes

alg

PS256We can support RS256 as well if the ASPSP’s crypto libraries do not support RS256. However, PS256 is much more secure and follows FAPI recommendation

Yes

typ

JOSE

Yes

cty

json

Yes

kid

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

We recommend that only kid is used for key lookups with a pre-shared JWKS URL.

Other alternatives do not offer similar security and controls and are currently unsupported by Ozone.

...

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).

Body

Claim Name

Expected Value

Mandatory

Example value for JWT issued by OzoneExample value for JWT issued by ASPSP

Notes

iss

Mandatory

Should be set to be equal to the The organization O in the TLS certificate subject Subject that was used in the transport layer.

Yes

Ozone Financial Technology Limited

Bancorosa Limited

sub

Mandatory

Should be set to be equal to the 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 for MA in the transport layer.

Ozone UK Hub

Openbanking

aud

Mandatory

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

The providerId assigned to the tenant.

Ozone Financial Technology Limited

exp

Mandatory

Expiration time for 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 and .

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

30

30

iat

Mandatory.

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 epochThe resource server processing the header should reject the JWT .

Yes

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

The JWT is considered invalid if the current time is < iss (after allowing for clock skew)We recommend a 10s allowance for clock skewless than this value.

nbfOptional

Time before which the JWT is invalidThe resource server processing the header should reject the JWT .

No

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

The JWT is considered invalid if the current time < nbf (after allowing for clock skew)

We recommend a 10s allowance for clock skew.

NOT SENT

jti

Optionalis less than this value (when specified).

jti

A unique identifier for the JWT.

Uuid v4

UUID v4Yes

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