Key Providers Overview

Whenever TPP initiates a DCR request, the payload is signed with the TPP’s private key and same needs to be verified with the TPP’s public key at the Bank’s side. There could be different ways to get the TPP’s public key which can vary as per open banking directory services and the geographical regions.

To accommodate those varying approaches of getting the public key, OBDX has provided factory pattern to get a ‘Key Provider’. The main job of the key provider is to get the public key of the TPP, to verify the DCR payload, based on the Software Statement Issuer Name.

To implement the above, one IKeyProvider interface is added. This contains the methods which may differ based on the parameters mentioned above.

There are 4 methods to be implemented.

1. public Map<String, String> fetchPublicKey(String dcr_request_token); - to fetch the TPP’s public key when the TPP is being onboarded with the bank with the help of DRC Request Token data.
2. public String getPublicKey(String clientId, String kid); - to fetch the TPP’s public key based on the client id and the key id for further requests processing as and when required when the TPP is already onboarded with the bank.
3. public Map<String, String> getPublicKeyClaims(String x509Certificate, String keyId); - to get the various types of claims like certificate type, validity, expiry, revocation etc.
4. public RSAPublicKey getRSAPublicKey(String encodedKeyOrCert); - to get the decrypted RSA public key from the encoded key or extracted from the certificate.

In addition to above methods, to make the key provider class singleton, provider class must implement to return the singleton instance of the class

publicstatic IKeyProvider getInstance();

Key Provider Implementation & Configuration

To create a key provider, one needs to create a KeyProvider class by extending the com.ofss.digx.oauth2.spi.IKeyProvider interface and making the provider class entry in the DIGX_FW_CONFIG_ALL_B table.

For example, we have a SSA Issuer called ‘XYZ Ltd’.

We will need to follow below two steps to configure the XYZ key provider

1. Need to create a new key provider implementation class - com.ofss.digx.openid.service.XYZKeyProvider which must implement the IKeyProvider interface. Name and the package of the key provider class could be anything, those are not compelled to be same as the mentioned above, but it must implement the IKeyProvider interface.
2. Need to make the provider class entry in the DIGX_FW_CONFIG_ALL_B with prop_id = ‘XYZ Ltd_KEY_PROVIDER’. In this entry, the naming convention should strictly be followed as <SSA_Issuer>_KEY_PROVIDE and the CATEGORY_ID must be ‘openBankingConfig’.

   To configure new key provider in DB, refer below insert query and its values are described as below:

   Insert into DIGX_FW_CONFIG_ALL_B
           (PROP_ID,CATEGORY_ID,PROP_VALUE,FACTORY_SHIPPED_FLAG,PROP_COMMENTS,SUMMARY_TEXT,CREATED_BY,CREATION_DATE,LAST_UPDATED_BY,LAST_UPDATED_DATE,OBJECT_STATUS,OBJECT_VERSION_NUMBER,EDITABLE,CATEGORY_DESCRIPTION)
           values ('XYZ
           Ltd_KEY_PROVIDER','openBankingConfig','com.ofss.digx.openid.service.XYZKeyProvider','N',null,'XYZ
           Ltd Key Provider
           Class','ofssuser',sysdate,'ofssuser',sysdate,'A',1,'N',null);

As per the current standards, there are mainly two open banking authorities in European Continent:

1. Open Banking Directory (OBD)
2. European Banking Authority (EBA)

A Third-Party Provider (TPP) gets registered with any of the above two authorities and obtains the Software Statement (SSA) before getting onboarded with the bank.

In this release, OBDX has provided the out of the box implementation of key providers for both directory services.

1. com.ofss.digx.openid.service.OBDKeyProvider – for Open Banking Directory
2. com.ofss.digx.openid.service.EBAKeyProvider – for European Banking Authority

To get the public key, OBD has provided ‘software_jwks_endpoint’. This endpoint provides a JSON Web Key Set (JWKS), which is a set of keys containing the public keys used to verify any JSON Web Token (JWT). Based on the key id, TTP’s public key is extracted from the JWKS to verify the payload.

Both the key providers currently communicate with the Open Banking Directory to fetch the TTP’s public key currently as per the implementation.

We have below two configurations:

1. OpenBanking Ltd_KEY_PROVIDER – to fetch the public keys of TPP’s whose SSA Issuer is the ‘OpenBanking Ltd’.
2. DEFAULT_KEY_PROVIDER - to fetch the public keys of TPP’s whose SSA Issuer is NOT the ‘OpenBanking Ltd’.

   Besides above two configured providers, we have a mock key provider (for which, no configuration is needed in the DB):

3. MOCK_KEY_PROVIDER- "com.ofss.digx.oauth2.service.DBBasedKeyProvider" – this is only a dummy DB based key provider. If none of the above two providers are configured in the DB, KeyProviderFactory would return the mock key provider. It stores only single public-private key pair in the DB itself and uses the same pair for all the TPP payload verifications.

   Below is a sample code snippet to get the key provider for reference:

   
   
   
   Description of the illustration ukopen2.png