Table of Contents | ||||
---|---|---|---|---|
|
Version Control
Version | Date | Author | Comments | ||||
---|---|---|---|---|---|---|---|
DRAFT 1 | Open Banking Directory Team | Initial Release. This document supersedes the Open Banking Directory Specification v1.3. Technical details in the OB Directory Specification v1.3 have for the most part been moved to the Directory API Swagger Specification, and this document should be read in conjunction with this specification, which can be accessed via the GitHub link below:
| |||||
Draft v1.1 | Open Banking Directory Team | General Links to the Directory API Swagger Specification within the document content have been replaced with the GitHub link above. Links to the Directory Sandbox Usage document within the document have been replaced with links to Open Banking Directory Usage - eIDAS release (Directory Sandbox). Added Appendix C - Certificate profiles with an embedded document that outlines the general procedure to generate Certificate Signing Requests (CSR) for Open Banking Public Key Infrastructure (PKI). This includes example DER encoded QC Statements for all combinations of PSD2 roles. Manage Certificates and Keys Replaced the P19 Support for eIDAS Certificates in the OBIE Ecosystem link with a reference to Appendix C documentation in the section eIDAS Certificate Properties. Replaced the Certificate Profiles link with a reference to Appendix C documentation in the section Open Banking ETSI Conformant Certificates. | |||||
Draft v1.2 | Open Banking Directory Team | Update to Appendix A - SCIM resources Swagger specification, replacing the linked text with a GitHub link:
| |||||
v1.3 | Open Banking Directory Team | Copy enhancements to the following sections: Introduction Primacy of FCA Register and registers maintained by other National Competent Authorities Use of eIDAS Certificates Open Banking Certificate Authority Open Banking Non-ETSI Certificate Properties Revocation of Account Servicing Payment Service Providers Certificates Updated the associations for QSeal and OB Seal in the table in the section Manage Certificates and Keys - Overview. Updated Appendix C - Certificate profiles with an updated version of OpenSSL eIDAS PSD2 Certificate Signing Request Profiles, now v2.1. | |||||
v1.4 | Open Banking Directory Team | Updated Appendix C - Certificate profiles with an updated version of OpenSSL eIDAS PSD2 Certificate Signing Request Profiles, now v2.2. | |||||
1.5 | Open Banking Directory Team | Updated Appendix C - Certificate profiles with an updated version of OpenSSL eIDAS PSD2 Certificate Signing Request Profiles, now v2.3 | |||||
1.6 | Open Banking Directory Team | Updated links to version 2.3 of usage guidelines. | |||||
1.7 | Open Banking Directory Team | Updated links to version 2.4 of usage guidelines. |
Overview
Introduction
The Open Banking Directory is the key Architectural Component that enables Third Party Providers (TPPs)to enrol onto the Open Banking Directory and initiate interactions through APIs with Account Servicing Payment Service Providers (ASPSPs). At its core the Directory is an identity and access management service providing identity information supporting natural persons, organisations and software identity classes.
...
- Manage Identities and Access: The ability to issue and manage identity records for organisation and natural persons that interact with the Open Banking Directory
- Manage Certificates and Keys: The ability to upload, manage and remove eIDAS certificates (QWACs and QSeals), signing keys and encryption keys. The ability to issue, manage and revoke OB digital certificates.
- Manage Directory Information: The ability to update and find information maintained in the Directory - either through APIs and / or a self-service user interface (UI) delivered as a web application.
Design Principles
Adoption of Open Industry Standards
As far as feasible, the design of the Open Banking Directory will be based on industry standards that are open and widely adopted rather than building a new standard from scratch.
Primacy of FCA Register and registers maintained by other National Competent Authorities
Participants must be authorised or registered with their competent authority. The FCA Register will be the primary source of participants that can be added to the Open Banking Directory with PSD2 Authorizations in the UK. Participants that have a passport through their national competent authority register to operate in the UK can also be added to the Open Banking Directory.
Use of eIDAS Certificates
The OB solution allows for the use of eIDAS certificates as a means of asserting firm identities during the onboarding process. Participants holding a QWAC will be able to dynamically register whilst asserting their regulatory status and assured identity. Open Banking will add the additional member state authorisations to an organisation record as this information is not provided under eIDAS.
High Level Use Cases
TPP only
Drawio | ||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
|
ASPSP only
Drawio | ||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
|
TPP and ASPSP
Drawio | ||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
|
Entity Class Model and Visibility
Entity Class Model
Drawio | ||||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
|
Dynamic Client Registration with Open Banking
TPPs with valid eIDAS (QWAC) certificates will be able to dynamically register in Production with the Directory by using the Directory API. Please refer to the Directory API Swagger Specification for details regarding the API, which can be accessed via the GitHub link below:
Github link macro link https://github.com/OpenBankingUK/directory-api-specs
The process for enrolling on the Sandbox, and to Production via the non-dynamic route, is documented separately in Enrolling onto the Open Banking Directory - How To Guide.
Manage Certificates and Keys
Overview
The following matrix shows the possible associations between transport, signing and encryption materials, and organisations/software statements.
QWAC | QSeal | OB WAC | OB Seal | OB Transport | OB Signing | Signing Keys | Encryption Keys | |
Associated with Organisation | ||||||||
Associated with Software Statement |
eIDAS Certificate Properties
eIDAS certificates (QWACs and QSeals) can be uploaded and associated to software statements. This can be done via the Directory Front End Interface or programmatically via the Directory API. Examples of QWACS and QSeals with details of their properties are provided in Appendix C - Certificate Profiles.
Open Banking Certificate Authority
The Open Banking Certificate Authority (CA) engages with trust service provider, who supports OBIE in the provision of a technical managed service on its behalf. The Trust Service provider supports OBIE in the provision of ETSI conformant certificates (OB WACS and OB Seals) and non-ETSI conformant certificates (OB transport and OB signing certificates).
Open Banking ETSI Conformant Certificates
The properties for OB WACS and OB Seals are detailed in Appendix C - Certificate Profile.
Open Banking Non-ETSI Certificate Properties
The certificates will have the properties listed in the following table.
...
Logical Field Name | Description |
---|---|
Version | All certificates will be X.509 v3 certificates |
Serial Number | The serial number for the certificate |
Signature Algorithm | The signature algorithm used for signing the certificate. Certificates will be RSA certificates. |
Issuer | A DN representing the issuer of the certificate (Open Banking). The structure of the DN is to be confirmed. |
Validity | The date range for which the certificate will be valid |
Subject | A distinct name identifying the subject of the certificate. DN: C=GB O=OpenBanking OU=organisation_id CN=software_statement_id |
Public Key | The public key corresponding to the private key with which the certificate was signed. |
Key Usage | An indication of whether the key will be used for transport (MATLS), encryption or signing. |
Domain names | List of domain names that are valid for the certificate |
CRL URL | A hyperlink referring to the CRL for the CA that issued the certificate. |
OCSP URL | A url referring to the OCSP service for the CA that issued the certificate |
Supported Ciphers
The Open Banking Directory will only support the generation of certificates using RSA.
...
Section 8.6 states that only PS256 or ES256 should be supported for signing. As the Open Banking certificates are RSA certificates, Open Banking will only support PS256 for signing SSAs and SSO ID Tokens. Participants could upload PS256 or ES256 keys as signing or encryption materials for software statements. ASPSPs advertise support for algorithms on their well known endpoints and TPPs will need to use algorithms supported by them.
References to standards
The design decisions for these capabilities have been based on the following standards:
...
Server Name Indication: https://tools.ietf.org/html/rfc6066
Issue Open Banking Certificates
Using the Directory Front End Interface
Using the Directory Front End Interface, Primary Technical Contacts will be able to paste in a Certificate Signing Request (CSR) that they wish to associate with a given software record. The CSR will be validated ensuring:
...
Step by step instructions have been published in the updated Open Banking Directory Usage - eIDAS release (Directory Sandbox).
Using the Directory API
Alternatively, participants can issue certificates programmatically via the Directory API. Step by step instructions have been published in the updated Open Banking Directory Usage - eIDAS release (Directory Sandbox). Also, please refer to the Directory API Swagger Specification for details regarding the API, which can be accessed via the GitHub link below:
Github link macro link https://github.com/OpenBankingUK/directory-api-specs
Revoke Open Banking Certificates
Revocation of Account Servicing Payment Service Providers Certificates
Should an ASPSP lose their regulatory status for a given role or voluntarily withdraw from Open Banking, all software that was registered with that role contained in the collection of software_roles will also be removed. Additionally, all Authorization Server Information that describes technically how to interact with the ASPSP will be removed.
Revocation of Third Party Providers Certificates
Should a Third Party Provider lose authorisation/registration for a given role or voluntarily withdraw from Open Banking, all software that was registered with that role contained in the collection of software_roles will also be removed.
Effect of revocation on software statements
Software Statements associated with organisations have the following characteristics:
...
- The status field will be changed to inactive.
- The KeyIDs for signing, encryption and transport materials cleared of any values.
- Any OB issued certificates associated with this software statement revoked from the OB CA which will result in a new CRL being generated and this certificate returning revoked states from the OCSP service.
- The certificates or keys associated with this software statement will be removed from the active JWKS and will be moved to the revoked (inactive) JWKS.
Check Certificate Status
ASPSPs have four mechanisms available to them to identify the revocation of TPPs and/or their apps:
- Check certificate revocations through OCSP
- Check certificate revocations through CRL
- Check certificate / key presence on active JWKS hosted by Open Banking
- Call SCIM APIs to identify the state of the participant
OCSP
Open Banking's CA will provide an OCSP endpoint. Its location will be minted into certificates issued by the CA into the authority information access extension specified above.
CRL
As a backup, should OCSP be unavailable, the certificate authority will mint multiple CRL locations as per the specification above.
...
Should there be a discrepancy in speed of propagation between hosting locations, then the order in which the CRL end points will be minted in the CA will be from the fastest to the slowest.
Open Banking Certificate Lookup
The Directory will provide a publicly available store of all OB issued digital certificates implemented as a set of JSON Web Key Stores (JWKS).
Key Stores
The Directory will provide a number of key stores:
...
Additionally, The Directory will also publish all the certificates that it issues as PEM files in a specified folder.
JWK Structure
Each key store will consist of a JSON object with a root attribute of keys. This will be an array of JSON Web Keys with the following claims:
Claim | Description |
---|---|
kty | Key type. This can be EC or RSA |
use | Usage for the certificate This can be sig, tls or enc |
key_ops | The key operations supported by this public key contained in the certificate |
kid | The SHA-1 hash of the JWK Fingerprint |
x5u | A URL that can be used to retrieve the PEM file for the corresponding X.509 certificate. The PEM file will contain the entire certificate chain |
x5c | This will consist of an array with a single element. The element will be a base64 representing of the X.509 certificate's PEM format representation. (The JWKS standard allows us to provide a certificate chain as the other elements of the array. However, in order to constrain the size of the JWK, we will only provide the certificate without its chain. If the consumer requires the entire chain, it can be downloaded through the x5u claim. |
x5t | The SHA-1 hash of the DER Encoded Certificate https://tools.ietf.org/html/rfc7515.html#section-4.1.7 |
x5t#s256 | The SHA-256 hash of the DER Encoded Certificate https://tools.ietf.org/html/rfc7515.html#section-4.1.8 |
Open Banking Certificate Lifecycle
Certificate Generation
When a PSP generates a certificate (through the DFI or API software statement creation process), the following JWKS actions will be carried out:
- The JWK will be added to the organisation's active JWKS
- The JWK will be added to the software statement's active JWKS
- A PEM fill will be generated and added to the active PEM folder
Certificate Expiry
At the end of each day, a batch process will check for certificates that have expired and will carry out the following JWKS related actions:
- The certificate will be removed from the organisation's active JWKS
- The certificate will be removed from the software statement's active JWKS
- The certificate will be added to the organisation's inactive JWKS
- The certificate will be added to the software statement's inactive JWKS
Certificate Revocation
When a certificate is revoked, the following JWKS related actions will be carried out.
...
This is in addition to CRL and OCSP changes that will be carried out by the CA.
Accessing Open Banking's Signing Certificates
The certificates used by Open Banking for signing software statements can be retrieved through the active and inactive stores just like any other organisation.
...
The JWK x5u parameter can subsequently be used to retrieve PEM representations of the certificates.
Manage Directory Information
Generate Software Statement Assertion
A TPP-PTC can generate and download a software statement assertion through the Open Banking Directory User Interface.
...
Step by step instructions are provided in the Open Banking Directory Usage - eIDAS release (Directory Sandbox) document.
Retrieving a Signed Software Statement (Software Statement Assertion)
Allows authenticated clients to retrieve a Software Statement Assertion for the given software_id.
...
Step by step instructions are provided in the Open Banking Directory Usage - eIDAS release (Directory Sandbox) document.
Retrieving a software statement using SCIM APIS
As an alternative to retrieving a Software Statement Assertion, or at any point in time, an ASPSP can retrieve the software statement through the SCIM APIs.
...
Code Block | ||||
---|---|---|---|---|
| ||||
https://api.openbanking.cc/scim/v2/OBThirdPartyProviders ?filter=(urn:openbanking:softwarestatement:1.0:SoftwareStatements [Id eq "acfa0d4a-cb33-4867-9bb7-374ca7222b65" and Active eq true] ) and urn:openbanking:competentauthorityclaims:1.0:Authorisations[ MemberState eq "GBR" and Psd2Role eq "PISP" and Status eq "Active" ]) &attributes=totalResults |
Discover ASPSPs
A TPP can discover details of all the ASPSPs onboarded onto the Open Banking Directory by using the APIs described in the section Get PSP Identity Record.
Get PSP Identity Record
The Open Banking Directory provides a set of APIs to allow participants to query identity records of all the participants on the Directory.
...
In order to access the resource, the participant must first get an access token through a client credentials grant.
Scopes
Name | Description |
---|---|
AccountsReadAccess | Read access to OBAccounts resource |
ASPSPReadAccess | Search on OBAccountPaymentServiceProviders for match on Organisation Id returns ASPSP record minus Personal Account Roles Information |
AuthoritiesReadAccess | Read access to OBAuthorities resource |
QTSPReadAccess | Read access to the OBQualifiedTrustServiceProviders resource |
TPPReadAccess | Bulk search on OBThirdPartyproviders returns TPP record plus personal account roles information |
TPPReadAll | Search for OBThirdPartyProviders for match on Organisation Id returns TPP record minus personal Account Roles Information |
Mapping of Scopes to External Actors
AccountsReadAccess | ASPSPReadAccess | TPPReadAccess | TPPReadAll | AuthoritiesReadAccess | QTSPReadAccess | Client Type | |
---|---|---|---|---|---|---|---|
Account Servicing Payment Service Provider (ASPSP) | NO | YES | NO | YES | YES | YES | ASPSP Client |
Third Party Providers / Trusted Third Parties (TPP) | NO | YES | YES | NO | YES | YES | TPP Client |
End-points
Resource | HTTP Operation | Endpoint | Scope | Response Object | Fine Grained Policy |
---|---|---|---|---|---|
OBAccounts | GET | GET /scim/v2/OBAccounts | AccountsReadAccess | OBAccount | Only the authenticated user's object can be retrieved from this end point. |
OBAccountPaymentServiceProviders | GET | GET /scim/v2/OBAccountPaymentServiceProviders | ASPSPReadAccess | OBAccountPaymentServiceProviders | The PersonalAccountRoles values will only be retrieved if the authenticated user is a PTC or an STC for that organization. Retrieves only the ASPSPs that the PTC or STC is associated with. |
ASPSPReadAll | The PersonalAccountRoles values will only be retrieved if the authenticated user is a PTC or an STC for that organization. Retrieves all ASPSPs. | ||||
OBThirdPartyProviders | GET | GET /scim/v2/OBThirdPartyProviders | TPPReadAccess | OBThirdPartyProviders | The PersonalAccountRoles values will only be retrieved if the authenticated user is a PTC or an STC for that organization. Retrieves only the TPPs that the PTC or STC is associated with. |
OBAuthorities | GET | GET /scim/v2/OBThirdPartyProviders | AuthoritiesReadAccess | OBThirdPartyProviders | Retrieves all OBAuthorities. |
OBQualifiedTrustServiceProviders | GET | GET /scim/v2/OBQualifiedTrustServiceProviders | QTSPReadAccess | OBQualifiedTrustServiceProviders | None |
Appendix A - SCIM resources Swagger specification
The SCIM Swagger Specification provides a Swagger specification for the endpoints above and can be accessed via the GitHub link below:
Github link macro link https://github.com/OpenBankingUK/directory-api-specs
Appendix B - ASPSPs Only
Validate Access Token - Use of Open Banking as an Identity Provider
ASPSPs have the option of using Open Banking as an OIDC Provider (OP).
...
OB Directory will not support fine grained roles and permissions, all users will be identified only as TPP-PTCs.
Registration
ASPSPs that require the use of this feature should raise a service request through the service desk.
...
- One or more redirect URIs
- The client authentication method that they intend to use.
OIDC Profile Claims
Once a user authenticates using the Open Banking Directory as an identity provider, the id_token that is issued will consist of the following claims.
...
The claims can also be accessed through the UserInfo end-point provided by OB (which can be discovered through the Directory's .well-known configuration).
Appendix C - Certificate Profiles
Document | Description | ||||||
---|---|---|---|---|---|---|---|
OpenSSL eIDAS PSD2 Certificate Signing Request Profiles v2.3 |
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. |
...