| Table of Contents |
|---|
1. Version Control
| Version | Date | Author | Comments |
|---|---|---|---|
| DRAFT 1.0 | Open Banking Directory Team | Initial Release. This document supersedes the Open Banking Directory Usage (Directory Sandbox) document. | |
| 1.1 | 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 | 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. |
2. Introduction
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.
...
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. |
| /wiki/spaces/DZ/pages/997065488Directory Specifications | 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). |
| Open Banking Security Profile – Implementer’s Draft v1.1.2 | 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. |
| /wiki/spaces/WOR/pages/363986945 | 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, in order to support the compliance of its participants and enable a well-functioning OB ecosystem. |
| /wiki/spaces/WOR/pages/616300677 | 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, in order to support the compliance of its participants and 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.1 |
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. |
...
- 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
...
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
...
| # | Notes | Description | Example |
|---|---|---|---|
| 1 | Client Name | Must be set to a text string of your choice. During the PSU consent flow, 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). | Example: ACME Limited Maximum length: 40 characters. |
| 2 | Description | Must be set to a text string of your choice. | |
| 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 | 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.). | |
| 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. | |
| 6 | Policy URI | Must be set to a text string that represents a single Policy URI. | |
| 7 | Terms Of Service URI | Must be set to a text string that represents a single Terms of Service URI. | |
| 8 | Client URI | The website or resource root URI. | |
| 9 | Logo URI | Link to the TPP logo. Note: ASPSPs are not obliged to display images hosted by third parties. | |
| 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. | |
| 11 | Additional Redirect URIs | Additional Redirect URIs can be added by clicking the Add Redirect URI. | |
| 12 | Continue | Click the Continue button to create a new software statement. | |
| 13 | An OAuth client will be generated automatically | See Step 5: Client Id |
...
Before you start
You need to have,
- a transport certificate CSR
- a signing certification CSR, and
- both the CSRs are generated from two different private keys
Steps to Create Certificates
...
- 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.openbankingtest.org.uk/as/token.oauth2
- tppTestUrl — https://matls-api.openbankingtest.org.uk/scim/v2/OBAccountPaymentServiceProviders/
Example
{
"softwareStatementId": "6Rj1EIORw6cRB3q3x1YVgg",
...
"keyId": "tH9CjyQ-kbJBZpPx81cp-CVny-o",
"tokenUrl": "https://matls-sso.openbankingtest.org.uk/as/token.oauth2",
"tppTestUrl":https://matls-api.openbankingtest.org.uk/scim/v2/OBAccountPaymentServiceProviders/
"aud": https://matls-sso.openbankingtest.org.uk/as/token.oauth2
...
- To edit the details click Edit URI button. (You can edit individual URIs.)
- To delete the details click Delete URI button. (You can delete individual URIs.)
- ASPSPs that have multiple brands can enter a Well-known URI per brand.
- ASPSPs can also enter a URL that defines their functional APIs using the input field labelled API Resource Discovery Endpoint.
- For ASPSPs who have created a discovery file using the discover file specification or the OBIE Functional Conformance Tool, please see this guide (https://bitbucket.org/openbankingteam/conformance-discovery/src/master/) on how to use this file as an API Resource Discovery Endpoint.
16. Acquiring the List of ASPSP Authorisation and Resource Servers
...
Step 1: Send a HTTP GET request to
https://matls-api.openbankingtest.org.uk/scim/v2/OBAccountPaymentServiceProviders/
using Authorization: Bearer <access_token>
...
19. Definition of Terms
| Term | Description |
|---|---|
| Open Banking Limited (OB) | The Open Banking Implementation Entity is the delivery organisation working with the CMA9 and other stakeholders to define and develop the required APIs, security and messaging standards that underpin Open Banking. |
| Account Servicing Payment Service Provider (ASPSP) | Account Servicing Payment Service Providers provide and maintain a payment account for a payer as defined by the PSRs and, in the context of the Open Banking Ecosystem are entities that publish Read/Write APIs to permit, with customer consent, payments initiated by third party providers and/or make their customers’ account transaction data available to third party providers via their API end points. |
| Third Party Providers / Trusted Third Parties (TPP) | Third Party Providers are organisations or natural persons that use APIs developed to Standards to access customer’s accounts, in order to provide account information services and/or to initiate payments. Third Party Providers are either/both Payment Initiation Service Providers (PISPs) and/or Account Information Service Providers (AISPs). |
| Technical Service Provider (TSP) | An unregulated Technical Service Provider who will only have access to the Directory Sandbox. |
| Payment Initiation Service Provider (PISP | A Payment Initiation Services Provider provides an online service to initiate a payment order at the request of the payment service user with respect to a payment account held at another payment service provider. |
| Payment Service Provider (PSP) | A legal entity (and some natural persons) that provide payment services as defined by PSD2 Article 4(11) |
| Account Information Service Provider (AISP) | An Account Information Service provides account information services as an online service to provide consolidated information on one or more payment accounts held by a payment service user with one or more payment service provider(s). |
| Payment Service User (PSU) | A Payment Services User is a natural or legal person making use of a payment service as a payee, payer or both |
TPP Primary Technical Contact (TPP-PTC) | A Primary Technical Contact is an individual nominated by a TPP to have access to the Directory and will be able to nominate other Directory technical users. This should be a main point of contact on technical configuration and a senior member of staff with responsibility for the management of the Open Banking digital identity. |
TPP Secondory Technical Contact (TPP-STC) | A person that carries out technical operations on behalf of a TPP. A TPP-STC has the same permissions as a TPP-PTC except for the ability to nominate other Directory technical users. |
ASPSP Primary Technical Contact (ASPSP-PTC) | A Primary Technical Contact is an individual nominated by the ASPSP to have access to the Directory and will be able to nominate other Directory technical users. This should be a main point of contact on technical configuration and a senior member of staff with responsibility for the management of the Open Banking digital identity. |
ASPSP Secondory Technical Contact (ASPSP-STC) | A person that carries out technical operations on behalf of an ASPSP. An ASPSP-STC has the same permissions as a ASPSP-PTC except for the ability to nominate other Directory technical users. |
| Software Statement | A description of a TPP Client Application stored by OB and whose infomation is distributed to ASPSPs using an SSA. |
| Software ID | Unique identifer for a TPP Client App that is scheme wide and can be used to revoke a TPP Client App. |
| Software Statement Assertion (SSA) | Software Statement Assertion represents a formalized assertion describing a TPP Client Application. It includes claims such as Client Name, Redirect URL etc. The SSA is emphermal and is short lived. |
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