How to Enable Open Banking Dynamic Client Registration with Ping Identity

March 27, 2018

Federico Carbone
Regional Solution Architect

Financial institutions face a wide range of technical challenges of securing access to Open Banking APIs under UK Open Banking. In the coming weeks, I will be covering how Ping Identity can address these challenges. In this first blog, I focus on how Ping Identity enables Account Servicing Payment Service Providers (ASPSPs) to comply with the Open Banking UK Dynamic Client Registration specification. Specifically, you’ll learn:

How the Open Banking Dynamic Client Registration process works.
The PingFederate configurations needed to enable Dynamic Client Registration.
How third-party providers (TPPs) can obtain software statements from Open Banking and issue registration requests to PingFederate for client registration.

Introduction

OAuth 2.0 is the reference framework for API security in Open Banking, which means that third-party providers (TPPs) will need to obtain credentials with ASPSPs to enable access to the ASPSP Open Banking APIs.

The Open Banking OpenID Dynamic Client Registration Specification defines two methods by which a Primary Technical Contact for a TPP may register an OAuth client with an ASPSP: manual and automatic.

Automatic Registration Process

The automated mechanism is based upon the OAuth 2.0 Dynamic Client Registration Protocol [RFC7591] and adds some Open Banking-specific constraints around the content of the request and mutual TLS (MTLS) between TPPs and ASPSPs.

The process that a TPP (already registered at the Open Banking directory) must follow to register a new client is depicted and described below:

A Primary Technical Contact (PTC) accesses the Open Banking Directory Front End Interface, registers the new software and generates and uploads the Certificate Signing Requests (CSRs).
- For the network certificate, that will be used to establish MTLS channels with the ASPSPs.
- And for the signing certificate, that will be used for signing the JSON Web Tokens (JWTs) generated by the TPP.
The PTC obtains a software statement (a JWT, signed by Open Banking which describes the TPP software) and the certificates.
The PTC triggers the automatic registration request to the ASPSP.
The TPP application creates a registration request that includes the software statement and submits the request to the ASPSP. Unlike RFC7591, the registration request:
- is a JWT signed by the TPP. The private key used to sign the JWT has a corresponding public key published by the Open Banking Directory and referenced in the software statement.
- must be sent over MTLS, with the client presenting the network certificate obtained from Open Banking.
The ASPSP validates the request and upon successful validation, the ASPSP creates the OAuth client and returns the client credentials to the TPP.

From this moment, the TPP can use those credentials to call the Open Banking APIs exposed by the ASPSP.

The following diagram shows the relationships between the request JWT and the software statement JWT.

When an ASPSP receives the registration request, in order to validate the signatures of the JWTs, it will need to do the following:

Decode the request JWT, without validating the signature.
Extract the software statement from the decoded request JWT.
Validate the software statement JWT with the Open Banking Ltd. JSON Web Key Set (JWKS) endpoint.
Extract the software JWKS endpoint from the software statement.
Validate the request JWT using the JWKS endpoint extracted.

Test Environment

To demonstrate how client registration works, I will use a Ping Identity test environment connected to the Open Banking Multi-Party Industry Testing (MIT) Directory, where I have previously registered an ASPSP (AnyBank) and an AISP (Ping Bank TPP - AISP) and where I have an account as a PTC.

Logical Architecture
ASPSPs can rely on PingFederate, PingAccess and PingDirectory to comply with the Open Banking specification and specifically with Dynamic Client Registration. The following diagram shows how the three components are deployed and connected in the test environment.

PingFederate works as the OAuth authorisation server and exposes the client registration endpoint. Out of the box, PingFederate exposes an [RFC7591] compliant registration endpoint; since the Open Banking Dynamic Client Registration process deviates significantly from [RFC7591], a PingFederate extension—a “Client Registration Policy”—is needed. The Registration Policy is triggered when a client registration request is received by PingFederate and implements the specific validation steps of the Open Banking specification. Ping Identity will publish the extension on the Ping Identity GitHub page, and I will discuss the code in my next blog.
PingAccess exposes the PingFederate registration endpoint and enforces MTLS.
PingDirectory stores the OAuth client data. The schema of the directory is extended to create the necessary object classes, and PingFederate points to the PingDirectory to store the OAuth client data. Storing client data in a directory or in a relational database is a prerequisite to enable dynamic client registration.

Client Registration Policy Configuration

For the configuration of the Client Registration Policy, I start from an environment where PingFederate has already been deployed, enabled for OAuth and connected to PingDirectory to store OAuth Client data. PingAccess has also been deployed and configured to protect the PingFederate registration endpoint via Mutual TLS (MTLS).

Once the plugin has been compiled and deployed, a new Client Registration Policy type becomes available to administrators.

From the “OAuth Server” menu in the “Client Registration Policies” section, select “Create new Instance.”

Input a name and description for the policy and select the type “Open Banking Software Assertion Validator.”

The new instance can now be configured and the following must be set:

Issuer: This is the value of the “iss” claim expected in the received software statement JWT. It is set by Open Banking in the software statement and has the value “Open Banking Ltd.”
JWKS URL: The URL of the JWKS endpoint that must be used to validate the signature of the software statement. For the OB MIT environment the JWKS endpoint is https://keystore.mit.openbanking.qa/keystore/openbanking.jwks
The supported algorithms: The plugin supports ES and PS to be compliant with specification. RSA has been added for convenience and because in the MIT environment the issued software statements are signed with RS256. For the test, I enable RSA-PSS and RSA.

Note: PingFederate supports RSA-PSS out of the box only when connected to an HSM. As I do not have an HSM available in the test environment I enabled RSA-PSS support adding the Bouncy Castle JCE provider to the environment.

Once the policy is configured, Dynamic Client Registration must be enabled via the “OAuth Server” - “Client Settings” - “Dynamic Client Registration” menu:

Finally the policy can be enabled in the “OAuth Server” - “Client Settings” - “Client Registration Policies” menu:

PingFederate is now ready to receive registration requests from TPPs at the /as/clients.oauth2 endpoint.

Client Metadata Configuration

Software statements include several claims that describe the TPP client application and the TPP organisations. In PingFederate, these can be attached to the OAuth client definition and stored as OAuth client metadata. The registration policy ensures that the attributes received in the software statement are stored with the OAuth client.

Metadata attributes can be configured in the “OAuth Server” - “Client Settings” - “Extended Client Metadata.”

In this example, I have configured a subset of the attributes of the software statement related to the organisation and to the software.

Software Statement Download

With the Ping Identity environment configured, I can now obtain a software statement and generate a registration request.

To obtain a software statement, a TPP must be registered at the Open Banking Directory and a TPP technical contact must be able to access the Directory Front End Interface in order to register the application and receive the software statement. (The OB directory also enables TPPs to request software statements via APIs and I will cover the API approach in another blog post.)

Let’s see how a technical contact can register a new TPP application. The following screenshots are taken from the Open Banking test environment (the MIT environment) where I have the “Ping Bank TPP - AISP” TPP registered.

Search for the TPP on the “Search directory participants screen” and copy the Organisation ID that will be needed later to generate the CSRs for that TPP.

In the TPP page, locate the “Software Statements” section (at the bottom of the page) and select “Add new statement.”

A form that allows me to input the new software data is displayed; input the TPP application data and submit. This data will be included in the Software Statement that Open Banking generates for this client. Pay particular attention to the Redirect URI value to ensure this is correct.

The new software statement is created and the UI shows the details: A software statement ID is generated and a new client ID is generated and assigned to the software statement. At the moment, no certificates are assigned to the statement.

I can start generating the software statement and upload the necessary CSR files later by selecting the “Generate” button. The directory provides the encoded JWT and the decoded JWT. From the decoded JWT I can see that the statement was issued by Open Banking Ltd; I can identify the key ID of the key that was used to sign the software statement and I can see the software_jwks_endpoint claim that points to JWKS that must be used to validate the request JWT.

The statement cannot be used yet, as the certificates have not been attached to it. The final step is to bind a network certificate (used to establish MTLS connections between the TPP and the ASPSP) and a signing certificate (used by the TPP to sign the various tokens sent to the ASPSP). To do that I need to generate private / public key pairs and the signing requests to be uploaded with the OB Directory Front End Interface.

I am going to use OpenSSL for the generation of the keys and CSRs. The only aspect to notice here is that the certificate cn must have the following structure:

To generate the CSRs for the network and signing certificates, I am going to use the following commands:

The commands above will produce two private keys and the CSR files that can be uploaded using the Open Banking UI.

If the upload is successful, Open Banking binds the certificates to the software statement, makes the certificates available for download (in PEM format) and publishes the keys at the correct JWKS endpoints.

The TPP can now download the network certificate for establishing the MTLS channel with the ASPSP and the signing certificate to sign the JWT registration request. I select “Download PEM File” on the network (Transport) certificate and then combine it with the private key to obtain a .p12 file using OpenSSL:

Registration Request and Response

The TPP can now generate a registration request and submit the request to the ASPSP. According to the Open Banking specification, the TPP must POST a PS256 JWT to the ASPSP registration endpoint with application/jwt content type. To sign the request JWT the TPP will use the private key previously generated whose corresponding public key is published by Open Banking.

This is an example request:

Decoded request JWT

On the Ping Identity GitHub page I will provide the sample Java code to generate, sign and submit the registration request and I will explain the code in a future blog.

If successful, the ASPSP will return the following JSON data, which includes the client_id and the client_secret that will be used by the TPP application to authenticate with the ASPSP authorisation server.

If I finally look at the PingFederate OAuth client page, I will see the client just created with the core attributes and the metadata populated according to the request and the software statement.

For more information on how Ping Identity can address the technical challenges of securing access to Open Banking APIs, watch the Dynamic Client Registration demo video or visit www.pingidentity.com/PSD2.