The purpose of this How To Guide is for ASPSPs and TPPs who want to onboard their software with the Open Banking Directory Sandbox. It is aimed at Primary Technical Contacts (PTC) and Secondary Technical Contacts (STC).

This guide describes the technical steps for creating and maintaining Software Statements, access tokens and ASPSP authorisation servers on the Directory Sandbox environment of the Open Banking Directory.

This guide is structured into these sections:

• Log in to the Directory Front End Interface (DFI)

• Accessing ASPSP and/or TPP records

• Creating Software Statements

• Creating a Certificate Signing Request (CSR) for OB ETSI like and OB non-ETSI certificates 

• Managing Transport and Signing Test Certificates including QWACs and QSeals (eIDAS certificates)

• Managing signing and encryption keys

• Creating Software Statement Assertions (SSA)

• Creating ASPSPs’ lists of Authorisation Servers

• Acquiring Access Tokens to consume API services

• Acquiring the list of Authorisation Servers

• Creating Software Statement Assertions (SSA) via API

• Using DFI features via API

The guide is intended for:

• ASPSP/TPP Primary Technical Contacts

• ASPSP/TPP Secondary Technical Contacts

• TSP Primary and Secondary Technical Contacts

Before you begin, it is highly recommended to go through this section first to ensure that you have all the relevant details;

1. You have been added to the Open Banking Directory as a Primary Technical Contact or Secondary Technical Contact.

2. You have installed node.js (latest build): https://nodejs.org/en/download/

3. You have the ability to run git on your computer. Git is available for all major operating systems. Git is available from https://git-scm.com/downloads and as a package for all major Open Source operating systems.

4. You have read the following:

This section describes how to log in to the Directory Front End Interface using two-factor authentication.

• You have been enrolled as an ASPSP, TPP or TSP in the Open Banking Directory. Please refer to the guide to complete enrolment - How To Guide: Enrolling Onto Open Banking.

• You have received a link to the DFI web application. The link should have been sent to the Primary Technical Contact’s (PTC) email address supplied to Open Banking as part of the onboarding process.

• Use either Chrome or Firefox web browsers to login to DFI for the best experience.

• For two-factor authentication, you will need a mobile phone (IoS or Android) with the Ping ID app installed. You can download the app from the Apple App Store or Google Play Store.

Step 1: Click on the link sent by Open Banking. (Note: this access is for the Primary Technical Contact specified in the submitted enrolment form)

Step 2: Go through the “Setting up your password” screens as described in the document - How To Guide: Enrolling Onto Open Banking.

Step 3: Follow the instructions on the screen to log in to the DFI web application.

Once you've logged in to the DFI, you will see a list of directory participants.

Step 1: Once you log in to the DFI you will see a list of ASPSP/TPP. 

Open

Step 2: Click on the particular row (or > button) corresponding to your ASPSP/TPP. This will open up the summary page for your ASPSP/TPP. 

Open

If you do not see your ASPSP/TPP in the list, then enter your ASPSP/TPP name or ID and click on search. From the search results click on the row (or > button) corresponding to your ASPSP/TPP. This should open up the summary page for your ASPSP or TPP.

Note: TPPs can see a list of ASPSPs, but not other TPPs. ASPSPs can see a list of all TPPs and ASPSPs. PTC and STC details can only be seen by PTCs or STCs of the same organisation. 

In order for TPPs and ASPSPs to communicate with each other they need to create Software Statements that uniquely identify their application. This section explains the steps to create Software Statements.

• You are viewing the summary page for your ASPSP or TPP.

Step 1: Scroll down to the Software Statements section 

Step 2: Click the Add new statement button. 

Open

Step 3: Complete the Add new Software Statement form as shown below:

Open

Step 5: Verify that the new Software Statement has been created. It should appear on the summary page for the ASPSP or TPP.

Open

ASPSPs and TPPs need to create digital certificates to encrypt messages over the public network, and sign requests. In order to create certificates, ASPSPs and TPPs need to create certificate signing requests. This section explains the steps to create a certificate signing request for Open Banking non-ETSI certificates.

• You have created a Software Statement for your Organisation.

•  You know the Software Statement Id as shown on the software statements screen. 

Open

• You know the Organisation ID of your organisation as shown on the Business Information screen.

Open

Using your own key generation and management policies, a public private key pair must be created. The following is an example using OpenSSL and is for illustration purposes only. 

Unix and Mac Users

• Open the text terminal window (command line) on your computer and run the following command:
  openssl req -new -newkey rsa:2048  -sha256 -nodes -out <software_statement_id>.csr -keyout <software_statement_id>.key -subj "/C=GB/O=OpenBanking/OU=<organisation_id>/CN=<software_statement_id>"

  Note: Keep O set to OpenBanking

The DN should be "/C=GB/O=OpenBanking/OU=<organisation_id>/CN=<software_statement_id>". There should not be any other fields in the DN.

Windows Users

• Install a bash shell emulater.

• goto the directory you want to create the CSR.

• Open the text terminal window (command line) on your computer and run the following command:
  openssl req -new -newkey rsa:2048  -sha256 -nodes -out <software_statement_id>.csr -keyout <software_statement_id>.key -subj "//C=GB\O=OpenBanking\OU=<organisation_id>\CN=<software_statement_id>"

  Note: Keep O set to OpenBanking

The DN should be windows escaped "//C=GB\O=OpenBanking\OU=<organisation_id>\CN=<software_statement_id>".

All Users

You will need to create two private keys and two CSRs - one for the transport certificate and the other for signing certificate.

The following table summarises the fields you will need to set in your CSR. If you add values to additional fields in your CSR tool, eg. State, the CSR will be rejected on upload.

TPP and ASPSPs need to create digital certificates to encrypt messages passing over the network between the participants (ASPSP/TPP) and OB network. This section explains the steps to create digital Open Banking non-ETSI certificates.

You need to have,

1. a transport certificate CSR

2. a signing certification CSR, and

3. both the CSRs are generated from two different private keys

Step 1: On the ASPSP or TPP summary page click on the > to the right of the newly created Software Statement.

Open

Step 2: Scroll down to the Add certificates section and upload the CSR to generate the Transport certificate. On upload the generated transport certificate appears in the Certificates section.

Open

Step 3: Upload the file for the OB Signing Certificate.

Open

Step 4: Click on the 3 dots on the right, and then click on Get PEM to download the certificates.

Open

If you need to revoke a certificate, click on the Revoke button to revoke the certificate.

The Open Banking Certificate Authority allows the generation and management of transport and signing certificates that have an ETSI profile, consistent with the structure of their equivalent eIDAS certificates (QWACs and QSeals).

• You are viewing the summary page for your ASPSP or TPP. Unlike Open Banking non-ETSI certificates, the OB ETSI certificates are not generated at the software statement level/screen, they are generated at the organisation level on the organisation's summary screen. 

To generate a valid CSR for an OBWAC or OBSeal please follow the instructions in the OpenSSL eIDAS PSD2 Certificate Signing Request Profiles v2.0.

Please note:

• If you use the obdatat tool referred to in Section 12 to successfully acquire an access token: '-nodes' must be added to the Openssl CSR generation command.

• If you copy and paste a QcStatement DER encoded line into your config file: line breaks or whitespaces may be introduced, which may invalidate your CSR.

On the summary page for your ASPSP or TPP, scroll down to the Organisation Certificates sections and upload your CSR for either an OBWAC or OBSeal. The following shows the Organisation Certificates section with several OBWACs and OBSeals.

Open

To the right of each certificate is a menu option (three stacked dots). Click on these and three options appear:

• JWKS - a link to the JWKS file

• Get PEM - a link to the PEM file

• Revoke - click to revoke the certificate

To associate an OBWAC or OBSeal certificate to a Software Statement select it to navigate to the Software Statement's detail screen. In the above case, the Keys/certificates section appears as follows:

Open

The certificates can be associated by selecting the check box for them. Note, OBWAC certificates can be associated to all Software Statements or just one Software Statement. OBSeal certificates can only be associated to one Software Statement.To dissociate a certificate from a Software Statement simply uncheck the Associated check box.  

The Open Banking Certificate Authority allows the upload and management of QWAC and QSeal certificates. 

• You are viewing the summary page for your ASPSP or TPP. QWAC and QSeal certificates are not uploaded on the Software Statement screen, they are uploaded at the organisation level on the organisation's summary screen. 

On the summary page for your ASPSP or TPP, scroll down to the Organisation Certificates sections and upload your QWAC and QSeal certificate. To associate a QWAC or QSeal certificate to a Software Statement select it to navigate to the Software Statement's detail page. The certificates can be associated and dissociated in the same way OBWACs and OBSeals in the section above. Note, QWAC certificates can be associated to all Software Statements or just one Software Statement. QSeal certificates can only be associated to one Software Statement.

Instead of the signing certificates mentioned above, signing keys can be used. On the Software Statement's detail page for your ASPSP or TPP, scroll down to the Keys/certificates section and upload your signing key. The certificates can be associated and dissociated in the same way OBWACs and OBSeals in the section above. Note, signing keys can only be associated to one Software Statement.

Encryption keys can be associated and dissociated in the same way as signing keys.

As a TPP you will need to create a software statement assertion and submit it to ASPSP to receive valid client credentials. These credentials are then used to access any Personal Service User (PSU) resource from the ASPSP. SSAs are essentially JSON Web Tokens (JWT) issued and signed by Open Banking.

There are two ways to generate Software Statement Assertions:

1. SSA generation using DFI Portal, described in this section

2. Dynamic SSA generation using the API, described in section 13. Create a Software Statement Assertion (SSA) using an API call

• You have created a Software Statement for TPP software that you want to register with an ASPSP.

Step 1: Go back to the ASPSP or TPP summary page and click on the newly created Software Statement.

Step 2: Scroll down to the Software Statement Assertion section and click the Generate

Open

Step 3: The SSA is displayed and can be copied to the clipboard. It can be used to on-board the associated Software Statement with an ASPSP. The plain text contents are also displayed.

Open

Notes:

• Open Banking Ltd.’s signature can be verified using the JWKs store located at  https://keystore.openbankingtest.org.uk/keystore/openbanking.jwks

• Open Banking’s Root and Issuing Certificates can be found at OB Root and Issuing Certificates for Directory Sandbox

• If your certificate is missing in your software jwks, it is most likely because you have not associated the certificate with the particular software statement

To access Open Banking Directory APIs you will need an access token. This section describes the steps required to acquire access tokens.

• Latest Long Term Support (LTS) version of Node.js and git installed on the computer used to acquire the access token.

• You have read the obdatat Readme file on git  https://github.com/OpenBankingUK/obdatat/tree/env-sandbox. For Directory Sandbox please make sure you clone or download the env-sandbox branch.

• Run the following command from the command line:

  • git clone git@github.com:OpenBankingUK/obdatat.git

• Run the following command from the command line:

  • cd obdatat

• Run the following commands from the command line:

  • npm install

Step 1: Make sure you are in the obdatat directory.