Version Control

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.

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:

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

Mapping of Scopes to External Actors

End-points

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.

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