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

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"
  ]
}