Open Banking Directory Usage - eIDAS release (Production) - v2.3
- 1 1. Version Control
- 2 2. Introduction
- 3 3. Getting Started Checklist
- 4 4. Log in to the Directory Front End Interface (DFI)
- 5 5. Access your Records
- 6 6. Create Software Statements
- 7 7. Create a Certificate Signing Request (CSR) for Open Banking non-ETSI certificates
- 8 8. Generate and manage Transport and Signing Certificates for Open Banking non-ETSI certificates - ASPSPs only
- 9 9. Generate and manage Transport and Signing Certificates for Open Banking ETSI certificates (OBWAC and OBSeal)
- 10 10. Upload and manage QWAC and QSeal (eIDAS) certificates
- 11 11. Upload and manage signing and encryption keys
- 12 12. Create a Software Statement Assertion (SSA) signed by Open Banking
- 13 13. Acquiring an Access Token to access Open Banking Directory APIs
- 14 14. Create a Software Statement Assertion (SSA) using an API call
- 15 15. Creating and managing ASPSP Authorisation and Resource Servers
- 16 16. Acquiring the List of ASPSP Authorisation and Resource Servers
- 17 17. Obtaining an Organisation level OAuth Client
- 17.1 Before you start
- 17.2 Steps to create and configure an Organisation level OAuth Client
- 17.3 Steps to update an Organisational level OAuth Client
- 17.4 Steps to update soon-to-expire Organisation level OAuth Client certificates
- 17.5 When an Organisation level OAuth Client has expired and there are no eligible certificates available to update the configuration
- 18 18. Using the Open Banking Directory APIs
- 19 19. Support
- 20 20. Definition of Terms
O
1. Version Control
Version | Date | Author | Comments |
|---|---|---|---|
DRAFT 1.0 | Jul 26, 2022 | Open Banking Directory Team | Initial Release. This document supersedes the Open Banking Directory Usage (Directory Sandbox) document. |
1.1 | Sep 3, 2019 | Open Banking Directory Team | Updated document in 3.Getting Started Checklist: Certificate profiles updated with OpenSSL eIDAS PSD2 Certificate Signing Request Profiles v2.1. Updated Description and Example for the On Behalf Of item in 6. Create Software Statements. |
1.2 | Oct 31, 2019 | Open Banking Directory Team | Updated screenshot in 15. Creating and managing ASPSP Authorisation Servers to show new input field: API Resource Discovery Endpoint. Updated text in 16. Acquiring the List of ASPSP Authorisation Servers to highlight the new field: API Resource Discovery Endpoint. |
1.3 | Mar 14, 2020 | Open Banking Directory Team | Updated text in 6. Create Software Statements: TPPs must upload an eIDAS certificate to be able to create a software statement. |
1.4 | Apr 23, 2020 | Open Banking Directory Team | Updated text in 7. Create a Certificate Signing Request (CSR) for Open Banking non-ETSI certificates to include details about the use of eIDAS certificates for identification purposes. |
1.5 | Sep 15, 2020 | Open Banking Directory Team | Updated text in 9. Create a Certificate Signing Request (CSR) for Open Banking non-ETSI certificates to include details about the use of eIDAS certificates for identification purposes. |
1.6 | Oct 22, 2020 | Open Banking Directory Team | Updated links to CSR profile document. Updated text in 5,6 and 10. TPPs can see other TPPs listed. Upload and manage QWAC and QSeal (eIDAS) certificates updated to make distinction between sandbox and production environments. Restrictions not applied in Sandbox post March 14 2020. Re-align with production. |
1.7 | Dec 21, 2020 | Open Banking Directory Team | Updated qcStatements in sections 3.2 and 4.2. |
1.8 | Dec 29, 2020 | Open Banking Directory Team | Updated text in section 9. |
1.9 | Feb 3, 2021 | Open Banking Directory Team | Updated to reflect the Technical Directory release to Confimation of Payee (CoP), ie. multi industry support . All screen shots updated and copy updated where necessary to reflect screen changes. |
2.0 | Mar 3, 2022 | Open Banking Directory Team | Updated link to eIDAS PSD2 manual. |
2.1 | Jan 2, 2023 | Open Banking Directory Team | Updated to include CSR configuration flle generation within the DFI. |
2.2 | Jan 2, 2023 | Open Banking Directory Team | Updated to include new screenshot in Chapter 6 Step 4 - referencing the need to upload a CSR. Updated to include Auto-generated CSR and SAN configuration settings in Chapter 7. Updated to include new screenshots in Chapter 8 Step 2. |
2.3 | 10 Mar 2023 | Open Banking Directory Team | Updated to include Chapter 17, outlining how to create and update an organisational OAuth Client. |
2. Introduction
The purpose of this How To Guide is for participants 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 Participant 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 Primary Technical Contacts (PTC) and Secondary Technical Contacts (STC) in the following domains:
ASPSPs
TPPs
TSPs
Crown Dependencies
3. Getting Started Checklist
Before you begin, it is highly recommended you go through this section first to ensure that you have all the relevant details;
You have been added to the Open Banking Directory as a Primary Technical Contact or Secondary Technical Contact.
You have installed node.js (latest build): https://nodejs.org/en/download/
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.
You have read the following:
Document | Description |
|---|---|
Open Banking JIRA Service Desk | How to record issues and support requests. This document is emailed to participants after enrolment. |
Open Banking OpenID Dynamic Client Registration Specification v1.0.0 RC2 | This specification defines two mechanisms for registering software with an ASPSP. |
This document provides an overview of the Open Banking Directory, its information architecture and functional capabilities. It links to the Directory API Specification (swagger spec). | |
This document outlines the differences between the Open Banking Security Profile and the FAPI R+W profile, with clauses and provisions necessary to reduce delivery risk for ASPSP Open ID Providers. | |
This document outlines the set of technical design changes required to the Open Banking Directory Platform with regards to the use of eIDAS certificates for cross-party identification. It outlines the technical components and the expected changes providing the requirements it should adhere to, to enable a well-functioning OB ecosystem. | |
This document outlines the set of technical design changes required to the Open Banking Directory Platform to enable support for API based enrollment of TPPs with regards to the use of eIDAS certificates for cross-party identification. It outlines the technical components and the expected changes providing the requirements it should adhere to, to enable a well-functioning OB ecosystem. This will be used to inform the detailed design and implementation activities to align the OB Directory Platform with PSD2 Regulatory Technical Standards (“RTS”) and support the related eIDAS requirements. |
5. You will be referred to further documents. Please check that you have access to the following documents and submit a request for access to the Service Desk if you don't:
Document | Description |
|---|---|
OpenSSL eIDAS PSD2 Certificate Signing Request Profiles v2.6
|  This document outlines the general procedure to generate Certificate Signing Requests (CSR) for Open Banking Public Key Infrastructure (PKI). It focuses on the method required to generate a CSR for Open Banking ETSI like certificates (OBWAC, OBSeal). It includes configuration files to generate CSRs for OBWAC and OBSeal certificates using OpenSSL. Also, example DER encoded QC Statements for all combinations of PSD2 roles. |
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 a participant for one or more authorisation domains (PSD2 or Confirmation of Payee) 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 Records
Once you've logged in to the DFI, you will see a search tool on the left hand side of your screen and the list of your organisations on the right hand side. Where participants feature in one or more domains, they will be listed twice with a label denoting which authorisation domain each entry belongs to (i.e. Pay.UK or PSD2).
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 "Organisation Details" button for the participant you are interested in. This will open up the Organisation details page for your organisation.
The tabs at the top of page can be used to navigate each profile:
Organisation Details - this page displays the business information for the selected organisation.
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.
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.
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.
Note: PTC and STC details can only be seen by PTCs or STCs of the same organisation. PTCs and STCs will only see listed the organisation they have access to in the respective domains.
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 shown below:
# | Notes | Description | Mutability | Notes |
|---|---|---|---|---|
1 | Client Name | Must be set to a text string of your choice. During authentication, ASPSPs will display this field as the company trading name requesting access to PSU data. Ensure the name provided is representative of the trading name of the organisation. The trading name should be a name that is registered at your National Competent Authority (NCA). | Immutable | Example: ACME Limited Maximum length: 40 characters. |
2 | Description | Must be set to a text string of your choice. | Immutable |
|
3 | The On Behalf Of attribute supports Onward Provisioning | The “On Behalf of” field enables the TPP to provide the details of their agent to the ASPSP by including these within the payload. The ASPSP can then present this information to the PSU by displaying both the agent’s name and the regulated TPP’s name. The CEGs* require that if the customer-facing entity is acting on behalf of a TPP as its agent, the TPP must make the PSU aware of this relationship. The “On Behalf of” field is classified as optional for implementation, however, it is encouraged that:
*Currently this is a CEG requirement for AISPs only | Immutable | Example : The Regulated party is ACME, a registered TPP enrolled onto the Open Banking Directory. They wish to identify another party, ABC Agent, who is an agent acting on behalf of ACME who directly interacts with the ASPSP/ PSU on behalf of ACME. ACME would like the PSU to be informed about ABC Agent in the domain of their ASPSP and would therefore input ABC Agent in the On Behalf Of field. |
4 | Version | Software Version must be set to a numeric value, an integer (e.g. 1) or a floating-point number (1.2, 2.2, 3.2 etc.). | Immutable |
|
5 | Role | Default shows PSD2 role as selected based on the organisation's PSD2 roles as registered on enrollment. A TPP may have a several roles and can select one specific role for the software statement or all the registered roles. No role - this can be selected to create a software statement with an Oauth client that can be used to monitor APIs, but without the risk of it being misused to transact with Read/Write APIs. | Immutable |
|
6 | Policy URI | Must be set to a text string that represents a single Policy URI. | Immutable |
|
7 | Terms Of Service URI | Must be set to a text string that represents a single Terms of Service URI. | Immutable |
|
8 | Client URI | The website or resource root URI. | Immutable |
|
9 | Logo URI | Link to the TPP logo. Note: ASPSPs are not obliged to display images hosted by third parties. | Immutable |
|
10 | Redirect URI | Redirect URIs must be set to a text string that represents a single redirect URI. Wild cards are not allowed; port numbers are not allowed - defaults to https/port 443. | Immutable |
|
11 | Additional Redirect URIs | Additional Redirect URIs can be added by clicking the Add Redirect URI. | N/A |
|
12 | Continue | Click the Continue button to create a new software statement. | N/A |
|
13 | An OAuth client will be generated automatically | See Step 5: Client Id | N/A |
|
Step 4: Verify that the new Software Statement has been created. It should appear on the summary page for the ASPSP or TPP.
Notes | |
|---|---|
| 1 | The software statement ID (software_id) appears below the software statement name (i.e Test in the above example). |
| 2 | The OAuth client ID (software_client_id) is the Client Id. |
| 3 | The software statement ID and OAuth client ID are given the same value. |
| 4 | To deactivate software statement click on the Deactivate Statement button. |
| 5 | If it has individual transport and signing certificates they will be automatically revoked and moved into the revoked JWKS and PEM stores in the case of OBWACs/OBSeals and OB non-ETSI certificates. QWACs and QSeals will be automatically removed and moved into the revoked JWKS and PEM stores. |
| 6 | If it has individual signing keys and/or encryption keys they will be automatically removed and moved into the revoked JWKS and PEM stores. |
| 7 | The Deactivate Statement button is replaced with an Activate Statement button. |
| 8 | To reactivate the software statement click the Activate Statement button. The transport and signing certificates will have to be generated manually in the case of OBWACs/OBSeals and OB non-ETSI certificates. OBWACs, OBSeals, signing and encryption keys will have to be reassociated with the software statement. |
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, which are often referred to as OB Legacy certs.
Before you start
Check you have created a Software Statement for your Organisation.
Check you have the Software Statement Id as shown on the software statements screen to hand
If you are using openssl, ensure you are running v1.1.1 or above.
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 to manually create a CSR. This 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.
Assign the roles in your configuration file, the Directory will prepopulate the remaining fields. The table below lists which should be set in your configuration file. If additional fields are included in the file, (eg. State), the CSR will be rejected on upload.
Logical Field Name | Expected Values | Description |
|---|---|---|
Signature Hash Algorithm (signatureHashAlgorithm) | sha256 |
|
Country (C) | GB | C=GB |
Organisation (O) | OpenBanking | O=OpenBanking |
Organisational Unit (OU) | <OrgID> | OU=The unique identifier for the organisation. |
Subject Common Name (CN) |