1. Version Control

2. Introduction

The purpose of this How To Guide is for ASPSPs and TPPs who want to onboard their software with the Production/Live Open Banking Directory. 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 Production 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

3. Getting Started Checklist

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:

4.  Log in to the Directory Front End Interface (DFI)

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

Before you start you must check the following:

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

Steps to log in to the DFI

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.

5.  Access your ASPSP or TPP Records

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

Steps to identify your participant

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

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. 

The tabs at the top of page can be used to navigate each profile:

1. Organisation Details - this page displays the business information for the selected organisation.
2. Software Statements - this page displays software statements along with supporting functionality to create, activate and deactivate them. Participants can also create obtransport and obsigning certificates on this page.
3. Certificates - this page displays organisation level certificates only and provides supporting functionality to create, upload and revoke them. This tab is only visible in the PSD2 domain. To view software statement level certificates, go to the Software Statements tab.
4. Authorisation Servers - this page displays the list of established authorisation servers for an ASPSP organisation. Participants can also create new authorisaton servers on this page.

Searching for a Participant

If the organisation you want to view is not listed, you can search for it by entering the organisation name or ID using the search tool on the left side of your screen.

Select the authorisation domain (Pay.UK or PSD2) to refine your search criterion. 

From the search results click on the row for your organisation. This will open up the Organisation details page for your organisation.

6.  Create Software Statements

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.

Before you start

• Click on the "Software Statements" button for the organisation on the main Directory page. Alternatively, select the Software Statements tab at the top of your screen if you already have the organisation details displayed on your screen.

Steps to Create Software Statements

Step 1: Select the Software Statement tab.

Step 2: Click the Add new Software Statement button. 

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

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

7.  Create a Certificate Signing Request (CSR) for Open Banking non-ETSI certificates

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.

Before you start

• You have created a Software Statement for your Organisation.
•  You know the Software Statement Id as shown on the software statements screen. 

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

Steps to create CSR

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.

8.  Generate and manage Transport and Signing Certificates for Open Banking non-ETSI certificates

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.

Before you start

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

Steps to Create Certificates

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

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

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

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

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

9.  Generate and manage Transport and Signing Certificates for Open Banking ETSI certificates (OBWAC and OBSeal)

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

Before you start

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

Steps to create CSR

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

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.

Generate and manage OBWAC and OBSeal certificates

On the Organisation details 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.

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:

The certificates can be associated by selecting the check box for them. OBWAC and OBSeal certificates can be associated to one software statement.To dissociate a certificate from a software statement simply uncheck the Associated check box.  

10.  Upload and manage QWAC and QSeal (eIDAS) certificates 

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

Before you start

• You are viewing the summary page for your ASPSP or TPP. 
• You can upload QWAC and QSEAL certificates using /wiki/spaces/WOR/pages/616300677 (TPPs only).

Manage QWAC and QSeal certificates

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.

11.  Upload and manage signing and encryption keys

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.

12.  Create a Software Statement Assertion (SSA) signed by Open Banking

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

Before you start

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

Steps to create a Software Statement Assertion

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

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.

Notes:

• Open Banking Ltd.’s signature can be verified using the JWKs store located at  https://keystore.openbanking.org.uk/keystore/openbanking.jwks
• Open Banking’s Root and Issuing Certificates can be found at OB Root and Issuing Certificates for Production
• 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

13.  Acquiring an Access Token to access Open Banking Directory APIs

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

Before you start

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

Steps to acquire access tokens

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

Step 2: Copy the two private keys generated in Create Certificate Signing Request (CSR) – one for the signing certificate, one for the transport - to the relevant files in obdatat config folder replacing their empty equivalents (privateKeySigning.key, privateKeyTransport.key).

Step 3: Download the PEM files from the DFI for the signing and transport certificates. Upload them into the config folder replacing their empty equivalents (certSigning.pem, certTransport.pem)

Step 4: Edit obdatat/config/config.json and set the values of its keys as follows:

• SoftwareStatementId — the Software Statement ID (software_id) of the software statement created in Create Software Statements.
• Client Scopes — one of the following, matching the type of your organisation:
  • for a TPP, use ASPSPReadAccess TPPReadAccess AuthoritiesReadAccess
  • for an ASPSP, use ASPSPReadAccess TPPReadAll AuthoritiesReadAccess
• Key ID (K ID in image below) — the value of the kid parameter associated with the signing certificate generated in Generate a Transport/Signing Certificate Pair. (Please note that you need to use the signing certificate kid)

• TokenUrl — https://matls-sso.openbanking.org.uk/as/token.oauth2
• tppTestUrl — https://matls-api.openbanking.org.uk/scim/v2/OBAccountPaymentServiceProviders/

Example

{

"softwareStatementId": "6Rj1EIORw6cRB3q3x1YVgg",

"client Scopes": "AuthoritiesReadAccess ASPSPReadAccess TPPReadAll",

"keyId": "tH9CjyQ-kbJBZpPx81cp-CVny-o",

"tokenUrl": " https://matls-sso.openbanking.org.uk/as/token.oauth2 ",

"tppTestUrl":https://matls-api.openbanking.org.uk/scim/v2/OBAccountPaymentServiceProviders/

"aud": https://matls-sso.openbanking.org.uk/as/token.oauth2

}

Note: MATLS connections require the use of the host name; using the IP address will not result in a successful connection.

Step 5: Run the following command from the command line:

• npm start

The command will return an access token that can be used to access Open Banking Directory Services’ APIs. (see screenshot below)

Please note that Open Banking have provided the obdatat tool to help you understand how to acquire an access token. You can use any HTTP client that supports HTTPS and MATLS.

14.  Create a Software Statement Assertion (SSA) using an API call

Software Statement Assertions can also be created using APIs provided by Open Banking, an alternative to manual SSA creation via the DFI. This section explains the steps to create SSAs using the API.

Before you start

• You have created a Software Statement.
• You have a HTTP client that supports HTTPS with MATLS.

Steps to create a Software Statement Assertion using API

Acquire an Access Token (see section above on Acquiring Access Token).

Make a HTTP GET call using the access token and relevant scope to:

https://matls-ssaapi.openbanking.org.uk/api/v1rc2/tpp/<org_id>/ssa/<software_id>

org_id must be the Id of the TPP/ASPSP for which you want to generate an SSA.

software _id must be set to the Id of the Software Statement for which you want to generate an SSA; this is displayed under the Software Statement title at the top of the page (see below).

Client Scopes — use one of the following, matching the type of your organisation:

• for a TPP use TPPReadAccess
• for an ASPSP use ASPSPReadAccess 

15.  Acquiring the List of ASPSP Authorisation and Resource Servers

As a TPP you can get access to the authorisation servers of individual ASPSPs. This section explains how to retrieve ASPSP authorisation servers using Open Banking APIs.

Before you start

• You have acquired an access token - see Section above (Acquiring Access Token).

Steps to acquire ASPSP authorisation servers

Step 1: Send a HTTP GET request to

https://matls-api.openbanking.org.uk/scim/v2/OBAccountPaymentServiceProviders/

using Authorization: Bearer <access_token>

Bearer goes into the Authorisation header to obtain the list of ASPSPs

Step 2: Iterate over the response and filter for the AuthorisationServers

Notes:

• ASPSPs may provide a URL that defines their functional APIs using the input field labelled API Resource Discovery Endpoint.
• This information will be returned with the AuthorisationServers data.

16.  Using the Open Banking Directory APIs

Functionality that was previously only available via the DFI can now be accessed via Open Banking APIs:

• manage organisation contacts (CRU)
• manage software statements (CRU)
• generate software statement assertions
• upload/manage signing keys
• upload/manage encryption keys
• generate/manage OB non-ETSI certs
• generate OBWAC/OBSeal certs
• upload eIDAS QWAC/QSeal certs

The above require the generation of an organisational OAuth client.  The Dynamic Client Registration (DCR) service generates an organisational OAuth client. A full list of services is available on the /wiki/spaces/WOR/pages/1111785878 page.

To understand how to use the API, please read the Directory API Swagger specification here .

17.  Support

All queries, issues or support requests need to be routed through the JIRA Service Desk (JSD) (see Open Banking JIRA Service Desk for guidance on how to report a query or issue). 

JSD will be monitored throughout each day - Monday to Friday, 8am to 6pm UK time - and issues raised will be responded to as follows:

1. Urgent Support Requests:   As they occur depending upon priorities 
2. Queries: Daily morning triage will assign and respond according to priorities
3. Bugs: Daily triage will assign and respond according to priorities

Any critical blocking bugs will be addressed as they occur depending upon priorities.

18. Glossary of Terms

For further information on the terms used within this document please refer to the Glossary on the Open Banking website at www.openbanking.org.uk