How To

Creating Your Registration Payload

 

   

The Registration JWT

Your Registration Payload must be provided as a Signed JWT (JSON Web Token), a set of claims signed by the creator that can be decoded and verified using a public certificate by a third party.

A JWT is comprised of 3 parts:

  1. The Header, which contains details on how the JWT has been signed/encoded
  2. The Payload, a number of application specific claims, the details that the signature will be verifying
  3. The Signature, created using your Private Key, used to validate the payload is unmodified using a Public Certificate
The serialized and encoded JWT takes the form header.payload.signature

 
   
   

Creating Your Registration JWT

The steps below outline the process to assemble your Signed JWT / Registration Payload

1 
Create the JWT Header
 

Your JWT Header should include the following:

  1. The 'typ' claim, with a value of 'JWT'
  2. The 'alg' claim, with a value of 'PS256'
  3. The 'kid' claim, which should reflect the Key ID for the Key being used to sign the JWT
   
2 
Create the JWT Payload
 

Your JWT Payload will include a number of claims describing your App. These values will be sourced from a combination of your Software Assertion from the OBIE, Values taken from the Nationwide Well-Known endpoint and the OBIE speecification

Your JWT Payload will also include the Signed Software Assertion (SSA) for your APP, provided by the OBIE. The SSA has a limited lifetime (30 mins). It is advised to use a fresh SSA when assembleing your registration payload.

Please see the Registration Request Format table below for details on the claims that you need to include in the payload, or refer to the OBIE Specification for more in-depth details.
   
3 
Sign the JWT and Verify
 

Using the Signing Key associated with your App, sign the Registration JWT you have assembled in the previous steps.

You can verify the JWT has been signed correctly, using the appropriate key using JWT.io:

 
   
   

Registration Payload Claims

The list below outlines some of the values that should be used in the mandatory claims as part of your registration payload.
Certain values can be obtained from your OBIE provided SSA, and opthers from our Well-Known endpoint.

A full breakdown of the claims can be found in the OBIE DCR Specification

 

software_statement

       

This should be the JWT value of the SSA you receive from the OBIE.

redirect_uris

       

Value of this parameter should match ‘software_redirect_uris’ value in the TPP Software Statement, issued by the OBIE. It must be 2,000 characters or fewer and must not be an IP address.

scope

       

This should match what is on your SSA and should be written as "openid" and then followed by any one or all of the following values depending on your app requirements: "accounts", "payments", “fundsconfirmations”. This should be in a string format

iss 

  

The value should match the 'software_id' from your SSA

software_id

  

Mandatory field, which should be the `software_client_id` value taken from the SSA

exp

       

The expiry date should be in a Unix time stamp format and not wrapped in speech marks e.g "exp": 1536913020. This value must be greater than `iat` value and should be a future time value from the time of your app registration.

aud

       

This should be the Nationwide Org Id - 0015800000jf8aKAAQ

iat

       

This should be the equivalent Unix timestamp value of the time you try the registration. This should be provided in the Unix time stamp format and not wrapped in double quotes e.g "iat": 1536913020

response-types

       

Must be "code id_token" only

jti

       

A unique identifier for the JWT. The value must be a UUIDv4 GUID.

token_endpoint_auth_method

       

Your `token_endpoint_auth_method` value determines the authentication method you will use in requests to the /token endpoint and should be "tls_client_auth" or "private_key_jwt"

id_token_signed_response_alg

       

The expected algorithm that id_tokens will be signed with. Shold be PS256

token_endpoint_auth_signing_alg

       

Mandatory field for registrations if your token_endpoint_auth_method claim is private_key_jwt. Must be PS256

tls_client_auth_subject_dn

       

Mandatory field for registrations if your token_endpoint_auth_method claim is tls_client_auth. Must be the subject DN of your TLS certificate.

 

 
   
   

Verifying the JWT Signature

If you would like to verify the signature of you registration Payload JWT you cna use the steps below to do so on jwt.io

1  
Navigate To You .jwks Endpoint
 

Navigate to the .jwks endpoint for your application. This url can be found in your SSA against the claim 'software_jwks_endpoint'.
This lists all of the Key/Certificate pairs associated with your App, is where we will obtain your public certificate from.
   
2
Download the Public Transport Certificate
  Find the Key that has the 'kid' value you specified in your JWT header, this should have a 'use' value of 'tls'.
Download the Public Certificate for this key using the link in the 'x5u' value.
   
3
Input You JWT Claims ON JWT.io
  Open JWT.io in your browser, and paste your Signed JWT into the 'Encoded' input field on the left hand side of the screen.
This should now update the Header and Payload fields on the right hand side of the screen to reflect the claims you used when creating the JWT.
   
4
Verify your Certificate On JWT.io
  Paste the contents of the Public Certificate (including the Begin and End certificate lines) into the 'Public Key' section of the Verify Signature fields on the right hand side of the screen.
If your JWT payloads has been signed correctly using the appropriate Signing Key, you should see the message 'Signature Verified' below the Encoded JWT field.
   
   

Registration JWT Examples

Example Decoded Registration JWT

{
  "typ" : "JWT",
  "alg" : "PS256",
  "kid" : "anExampleKid"
}
{
  "software_statement" : "eyJhbGciOiJQUzI1NiIsImtpZCI6Ikh6YTl2NWJnR...vlsIOLNPA",
  "aud" : "0015800000jf8aKAAQ",
  "grant_types" : [ 
    "authorization_code", 
    "client_credentials", 
    "refresh_token" 
  ],
  "scope" : "openid accounts payments",
  "iss" : "VBgoz0UEnwpUoS07JDEzVL",
  "exp" : 1579520051,
  "iat" : 1579170789,
  "token_endpoint_auth_method" : "tls_client_auth",
  "tls_client_auth_subject_dn" : "CN=ExampleTppApp, OU=OBExamples, O=ExampleTPP, C=GB",
  "software_id" : "VBgoz0UEnwpUoS07JDEzVL",
  "jti" : "aff03404-b404-44c6-99f9-b994d0fdf611",
  "redirect_uris" : [
    "https://example-tpp.com/callback"
  ],
  "application_type" : "web",
  "id_token_signed_response_alg" : "PS256",
  "request_object_signing_alg" : "PS256",
  "response_types" : [ 
    "code id_token" 
  ]
}