Successful Third Party Onboarding for Open Banking UK
By Sachini Siriwardene
- 4 Jun, 2019
The second Payment Service Directive (PSD2) requires banks to provide access to customer data through open APIs. Security is a crucial factor when exposing confidential customer data in this manner. Before allowing third-party providers (TPPs) access to consumer financial data, the bank must make sure that the data does not fall into the wrong hands. To make sure the applications accessing the data are secure, the application needs to be first registered with the bank.
The UK open banking specification is based on the OAuth2 framework with necessary enhancements to ensure safe consumption of data. To cater to this security requirement, the Open Banking UK specification has adopted the OpenID Connect Dynamic Client Registration specification with some modifications. The specification mentions Dynamic Client Registration (DCR) and “Manual Client Registration” as the two main methods which can be used for a TPP to register with a bank by integrating with the directory service.
This article explains the two approaches for registering applications as mentioned in the Open Banking UK specification.
Open Banking Directory
The Open Banking Directory acts as a trust anchor, guaranteeing the authenticity of the banks as well as the application providers. Both account service providers and TPPs can register with the directory and registrants have to go through a process of verifying their identity. The directory issues digital certificates for the purposes of message signing and transport level security (TLS). TPPs can obtain a Software Statement Assertion (SSA) from the directory in order to register with a bank using either DCR or Manual Client Registration. This is a signed JSON web token, which contains details about the TPP as well as the application. The third party application providers can discover the account service providers via the directory where the details of the banks registered and their available API endpoints are advertised.
Dynamic Client Registration
Figure 1: DCR
DCR is used by TPPs (Account Information Service Provider [AISP], Payment Initiation Service Provider [PISP], Card-Based Payment Instrument Issuer [CBPII]) to register with a bank and gain access to the relevant APIs to retrieve details needed for the application functions. It provides a standard API which can be used by TPPs to register an application and obtain a client ID and secret, which can be used to obtain tokens that need to be used when calling the Open Banking APIs. WSO2 Open Banking supports DCR and allows TPPs to register using the API endpoint.
In this flow, the registration happens through an API call. No prior token is expected to call this API but the communication should take place through a secured channel protected by mutual TLS.
Calling the DCR endpoint
- Prior to calling the DCR endpoint, the TPP has to register with the Open Banking Directory. After successful registration, the TPP will be able to obtain a signing and transport certificate from the directory.
- A software statement assertion will be generated for the particular TPP application and the TPP can download this assertion.
- The TPP can now call the DCR endpoint of a bank which they wish to register with. The communication should take place with mutual TLS and the TPP must use the transport certificate issued by the directory to perform mutual TLS.
- After successful validation of the request, the TPP will receive a client ID and secret, which they can use to obtain tokens and access bank APIs.
In this flow, the registration endpoint can be invoked without any prior authentication mechanism. This means that when invoking the API, the user does not need to have a token to verify their identity. The request sent to the endpoint is an encoded JSON Web Token (JWT), which is signed by the signing certificate obtained from the Open Banking Directory. The payload also contains the encoded and signed SSA as well.
Validating the request
After the request is received at the DCR API, it is validated to ensure the authenticity of the request. The request, which is in the form of an encoded JWT, must be decoded and the signature of the request must be verified. The signature verification is done by retrieving the public key used to sign the request from the JSON Web Key Set (JWKS) endpoint which is included in the SSA sent in the request.
A JWKS denotes a data structure that represents a cryptographic key. When a TPP registers in the Open Banking Directory, a JWKS endpoint is generated for each software statement, which contains the public certificate issued for signing and transport purposes.
The signature of the SSA is also verified in the same manner using the JWKS endpoint of the directory, which contains the public certificates. The following validations are done to the transport certificate sent with the request:
- Must ensure that the subject distinguishedName (DN) contains values for DN and organisationUnit (OU) claims
- The commonName (CN) attribute of the certificate must match the “software_id” specified within the SSA and the OU attribute of the certificate must match the “org_id” specified within the SSA.
- The client TLS certificate should chain to a certificate located in the SSA 'org_jwks_endpoint' attribute.
The claims sent in the request are validated to check whether the claims are allowed to be requested. Figure 2 shows the validations done for the incoming payload.
Figure 2: Validations for the request
If the request passes all validations, a response is returned which includes the client ID and secret of the created application and the claims which were sent in the request. In the event of not being able to satisfy a validation, an error response is sent back.
The high-level implementation can be summarized in the following diagram:
Figure 3: DCR validation sequence
Manual Client Registration
The second option given in the specification is the manual client registration, which involves the TPP registering at the Account Servicing Payment Service Provider (ASPSP) through their developer portal. In order for the bank to enable manual client registration, they must first obtain a client ID and secret for registering a service provider to enable federated authentication using the open banking directory as the identity provider (IDP). Also, the bank must provide a redirect URL where the TPP should be redirected to after logging in successfully.
Figure 4: Manual Client Registration Process
Logging into the portal
The following are the main steps followed in the manual registration process:
- The TPP logs into the Open Banking Directory.
- The TPP obtains an SSA.
- The TPP attempts to log into the bank’s developer portal.
- The TPP is redirected to the Open Banking Directory login page and logs in using their directory credentials, which they receive upon registering. The TPP is prompted to authenticate using a second factor (PING ID application).
- After a successful login attempt, the TPP is redirected back to the developer portal.
- The TPP can upload the SSA and if validation succeeds, the client ID and secret will be generated.
In this scenario, the Open Banking Directory is used as a federated IdP. The single sign-on (SSO) functionality is implemented using the OpenID flow. In this flow, a service provider must be registered with Open Banking Directory and the credentials for that service provider must be obtained by the bank as mentioned above. The login process involves an authorization code grant type. After being redirected to the particular URL that the ASPSP has registered with the Open Banking Directory, the authorization code can be obtained. Next, the ASPSP should initiate a request to obtain a token by exchanging the authorization code.
In order for the bank to verify that the logged in user is a valid TPP with the necessary roles (AISP, PISP, CBPII) assigned to and verified by the Open Banking Directory, the value of the “tpp_associated” claim in the token returned by the directory must be set to true. If not, the TPP will not be allowed to log into the developer portal of the ASPSP.
After successfully logging in, the SSA should be provided by the TPP. The signature and claims passed in the SSA are then validated. If the validation is successful, an application will be created and keys will be generated for the application. Depending on the “software_envrionment” attribute available in the SSA, a client ID and secret will be generated for the relevant environment, either production or sandbox.
WSO2 Open Banking also supports the on-boarding of TPPs using MCR, where the SSO functionality of WSO2 Identity Server is utilized to support this feature. The TPP can log into the WSO2 API Manager store where they will be redirected to the Open Banking Directory login. They can then use the credentials used to register with directory and log into the store. Upon successful login, the TPP will be redirected back to WSO2 API Manager’s store where they can provide the SSA, create an application in the store, and generate a client ID and secret.
In this article, we have discussed Dynamic Client Registration and how WSO2 Open Banking supports the approaches recommended by the Open Banking Directory to onboard TPPs. As mentioned in the Open Banking UK specification, there are two approaches to this; applications can register by calling an API or by logging into the bank’s developer portal using the Open Banking Directory as a federated IdP and an SSA issued by the directory to register an application and generate a client ID and secret. WSO2 Open Banking also includes the capabilities for consent management related to UK Open Banking Specification as well as fraud detection functionality as mentioned in PSD2.
- Sachini Siriwardene
- Software Engineer