Version Control

Version	Date	Author	Comments
DRAFT 1	18 Dec 2018	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	03 Apr 2019	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	23 Apr 2019	Open Banking Directory Team	Update to Appendix A - SCIM resources Swagger specification, replacing the linked text with a GitHub link:
v1.3	03 Sep 2019	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	17 Sep 2020	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	21 Dec 2020	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	06 Jun 2023	Open Banking Directory Team	Updated links to version 2.3 of usage guidelines.
1.7	16 Aug 2024	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.

The Open Banking Directory will provide the necessary functional capabilities required for Third Party Providers (TPPs) that successfully enrolled with Open Banking to identify and onboard with ASPSPs so that they can use the APIs provided by the ASPSPs. . ASPSPs can utilise technical information contained within the Directory to validate organisation and software identity (active/inactive), QTSP validity and member state NCA register status (including passport information).

The functional capabilities can be broken up broadly into three capability groups:

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

ASPSP only

TPP and ASPSP

Entity Class Model and Visibility

Entity Class Model

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:

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.

The FAPI Read Write Specification specifies the algorithms that should be used for TLS (Section 8.5) and for digital signatures (Section 8.6).

Section 8.5 states that only the following ciphers should be supported for TLS:

TLS_DHE_RSA_WITH_AES_128_GCM_SHA256
TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256
TLS_DHE_RSA_WITH_AES_256_GCM_SHA384
TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384

For avoidance of doubt, this only applies to the TLS connection between the ASPSP and the TPP and Participants and OB. TPPs and ASPSPs must establish their own standards for TLS connections with PSUs through apps, browsers and other PSU devices.

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:

The FAPI Read Write Specification: http://openid.net/specs/openid-financial-api-part-2.html

RFC 6960 - OCSP: https://tools.ietf.org/html/rfc6960

RFC 6818 - CRL: https://tools.ietf.org/html/rfc6818

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:

Distinguished Name and all attributes contained within are correct for the given software statement.
The keys used are of appropriate length and support the required algorithms

The Directory will store the issued public certificates in PEM format as well as returning them via both the API and DFI.

Should a Primary Technical Contact wish to roll or replace certificates used this will be a simple matter of associating another certificate with an existing software statement.

More than one certificate for a given software statement for both signing and encryption purposes can be active at any time.

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:

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:

Are immutable with the exception of the certificates, signing and encryption keys and corresponding (KeyID fields), Active status flags and redirect_uri's that are append only.

Should a software statement be revoked then:

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.

OB will host these CRL endpoints on public Content Delivery Networks. These CRLs will be served over HTTPS and HTTP.

HTTP clients MUST support SNI (Server Name Indication) in order to access the https resources.

A new CRL will be generated when a certificate is revoked and made available on the CDN as close to real time as possible.

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:

A key store for each organisation containing their active certificates, signing and encryption keys
A key store for each organisation containing their inactive certificates, signing and encryption keys
A key store for each software statement containing its active certificates, signing and encryption keys
A key store for each software statement containing its inactive certificates, signing and encryption keys

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.

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

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.

However, instead of an organisation id, the parameter value should be "OpenBanking".

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.

Alternatively, an SSA for a given software statement can be accessed from the SSA API end-point.

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.

To access this endpoint the requesting party must have an access token.

A Software Statement Assertion can only be generated if the Software Statement and its owning TPP are active. If either of the two are marked as inactive, an error will be returned.

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.

As an example, the following SCIM query retrieves a TPP if the following conditions are met

The TPP has a software statement with the given id
The Software Statement has the Active flag set to true
The TPP has a Competent Authority Claim valid for the member-state GBR
The TPP has a role of PISP
The TPP authorisation is still Active

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.

The APIs are implemented as a set of SCIM resources.

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.
OBAccountPaymentServiceProviders	GET	GET /scim/v2/OBAccountPaymentServiceProviders	ASPSPReadAll	OBAccountPaymentServiceProviders	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:

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

The endpoints for the Open Banking OIDC provider APIs can be identified using the authorization_endpoint, token_endpoint and registration_endpoint fields from the Directory's .well-known configuration.

The OB identity provider should be used to bootstrap a TPP's Primary Technical Contact onto the ASPSP API Gateway.

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.

The ASPSPs must specify:

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.

Claim	Type	Example value	Description
sub	string	xccsdlkj128789432	Unique Identifier for the Authenticated User
username	string	xccsdlkj128789432	The credential used by the user while logging in. This could be their email address or sales-force id.
email	string	jo.bloggs@openbanking.org.uk
phone_number	string	+44 5173 130 443	A contact phone number (mobile) for the user also used as a second means for a authentication during password resets
tpp_associations_list	string array	[ "0020E000008jgBfQFX", "0020E000008jgB6&8X" ]	A list of the TPP org_id's that this user is associated with in either a PTC or STC capacity.
family_name	string	Bloggs	Surname or Family name
given_name	string	Jo	First name
name	string	Jo Bloggs	Requested name string.
tpp_associated	boolean
account_verified	boolean
aspsp_association_list	string array
aspsp_associated	boolean

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.

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.