How to Use the Client Registration Tool for Open Banking with Ping Identity

In my previous blog, I explained how Ping Identity enables Account Servicing Payment Service Providers (ASPSPs) to implement the Open Banking Dynamic Client Registration Specification. In this post, you will get the details of the Java tool that third-party providers (TPPs) can use to issue and send the registration requests to ASPSPs.

 

Tool Description

The tool is a command line application that does the following:

 

1. Authenticates against the Open Banking Directory to obtain an OAuth Access Token.
2. Calls the Open Banking software statement API to obtain a new software statement (with the token just obtained).
3. Generates a client registration request JWT that embeds the software statement.
4. Submits the request JWT to the ASPSP.

 

Open Banking Directory Authentication

In order to call any of the APIs exposed by the Open Banking Directory, a TPP client must first authenticate and obtain an OAuth token with scopes ASPSPReadAccess TPPReadAccess AuthoritiesReadAccess. The authentication method supported by the Open Banking Authorisation Server is private_key_jwt (as defined by the OIDC specification); therefore TTP clients must first generate a signed JWT using the signing key previously obtained from the Open Banking Directory frontend, and submit the JWT to the Open Banking token endpoint. The following is an example call to the Open Banking MIT environment authorisation endpoint (parameters not URL encoded for clarity).

 

 

The authentication JWT must contain: 

• Issuer (iss) and subject (sub) claims: both set to the value of the software statement ID previously generated on the directory frontend;
• Audience (aud) claim: set to the URL of the Open Banking token endpoint;
• Expiration (exp) timestamp claim.

 

The key ID claim (kid) must match the key ID generated by the Open Banking Directory frontend for the signing key. This is an example decoded JWT that can be used for authentication.

 

 

The tool uses the Jose4j library to generate the JWT with the code below.

 

 

Once the private key JWT is available, the tool sends the token request to the Open Banking MIT Directory token endpoint. I implemented the actual call with Unirest for convenience.

 

 

Software Statement Download

Once the Open Banking Directory access token is available, the tool can make API calls to download the software statement sending an HTTP get request to the SSA API. For the MIT environment, the TLS endpoint for TPPs is:

 

https://ssaapi.mit.openbanking.qa/api/v1rc2/tpp/<org_id>/ssa/<software_client id>

 

where <org_id> is the ID of the TPP organisation and <software_client id> is the ID of the software statement both obtained from the Open Banking Directory frontend.

 

 

Request JWT Generation and Submission

Once the software statement is available, the request JWT for the client registration can be generated. The request includes the following claims:

 

• Issuer: set to the ID of the software statement obtained from the Open Banking Directory frontend.
• Audience: an ID that identifies the ASPSP. In my case, this must match the configured audience parameter in the PingFederate Client Registration Policy.
• Software statement: the software statement obtained from Open Banking.
• Client specific parameters like redirect URI, supported grant types, supported authentication method etc. The current version of the tool creates clients with a single redirect URL and response type set to code id_token. The code can be easily modified to support different grant types and response types.
• Timestamps and JWT id.

 

The code below is used to generate the request JWT.

 

 

Finally, the request can be sent over an MTLS channel to the ASPSP registration endpoint with the code below.

 

 

Tool Usage

The tool is available as a Maven project on the Ping Identity GitHub page. To run the tool:

1. Ensure that a software statement has been created using the Open Banking Directory frontend and that a signing key and network certificate are associated to the software statement (as explained in my previous blog).
2. Download and unzip the source code from GitHub or clone the source.
3. Change the following parameters in the src/main/resources/configuration.properties file:
   • ob.signingKeyId the signing key ID obtained from the Open Banking Directory frontend.
   • ob.softwareStatementId the software statement ID obtained from the Open Banking Directory frontend.
   • ob.organization the organisation ID obtained from the Open Banking Directory frontend.
   • aspsp.redirectUri the redirect URI of the TPP app; this must match the redirect URI configured in the Open Banking Directory.
   • aspsp.audience the audience expected from the ASPSP.
   • aspsp.registrationEndpoint the registration endpoint of the ASPSP.
   • aspsp.networkCertPassword the password used to protect the p12 network certificate.
4. The remaining parameters can be left unmodified for the MIT environment.
5. Replace the signing key and the network certificates with yours:
   • Signing key: replace the file 
   • src/main/resources/dynamic_client_reg_signing.key with your signing private key.
   • Network certificate: replace the file src/main/resources/dynamic_client_reg_network.p12 with your TPP certificate.
6. Run the following command from the root of the project: 
   • mvn compile exec:java -Dexec.mainClass="com.pingidentity.openbanking.ClientRegistrationTool"

 

This is the expected output:

 

Private key JWT eyJraWQiOiJ2TmF1aDEt…<Abbreviated>…6GmCyy8fc8gWllqx8w

OB Token endpoint response code 200, body

{"access_token":"eyJhbGciO…<Abbreviated>…2rC0jwRcXnQ","token_type":"Bearer", "expires_in" :7199} Access token eyJhbGciOiJS…<Abbreviated>…2rC0jwRcXnQ

SSA endpoint: https://ssaapi.mit.openbanking.qa/api/v1rc2/tpp/irW…<Omitted>…kM/ssa/5cr…<Omitted>…mvpJ

OB SSA endpoint response code 200, body eyJhbGciOi…<Abbreviated>…W9W4svCHEsg Request JWT generated: eyJraWQiOi…<Abbreviated>…FvueetxVzukcQ

Client registration response 201, body {"jwt_replay_prevention":true,…<Abbreviated>… "response_types":["code"]} ;

 

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