Javascript is actually
a good thing!
Make sure it's turned on
so that pingidentity.com can work properly.
Open Banking TPP Client Authentication with Ping Identity

Open Banking TPP Client Authentication with Ping Identity
Back
May 25, 2018
Federico Carbone
Regional Solution Architect

The Open Banking Security Profile defines how Third Party Provider (TPP) applications shall obtain and use OAuth and OpenID Connect tokens in a secure way, suitable for financial transactions. TPP applications will need to obtain tokens from account servicing payment service providers (ASPSPs) to initiate and complete transactions once a user has provided consent and authorized the ASPSP.

 

As part of the process of obtaining tokens, the security profile defines what authentication methods ASPSPs must support and make available to TPPs to authenticate. The following is required by the security profile:

 

  1. ASPSPs must secure the token endpoint, used by TPPs to obtain tokens, using mutually authenticated TLS.
  2. ASPSPs must make available one of the following methods at the token endpoint:

 

Of the three methods available, MTLS and Private Key JWT are recommended by Open Banking. In this blog post I will explain how to implement Private Key JWT using the Ping Identity software stack. You can also view my previous blogs on how to enable Open Banking dynamic client registration with Ping Identity and how to use the client registration tool.

 

Private Key JWT authentication

Private Key JWT authentication is defined by the “JSON Web Token (JWT) Profile for OAuth 2.0 Client Authentication and Authorization Grants” specification and defines a method for a TPP client application to authenticate at an ASPSP sending a JWT token.

 

In order to be able to authenticate at an ASPSP and request tokens, a TPP must have completed the following steps, explained in the blog about Dynamic Client Registration:

 

  1. A TPP Primary Technical Contact (PTC) must have registered a TPP and a software statement with the Open Banking directory. With this registration step, a TPP will have a signing key that can be used to sign the authentication JWT and a network certificate used to establish the MTLS channel with the ASPSP token endpoint.
  2. A TTP Primary Technical Contact (PTC) must have registered an OAuth client at the ASPSP (either via a manual or automated process).

 

Once a TPP has completed the above initial registration steps, it can obtain tokens from the ASPSP with the following steps:

 

  1. Establish an MTLS channel with the Token Endpoint exposed by the ASPSP, using the network certificate provided by the Open Banking Directory.
  2. Generate a JWT, signed with the signing key bound to the software statement obtained from the Open Banking Directory. The JWT must include the following claims:
    • "iss”. Issuer. This must contain the client_id of the OAuth client that was issued by the ASPSP to the TPP during client registration.
    • “sub”. Subject. This must contain the client_id of the OAuth client.
    • “aud”. Audience. This identifies the ASPSP and it must be set by the client to the URL of the ASPSP Token Endpoint.
    • “jti”. JWT ID. A unique identifier for the token defined by the TPP client application, that can be used to prevent reuse of the token.
    • “exp”. Expiration time of the token, defined by the TPP client.
  3. Send the authentication JWT to the token endpoint exposed by the ASPSP.  


The following example shows a private key JWT authentication request for an OAuth client credentials grant type (non URL encoded and abbreviated for clarity):


The decoded JWT is displayed below:


Test Environment

To demonstrate how private key JWT client authentication 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 and an Account Information Service Provider (AISP) and where I have an account as a PTC.

 

Logical Architecture
 The following diagram shows how PingFederate, PingAccess and PingDirectory are deployed and connected in the test environment.


  • PingFederate works as the OAuth authorization server and publishes the token endpoint. PingFederate will connect to the Open Banking directory to download the keys used to validate the authentication JWT sent by the client.
  • PingAccess exposes the PingFederate token endpoint enforcing MTLS.
  • PingDirectory stores the OAuth client data.

 

PingFederate OAuth configurations

To test client authentication, I start from an environment where PingFederate has already been deployed, enabled for OAuth and where an OAuth client has been created using the registration tool described in the previous blog. PingAccess has also been deployed and configured to protect the PingFederate token endpoint via Mutual TLS (MTLS).

The screenshot below displays the relevant part of the OAuth client configuration that enables private key JWT authentication. This is accessible from the PingFederate administrative UI via the “OAuth Server” menu, selecting the client created with the client registration tool.


The CLIENT AUTHENTICATION field is set to PRIVATE KEY JWT (optionally, replay prevention can be enabled to avoid that a client can reuse the same token to authenticate twice) and the JWKS URL is set to the address of the JWKS associated to the TPP client in the Open Banking directory. This value is derived from the software statement that was submitted as part of the registration request.

When PingFederate receives a private key JWT for client authentication, it validates the token according to the specification; as part of the validation it checks that the “aud” claim of the JWT matches the PingFederate token endpoint, using the PingFederate base URL. In this case, the token endpoint is published via PingAccess using a URL that differs from the PingFederate base URL (because the token endpoint must be protected via MTLS). I need therefore to modify the default configuration to set the correct token endpoint URL in PingFederate to make the “aud” check pass. The configuration is available in the PingFederate management UI in the “OAuth Server” - “Authorization Server Settings” - “TOKEN ENDPOINT BASE URL” field. This field must be set with the base URL used in PingAccess to expose the token endpoint.


Client authentication tool

To send the authentication requests, I will use a Java tool that generates an authentication JWT and submits a token request to the token endpoint of the ASPSP, using the OAuth client credential grant.

 

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 ASPSP token endpoint. I implemented the actual call with Unirest for convenience.


Tool Usage

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

 

  1. Ensure that a client has been registered at the ASPSP, as explained in the client registration tool 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.
    • aspsp.audience the audience expected from the ASPSP. In our case, this is the URL of token endpoint used to submit the token request.
    • aspsp.tppClientID the client ID issued by the ASPSP during client registration.
    • aspsp.networkCertPassword the password used to protect the p12 network certificate.
    • aspsp.tokenEndpoint the token endpoint of the ASPSP.
  4. 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.
  5. Run the following command from the root of the project:
    • mvn compile exec:java -Dexec.mainClass="com.pingidentity.openbanking.ClientAuthenticationTool

This is the expected output:

 

Private key JWT eyJraWQiOiJ2TmF1aDEt<Abbreviated>sgTHUN5Q

ASPSP Token endpoint response code 200, body "access_token":"dYFT6Uihl2BHSuJTbiE25C99bZ0x","token_type":"Bearer","expires_in":7200}

Access token dYFT6Uihl2BHSuJTbiE25C99bZ0x

 

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

 

 

Related Posts
Categories