Open Banking Directory Usage - eIDAS release (Production) - v2.3

O


1. Version Control

VersionDateAuthorComments
DRAFT 1.0Open 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.

1.3 Open Banking Directory TeamUpdated text in 6. Create Software Statements: TPPs must upload an eIDAS certificate to be able to create a software statement.
1.4  Open Banking Directory TeamUpdated 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 Open Banking Directory TeamUpdated 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 Open Banking Directory TeamUpdated 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 Open Banking Directory TeamUpdated qcStatements in sections 3.2 and 4.2.
1.8 Open Banking Directory TeamUpdated text in section 9.
1.9Open Banking Directory TeamUpdated 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.0Open Banking Directory TeamUpdated link to eIDAS PSD2 manual.
2.1Open Banking Directory TeamUpdated to include CSR configuration flle generation within the DFI.
2.2 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 TeamUpdated 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;

  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:

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 RC2This specification defines two mechanisms for registering software with an ASPSP.
Directory SpecificationsThis 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.2This 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.
P19 Support for eIDAS Certificates in the OB EcosystemThis 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.
P19 - TPP EnrolmentThis 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:

  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.

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
1Client 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.

2DescriptionMust be set to a text string of your choice.Immutable
3The 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:

  • TPPs  populate this field when using an agent for the purposes of transparency and consistency.
  • ASPSPs display the information contained in this field to the PSU during their authentication journey, as well as, in their access dashboard, where applicable.

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

4Version

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
5Role

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
6Policy URIMust be set to a text string that represents a single Policy URI.Immutable
7Terms Of Service URIMust be set to a text string that represents a single Terms of Service URI.Immutable
8Client URIThe website or resource root URI.Immutable
9Logo URI

Link to the TPP logo.

Note: ASPSPs are not obliged to display images hosted by third parties.

Immutable
10Redirect 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
11Additional Redirect URIs

Additional Redirect URIs can be added by clicking the Add Redirect URI.

N/A
12ContinueClick the Continue button to create a new software statement.N/A
13An OAuth client will be generated automaticallySee Step 5: Client IdN/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.

4To deactivate software statement click on the Deactivate Statement button.
5If 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. 
6If it has individual signing keys and/or encryption keys they will be automatically removed and moved into the revoked JWKS and PEM stores. 
7The Deactivate Statement button is replaced with an Activate Statement button.
8To 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)GBC=GB
Organisation (O)OpenBankingO=OpenBanking
Organisational Unit (OU)<OrgID>OU=The unique identifier for the organisation.

Subject

Common Name

(CN)

<SoftwareID>CN=The Software Statement ID (SSID) for the software statement that the certificate has been created for the software

X509v3 extensions:

X509v3 Subject Alternative Name:

<Comma separated list of DNS names>

Each ASPSP must be able to accept a connection from a TPP who identifies themselves via an eIDAS certificate or UK RTS digital certificate.

For ASPSPs implementing the OBIE Standard, it is expected that ASPSPs will support only QWACs only for the purposes of identification. 


The organisation can include multiple DNS qualifed domain name(s) as a comma seperated list.

Auto-generated CSR

As an alternative to manually creating a CSR file, you also have the option to use the Directory to auto-generate a CSR on your organization's behalf. To do so, please follow the steps below:

1. Navigate to the Add Certificate section within the DFI and select the certificate and file types to be created.

2. Select the roles granted to your organization, to be included in your certificate.

   Including the SAN 

   Participants have the option of including the subject alternative name (SAN) in the CSR. Please note the following configuration rules applied to this attribute below:

  • Once a SAN is included as part of a submitted csr, the details are stored against the participant profile with the CA service provider. Subsequent requests to mint a csr will include the SAN by default.
  • If a CSR with a different SAN is submitted, it replaces the previous one stored with the CA.
  • A config change is required to disable default inclusion of the SAN. If the participant requires this, a service desk request can be submitted.


3. Review the properties which will be auto-populated to the CSR by the Directory.


4. Generate and save the CSR file to later upload and obtain your certificate.

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

Participants operating within the PSD2 domain may need to create digital certificates to support encryption and authentication within the ecosystem and Open Banking's network. This section explains the steps to create digital Open Banking non-ETSI certificates. TPPs operating in the PSD2 domain should only create Open Banking ETSI certifcates (see next section below):

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 Organisation details page click on the > symbol to the right of the newly created Software Statement.

        

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.

          

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.

The steps outlined above can also be used to generate obsigning certificates.



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 Organisation details 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 details 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 2.6 

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 or more software statements. 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

  • Ensure you are viewing the Organisation details page for your organisation
  • Ensure you can upload QWAC and QSEAL certificates using Dynamic Client Registration  (TPPs only) or via the DFI. 

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. 



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 organisation, 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 Payment 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.
  • You have loaded an organisation level certificate (e.g. OBWAC/OBSEAL or eIDAS).

Steps to create a Software Statement Assertion

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

Step 2: Scroll down to the Software Statement Assertion section and click 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:



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/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:
  • 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)

        


Example

{

"softwareStatementId": "6Rj1EIORw6cRB3q3x1YVgg",

"client Scopes": "AuthoritiesReadAccess ASPSPReadAccess TPPReadAll",

"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

}


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 10. Acquiring Access Token).

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

https://matls-ssaapi.openbankingtest.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.  Creating and managing ASPSP Authorisation and Resource Servers

As an ASPSP you can add URIs so that TPPs can find your authorisation servers and other end points. This can be done by using the “Add well-known URI” feature provided to ASPSPs. This section details the steps required to create and manage authorisation servers.

Before you start

  • You are an ASPSP. You are viewing the Organisation details page for your ASPSP.

Steps to add well-known URI

Step 1: Login to the system, select your ASPSP and scroll down to the Well-known URI section.

   

Step 2: Click on the Add new URI

            

Step 3: Enter the details.

Step 4: Click Submit button.

           


Notes:

  • 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

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 Step 10 above (Acquiring Access Token).

Steps to acquire ASPSP authorisation servers

Step 1: Send a HTTP GET request to:

              https://matls-api.openbankingtest.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.


17.  Obtaining an Organisation level OAuth Client

Below are the necessary steps needed to create, configure and update an Organisation level OAuth Client.

After the user selects a group of certificates for organisation level OAuth Client configuration, the system sends the certificates to the authorisation server. The subjectDN and issuerDN are extracted from the certificate, which are used to configure the new OAuth Client.

Before you start

  • Lists of certificates will now be grouped in the DFI (and in edit mode) by issuerDN and subjectDN
  • Details (subjectDN, issuerDN, organisation ID and organisation name) from the first certificate from the chosen group of certificates will be sent to the authorisation server and the API to update the OAuth Client. The API will also be accessible externally
  • Having an organisation OAuth Client will allow you to interact with DIR-API

Steps to create and configure an Organisation level OAuth Client

Step 1: Log-in to the DFI and navigate to the Organisation Details tab to see the Organisation level OAuth Client section.

Step 2: Click "Create" to open up a window. Here, you will see that there are currently no organisational OAuth Client certificates in use, and you will need to select a certificate group for Organisational OAuth Client:

picture1

Step 3: Select a group of certificates from the Eligible Certificates Groups section. Note: certificates will be grouped by issuerDN and subjectDN.

Step 4: Click "Save" to continue.

Step 5: A success notification will appear and your successfully configured organisational OAuth Client will appear in the Organisation Details tab alongside updated validity dates.

Steps to update an Organisational level OAuth Client

Step 1: Log-in to the DFI and navigate to the Organisation Details tab to see the Organisation level OAuth Client section.

Note: A blue tooltip will appear when some, not all, certificates are due to expire soon. The tooltip will indicate which certificates are due to expire soon.

Step 2: In the Organisation OAuth Client section, click "Edit" to open a modal window. 

In it you will see organisation OAuth Client certificates currently in use and eligible certificate groups:


Step 3: Select a group of certificates from the Eligible Certificates Groups section to update the configuration. Note: certificates will be grouped by issuerDN and subjectDN.

Step 4: Click "Save" to continue

Step 5: A success notification will appear and your successfully updated organisation OAuth Client will appear in the Organisation Details tab alongside updated validity dates.

Steps to update soon-to-expire Organisation level OAuth Client certificates

Step 1: Log-in to the DFI and navigate to the Organisation Details tab to see the Org-level OAuth Client section.

Note: A red tooltip will appear when all certificates are due to expire soon. 

Note: A yellow tooltip will replace the blue tooltip next to each certificate to indicate that they are all due to expire soon.  

Step 2In the Organisation OAuth Client section, click "Edit" to open a modal window. In it you will see organisation OAuth Client certificates currently in use and eligible certificate groups.

Step 3: Select a group of certificates from the Eligible Certificates Groups section to update the configuration.

Note: certificates will be grouped by issuerDN and subjectDN, and expired certificates will be automatically revoked and will not appear in the list of eligible certificate groups:

Step 4: Click "Save" to continue.

Step 5: A success notification will appear and your successfully updated organisation OAuth Client will appear in the Organisation Details tab with updated validity dates.

Note: In the event that there are no eligible certificates available to reconfigure the Organisation level OAuth Client, the notification below will appear upon clicking the "Edit" function:

When an Organisation level OAuth Client has expired and there are no eligible certificates available to update the configuration

Users must log-in to the DFI and navigate to the Organisation Details tab to see the Organisation OAuth Client section. If all certificates have expired a notification will appear highlighting this.

Note: the organisation OAuth Client cannot be used without a valid certificate being configured.

On clicking “Edit” the notifications below will be visible in the modal window if there are no eligible certificates available to reconfigure the Organisation level OAuth Client:


Note: Users must navigate to the Certificates tab to mint a new transport certificate and then configure the organisational OAuth Client to use it. 


Constraints on the API:

  • The OAuthDomain must be set to PSD2
  • The certificate as a request body and MIME type must be set to application/x-pem-file, and can only be OBWAC or QWAC type
  • Authorization is based on JWT  

Additionally, to modify an organisation OAuth Client, the user must have at least one of the following scopes in JWT:

  • ASPSPFullAccess
  • ASPSPManage
  • TPPFullAccess
  • TPPManage

To retrieve information about an organisation OAuthClient, the user must have at least one of the following scopes in JWT:

  • ASPSPReadAccess
  • ASPSPFullAccess
  • TPPReadAccess
  • TPPFullAccess

Notes:

In the participant's Organisation OAuth Client certificate list on the Organisation Details tab, if a certificate has less than 30 days left until expiration a yellow warning tooltip will appear informing the participant of the upcoming expiration. 

If all certificates have less than 30 days remaining, a red tooltip will appear with a call-to-action.


18.  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 Technical Directory Services page.

To understand how to use the API, please read the Directory API Swagger specification. This is an attachment to the Directory 2.0 Technical Overview DRAFT 1.2.



19.  Support

All queries, issues or support requests need to be routed through 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.



20. Definition of Terms

TermDescription
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, 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) and Card Based Payment Instrument Issuer (CBPII).

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

Card Based Payment Instrument Issuer (CBPII)A Card Based Payment Instrument Issuer is a payment services provider that issues card-based payment instruments that can be used to initiate a payment transaction from a payment account held with another payment service provider.
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 StatementA description of a TPP Client Application stored by OB and whose infomation is distributed to ASPSPs using an SSA.
Software IDUnique 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