This is available only as a WUM update and is effective from July 2, 2019 (07-02-2019). For more information on updating WSO2 Open Banking, see Updating WSO2 Products.
Before you begin:
Deploy the Dynamic Client Registration v3.2 API.
According to the OBIE, the Account Servicing Payment Service Providers (ASPSPs) need to make sure that the TPPs can be registered in a seamless and ideally, a fully automated process. In order to avoid any obstacles that may occur, the OBIE requires the ASPSPs to provide the TPP responses real-time once the registration is processed. The Dynamic Client Registration (DCR) endpoint is capable of dynamically registering the clients with the ASPSP when the client sends a registration request with its metadata. This results in a registration response that includes a client identifier and the client metadata values registered for the client.
You can find the REST API documentation for Dynamic Client Registration v3.2 here.
This document explains how to utilize Dynamic Client Registration with WSO2 Open Banking.
Before you begin
- Run the DCR related database scripts in the
<WSO2_OB_APIM_HOME>/dbscripts/dynamic-client-registration
directory following Configuring Databases. - Deploy the Dynamic Client Registration v3.2 API.
Configuring dynamic client registration
Follow the steps below to configure DCR API v3.2 in WSO2 Open Banking.
Uploading certificate to the client trust store
The ASPSP can upload the OB root and issuer certificates found in the below mentioned locations to the client trust store of both WSO2 API Manager (WSO2 OB APIM)
and Key Manager (WSO2 OB KM)
.
In sandbox environment, upload certificates from https://openbanking.atlassian.net/wiki/spaces/DZ/pages/252018873/OB+Root+and+Issuing+Certificates+for+Sandbox
In production environment, upload certificates from https://openbanking.atlassian.net/wiki/spaces/DZ/pages/80544075/OB+Root+and+Issuing+Certificates+for+Production
The client trust stores are located in the WSO2 OB APIM and WSO2 OB KM servers in the following locations respectively:
<WSO2_OB_APIM>/repository/resources/security/client-truststore.jks
<WSO2_OB_KM>/repository/resources/security/client-truststore.jks
Use the following commands to add the certificate to the client trust store:
keytool -import -alias tpproot -file <OB_ROOT_CERT> -keystore client-truststore.jks -storepass wso2carbo
keytool -import -alias tppissuer -file <OB_ISSUING_CERT> -keystore client-truststore.jks -storepass wso2carbon
Updating open-banking.xml
Open the <WSO2_OB_APIM_HOME>/repository/conf/finance/open-banking.xml
file.
Add the <UseSoftwareIdAsApplicationName>
property under the <DCR>
tag and set it to true.
Setting this property to true ensures that the SoftwareId
in Software Statement Assertion is used as the application name.
<DCR> <UseSoftwareIdAsApplicationName>true</UseSoftwareIdAsApplicationName> </DCR>
Updating api-manager.xml
To store any properties retrieved from the SSA, add the server-level configuration to the <OB_APIM_HOME>/repository/conf/api-manager.xml
file as explained here . Ideally, place the following ApplicationConfiguration at the end of the file within the APIManager element.
For example, if you want to store software_client_id
retrieved from the SSA created in the sandbox environment, the property name should look like: software_client_id_sandbox
. Similarly, to store the software_client_id
retrieved from the SSA created in a production environment, the property name should be: software_client_id_production
. Make sure you add these properties as false, as required.
In addition to these, include software_jwks_endpoint
in the SSA. This is required to obtain an access token for the application.
This is available only as a WUM update and is effective from November 13, 2019 (11-13-2019). For more information on updating WSO2 Open Banking, see Updating WSO2 Products.
In the API Store, you can display both name and ID of the application if you have enabled UseSoftwareIdAsApplicationName
feature and configured the software_client_name
attributes.
Add the following to the
<WSO2_OB_APIM_HOME>/repository/conf/api-manager.xml
file under<ApplicationAttributes>
:<Attribute required="false"> <Name>software_client_name_sandbox</Name> <Description>Software Client Name of the sandbox</Description> </Attribute> <Attribute required="false"> <Name>software_client_name_production</Name> <Description>Software Client Name of the production</Description> </Attribute>
Open
<WSO2_OB_APIM_HOME>/repository/deployment/server/jaggeryapps/store/site/conf/site.json
and set the following value to true:"UseSoftwareIdAsApplicationName" : true
Add the given key-value pair to the following files:
"ID": "ID"
<WSO2_OB_APIM_HOME>/repository/deployment/server/jaggeryapps/store/site/conf/locales/jaggery/locale_default.json
<WSO2_OB_APIM_HOME>/repository/deployment/server/jaggeryapps/store/site/conf/locales/jaggery/locale_en.json
Once you follow the above instructions, notice the additional column ID under the Applications tab of the API Store.
Configuring application deletion workflow
This feature is available as a product update from September 4, 2019 (09-04-2019) onwards.
- Sign in to the API Manager Management Console at
https://<WSO2_OB_APIM_HOST>:9443/carbon
, using the super admin credentials. - On the Main tab, click Resources > Browse.
- Locate the
/_system/governance/apimgt/applicationdata/workflow-extensions.xml
registry file. - Click
workflow-extensions.xml
to edit the file. Under the Content section, click Edit as text.
Update the A
pplicationDeletion executor
value as follows:<ApplicationDeletion executor="com.wso2.finance.app.deletion.impl.ApplicationDeletionWorkflow"/>
- Click Save Content.
Registering an application
To get the public transport and signing certificates, enrol the TPP in the Open Banking Directory and upload the Certificate Signing Request (CSR).
The API allows the TPP to request the ASPSP to register a new client. The process is as follows:
The TPP sends a registration request,
This is a POST request including an SSA (Software Statement Assertion) as a claim in the payload.
The SSA is sent as a signed JWT, which is obtained from the Open Banking Directory. This contains the client metadata.
The software statement (SSA) should be obtained from the Open Banking Directory by the TPP. The SSA is a signed JWT issued by the Open Banking directory.
The automated DCR process is carried out by calling a synapse API in the gateway. The registration request relies on Mutual TLS authentication for TPP authentication.
An example request sent to the DCR registration endpoint is shown below:curl -X POST \ https://localhost:8243/open-banking/v3.2/register \ -H 'Content-Type: application/jwt' \ -d eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsImtpZCI6ImhjZ2V4dWd1VmI1cllTWVZCc2wtYzloQlB2WSJ9.eyJpc3MiOiJUUFAxIiwiaWF0IjoxNTU0MTg0NzY2LCJleHAiOjE3NDM1NzM1NjUsImp0aSI6IjkyNzEzODkyLTU1MTQtMTFlOS04NjQ3LWQ2NjNiZDg3M2Q5MyIsImF1ZCI6Imh0dHBzOi8vbG9jYWxob3N0OjgyNDMvdG9rZW4iLCJzY29wZSI6ImFjY291bnRzIHBheW1lbnRzIiwidG9rZW5fZW5kcG9pbnRfYXV0aF9tZXRob2QiOiJwcml2YXRlX2tleV9qd3QiLCJncmFudF90eXBlcyI6WyJhdXRob3JpemF0aW9uX2NvZGUiLCJyZWZyZXNoX3Rva2VuIl0sInJlc3BvbnNlX3R5cGVzIjpbImNvZGUiLCJjb2RlIGlkX3Rva2VuIl0sImlkX3Rva2VuX3NpZ25lZF9yZXNwb25zZV9hbGciOiJFUzI1NiIsInJlcXVlc3Rfb2JqZWN0X3NpZ25pbmdfYWxnIjoiRVMyNTYiLCJzb2Z0d2FyZV9pZCI6IlZnUU9JQk1laFBubExVUXcwQkZNNVMiLCJhcHBsaWNhdGlvbl90eXBlIjoid2ViIiwicmVkaXJlY3RfdXJpcyI6WyJodHRwczovL3dzbzIuY29tLyJdLCJzb2Z0d2FyZV9zdGF0ZW1lbnQiOiJleUpoYkdjaU9pSlFVekkxTmlJc0ltdHBaQ0k2SW1SVE0waEZlbk41VmtwUFRIcFJWa2hKVld0UFNrVXlTWEZyYlRONVNHSTBRbGxmVUdKQ1JWUlhhbGs5SWl3aWRIbHdJam9pU2xkVUluMC5leUpwYzNNaU9pSlBjR1Z1UW1GdWEybHVaeUJNZEdRaUxDSnBZWFFpT2pFMU5Ea3dNVEF5TVRrNE9EY3NJbXAwYVNJNkltRTBORFUyTXpoak9EYzFZalEwTmpNaUxDSnpiMlowZDJGeVpWOWxiblpwY205dWJXVnVkQ0k2SW5OaGJtUmliM2dpTENKemIyWjBkMkZ5WlY5dGIyUmxJam9pVkdWemRDSXNJbk52Wm5SM1lYSmxYMmxrSWpvaVZtZFJUMGxDVFdWb1VHNXNURlZSZHpCQ1JrMDFVeUlzSW5OdlpuUjNZWEpsWDJOc2FXVnVkRjlwWkNJNklsWm5VVTlKUWsxbGFGQnViRXhWVVhjd1FrWk5OVk1pTENKemIyWjBkMkZ5WlY5amJHbGxiblJmYm1GdFpTSTZJbFJGVTFSZlZGQlFJaXdpYzI5bWRIZGhjbVZmWTJ4cFpXNTBYMlJsYzJOeWFYQjBhVzl1SWpvaVZHaHBjeUJwY3lCaElIUmxjM1FnVkZCUUlpd2ljMjltZEhkaGNtVmZkbVZ5YzJsdmJpSTZNUzR4TENKemIyWjBkMkZ5WlY5amJHbGxiblJmZFhKcElqb2lhSFIwY0hNNkx5OTNjMjh5TG1OdmJTSXNJbk52Wm5SM1lYSmxYM0psWkdseVpXTjBYM1Z5YVhNaU9sc2lhSFIwY0hNNkx5OTNjMjh5TG1OdmJTOXlaV1JwY21WamRDSmRMQ0p6YjJaMGQyRnlaVjl5YjJ4bGN5STZXeUpCU1ZOUUlpd2lVRWxUVUNKZExDSnZjbWRoYm1sellYUnBiMjVmWTI5dGNHVjBaVzUwWDJGMWRHaHZjbWwwZVY5amJHRnBiWE1pT25zaVlYVjBhRzl5YVhSNVgybGtJam9pVDBKSFFsSWlMQ0p5WldkcGMzUnlZWFJwYjI1ZmFXUWlPaUpWYm10dWIzZHVNREF4TlRnd01EQXdNVWhSVVhKYVFVRllJaXdpYzNSaGRIVnpJam9pUVdOMGFYWmxJaXdpWVhWMGFHOXlhWE5oZEdsdmJuTWlPbHQ3SW0xbGJXSmxjbDl6ZEdGMFpTSTZJa2RDSWl3aWNtOXNaWE1pT2xzaVFVbFRVQ0lzSWxCSlUxQWlYWDBzZXlKdFpXMWlaWEpmYzNSaGRHVWlPaUpKUlNJc0luSnZiR1Z6SWpwYklrRkpVMUFpTENKUVNWTlFJbDE5TEhzaWJXVnRZbVZ5WDNOMFlYUmxJam9pVGt3aUxDSnliMnhsY3lJNld5SkJTVk5RSWl3aVVFbFRVQ0pkZlYxOUxDSnpiMlowZDJGeVpWOXNiMmR2WDNWeWFTSTZJbWgwZEhCek9pOHZkM052TWk1amIyMHZhVzFoWjJWekwyeHZaMjh1YW5Cbklpd2liM0puWDNOMFlYUjFjeUk2SWtGamRHbDJaU0lzSW05eVoxOXBaQ0k2SWpBd01UVTRNREF3TURGSVVWRnlXa0ZCV0NJc0ltOXlaMTl1WVcxbElqb2lWMU5QTWlBb1ZVc3BJRXhKVFVsVVJVUWlMQ0p2Y21kZlkyOXVkR0ZqZEhNaU9sdDdJbTVoYldVaU9pSkNkWE5wYm1WemN5SXNJbVZ0WVdsc0lqb2lkR1Z6ZEVCdFlXbHNMbU52YlNJc0luQm9iMjVsSWpvaUt6azBNREF3TURBd01DSXNJblI1Y0dVaU9pSkNkWE5wYm1WemN5SjlMSHNpYm1GdFpTSTZJbFJsWTJodWFXTmhiQ0lzSW1WdFlXbHNJam9pZEdWemRFQnRZV2xzTG1OdmJTSXNJbkJvYjI1bElqb2lLemswTURBd01EQXdNQ0lzSW5SNWNHVWlPaUpVWldOb2JtbGpZV3dpZlYwc0ltOXlaMTlxZDJ0elgyVnVaSEJ2YVc1MElqb2lhSFIwY0hNNkx5OXJaWGx6ZEc5eVpTNXZjR1Z1WW1GdWEybHVaM1JsYzNRdWIzSm5MblZyTHpBd01UVTRNREF3TURGSVVWRnlXa0ZCV0M4d01ERTFPREF3TURBeFNGRlJjbHBCUVZndWFuZHJjeUlzSW05eVoxOXFkMnR6WDNKbGRtOXJaV1JmWlc1a2NHOXBiblFpT2lKb2RIUndjem92TDJ0bGVYTjBiM0psTG05d1pXNWlZVzVyYVc1bmRHVnpkQzV2Y21jdWRXc3ZNREF4TlRnd01EQXdNVWhSVVhKYVFVRllMM0psZG05clpXUXZNREF4TlRnd01EQXdNVWhSVVhKYVFVRllMbXAzYTNNaUxDSnpiMlowZDJGeVpWOXFkMnR6WDJWdVpIQnZhVzUwSWpvaWFIUjBjSE02THk5clpYbHpkRzl5WlM1dmNHVnVZbUZ1YTJsdVozUmxjM1F1YjNKbkxuVnJMekF3TVRVNE1EQXdNREZJVVZGeVdrRkJXQzlXWjFGUFNVSk5aV2hRYm14TVZWRjNNRUpHVFRWVExtcDNhM01pTENKemIyWjBkMkZ5WlY5cWQydHpYM0psZG05clpXUmZaVzVrY0c5cGJuUWlPaUpvZEhSd2N6b3ZMMnRsZVhOMGIzSmxMbTl3Wlc1aVlXNXJhVzVuZEdWemRDNXZjbWN1ZFdzdk1EQXhOVGd3TURBd01VaFJVWEphUVVGWUwzSmxkbTlyWldRdlZtZFJUMGxDVFdWb1VHNXNURlZSZHpCQ1JrMDFVeTVxZDJ0eklpd2ljMjltZEhkaGNtVmZjRzlzYVdONVgzVnlhU0k2SW1oMGRIQnpPaTh2ZDNOdk1pNWpiMjB2ZEdWeWJYTXRiMll0ZFhObElpd2ljMjltZEhkaGNtVmZkRzl6WDNWeWFTSTZJbWgwZEhCek9pOHZkM052TWk1amIyMHZkR1Z5YlhNdGIyWXRkWE5sSWl3aWMyOW1kSGRoY21WZmIyNWZZbVZvWVd4bVgyOW1YMjl5WnlJNklsUkZVMVJQVWtjZ1ZGQlFJbjAuQ0E0aWZlXzdpdXFKYW54Yk9yYjZYZlFzVGU2WFFpdGhYOC1KS0xMaHhDNzJ0WEZSMTFSTm90Z2s5ajUwNW5TQjczQldEYWE3dFIwSG1MMVEzZXBNX0VTbEV1LUFLa2NrYlpVQVExQ0d5bHM2QVBta0w5NWtyWXZJWDc4VTI3cWpiTFU4MXlQdk8xWnhyeDY4X242Y2ZJelRweXAtdlN5MDlHcEd0cmZSZ1FieGpVMk9yZjllY1VwejF5S0toS3dXMlF4S00tSXV5aXpnN21jb1NFQkY1bmdWcXdsNU40Xy1kMEtzYjFCVzJaRWF0V2ZWTGFXVnJ2ZUZPUWhVbmlaQXJZVXNQRWxTOWdqRXVRdU5XZWpTcENMV2ZGd05oV1ppSUhHUWktenNscGgzY1pRYjZ6TXdTa1JYNmJSLVlzbTNGeFVxaGl3WHptMTh6a2V2U3ZSNVJ3In0.h_ixeb8Q-ne9Q7ZliWwjFq7B5uI8ohbWJESFMHDVJGhwuNBjDoBK1cMz3k0kC8zGZ8IqPkItNwA7mbLyKT7oMm94XwVUBXqwoJUMCvLnUtm-0MZDr_O7jFAc7r5UT8XxUJKFtoqZARJhDgCuFC0SGt215TwdwEK9AYRKt2mj3dh6dguA1tggGBAj3tV0iH-ZpX8PCtqsWiRSs5D-wbxz-F3YI0xpiolRaE2rzvwWkbr5VhB-_tv8uussWBnDGGwTo-MCUxM-9fzj4bL4mLLDQRrj5i6M6lU63AFIkwI7-qGkAKz0Gdxy6BjRxglengGCQWXjbPaNyYs_vht46bXfQA
The payload is a signed JWT payload. To sign it, use the signing certificate issued by the Open Banking Directory. The
kid
parameter of the header should match the values in thekid
of the signing certificate provided by the Open Banking Directory.The payload contains an SSA. Given below is a decoded SSA.
{ "alg": "PS256", "kid": "dS3HEzsyVJOLzQVHIUkOJE2Iqkm3yHb4BY_PbBETWjY=", "typ": "JWT" } { "iss": "OpenBanking Ltd", "iat": 1549010219887, "jti": "a445638c875b4463", "software_environment": "sandbox", "software_mode": "Test", "software_id": "VgQOIBMehPnlLUQw0BFM5S", "software_client_id": "VgQOIBMehPnlLUQw0BFM5S", "software_client_name": "TEST_TPP", "software_client_description": "This is a test TPP", "software_version": 1.1, "software_client_uri": "https://wso2.com", "software_redirect_uris": [ "https://wso2.com/redirect" ], "software_roles": [ "AISP", "PISP" ], "organisation_competent_authority_claims": { "authority_id": "OBGBR", "registration_id": "Unknown0015800001HQQrZAAX", "status": "Active", "authorisations": [ { "member_state": "GB", "roles": [ "AISP", "PISP" ] }, { "member_state": "IE", "roles": [ "AISP", "PISP" ] }, { "member_state": "NL", "roles": [ "AISP", "PISP" ] } ] }, "software_logo_uri": "https://wso2.com/images/logo.jpg", "org_status": "Active", "org_id": "0015800001HQQrZAAX", "org_name": "WSO2 (UK) LIMITED", "org_contacts": [ { "name": "Business", "email": "test@mail.com", "phone": "+940000000", "type": "Business" }, { "name": "Technical", "email": "test@mail.com", "phone": "+940000000", "type": "Technical" } ], "org_jwks_endpoint": "https://keystore.openbankingtest.org.uk/0015800001HQQrZAAX/0015800001HQQrZAAX.jwks", "org_jwks_revoked_endpoint": "https://keystore.openbankingtest.org.uk/0015800001HQQrZAAX/revoked/0015800001HQQrZAAX.jwks", "software_jwks_endpoint": "https://keystore.openbankingtest.org.uk/0015800001HQQrZAAX/VgQOIBMehPnlLUQw0BFM5S.jwks", "software_jwks_revoked_endpoint": "https://keystore.openbankingtest.org.uk/0015800001HQQrZAAX/revoked/VgQOIBMehPnlLUQw0BFM5S.jwks", "software_policy_uri": "https://wso2.com/terms-of-use", "software_tos_uri": "https://wso2.com/terms-of-use", "software_on_behalf_of_org": "TESTORG TPP" } <signature>
- The ASPSP validates the SSA based on the specifications provided in the Open Banking OpenID Dynamic Client (OIDC) Registration specification.
The ASPSP registers the client application using the metadata sent in the SSA.
If client creation is successful, the ASPSP responds with a JSON payload that describes the client that was created. The TPP can then use the client to access resources on the ASPSP's resource server.
If client creation is unsuccessful, the ASPSP responds with an error payload.
A sample response is given below:
ResponseHTTP/1.1 200 Ok Content-Type: application/json { "grant_types": [ "authorization_code", "refresh_token" ], "software_client_name": "Open Banking test", "supportedGrantTypes": [ "refresh_token", "client_credentials" ], "redirect_uris": [ "https://www.amazon.com", "https://www.amazon.com/tt/webview/oobe/proposition" ], "software_jwks_endpoint": "https://keystore.openbankingtest.org.uk/0015800001HQQrZAAX/3c8F2a7zpWaxnO5kFOZpyE.jwks", "token_endpoint_auth_method": "private_key_jwt", "client_secret": "DMcSUBmgi4tjKktagizDuDaiCAAa", "software_id": "3c8F2a7zpWaxnO5kFOZpyE", "software_logo_uri": "https://www.amazon.com/logo", "scope": [ "openid", "payments" ], "request_object_signing_alg": "ES256", "software_roles": [ "AISP", "PISP" ], "client_id": "kKcxI71dFnCtIHoM9zTZiG6U1GUa", "id_token_signed_response_alg": "ES256" }
Retrieving an application
The API allows the TPP to retrieve the details for a client that has already been registered. The request relies on Mutual TLS authentication and application access token (Client Credentials grant type) for TPP authentication.
The request has one path parameter named
ClientId
. It specifies the
ClientId
of the application that the TPP wants to retrieve details.
- If the request is successful and the identifier (
ClientId
) matches the client to whom the Client Credentials grant access token was issued, the ASPSP returns details of the requested client - If the
ClientId
is unknown, the ASPSP responds with anUnauthorized
status code and immediately revokes the access token
Given below is a sample request sent to the retrieving endpoint:
Updating an application
The API allows the TPP to request the ASPSP to modify one or more attributes related to an existing client. The request relies on Mutual TLS authentication and application access token (Client Credentials grant type) for TPP authentication.
The request has one path parameter named
ClientId
. It specifies the
ClientId
of the application that the TPP wants to modify. The TPP submits a JWS payload that describes the characteristics of the client to be modified. This must include all the claims, including the ones that will not be modified.
- If the client is successfully modified, the ASPSP responds with a JSON payload that describes the client that was created.
If the
ClientId
is unknown, the ASPSP responds with anUnauthorized
status code and immediately revokes the access token.If client modification is unsuccessful, the ASPSP responds with an error payload.
Deleting an application
The API allows the TPP to request the ASPSP to delete an existing client. The request relies on Mutual TLS authentication and application access token (Client Credentials grant type) for TPP authentication.
The request has one path parameter named ClientId
. It specifies the ClientId
of the application that the TPP wants to delete.
- If the request is successful and the
ClientId
matches the client to whom the Client Credentials grant access token was issued, the ASPSP must delete the client and invalidate long lived access tokens that were issued to the client - If the ClientId is unknown, the ASPSP responds with an Unauthorized status code and immediately revokes the access token
You can find a sample request sent to the retrieving endpoint below.
If the deletion is successful you will get a 204 No Content
response.