Dynamic Client Registration API v0.1

Before you begin:

Deploy the Dynamic Client Registration v0.1 API.

Data Recipient must be accredited and the associated software product must be configured within the CDR Register.
Run the DCR related database scripts in the <WSO2_OB_APIM_HOME>/dbscripts/finance/dynamic-client-registration directory against the openbank_openbankingdb database.

CDR-registered software products of the Accredited Data Recipient (ADR) can be registered with one or more Data Holders. Thereby, the ADR can obtain client credentials and use it to retrieve consumer data. The Dynamic Client Registration (DCR) endpoint is capable of dynamically registering the ADRs with the Data Holders 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.

This document explains how to utilize DCR with WSO2 Open Banking.

Configuring dynamic client registration

Follow the steps below to configure the DCR API v0.1 in WSO2 Open Banking.

Updating open-banking.xml

Open the <WSO2_OB_APIM_HOME>/repository/conf/finance/open-banking.xml file.

Set the <UseSoftwareIdAsApplicationName> property under the <DCR> property to true.

Setting this property to true ensures that the SoftwareId in Software Statement Assertion (SSA) is used as the application name.

<DCR>
	<UseSoftwareIdAsApplicationName>true</UseSoftwareIdAsApplicationName>
</DCR>

Updating identity.xml

To display the DCR endpoint in OpenID Connect Discovery (https://<WSO2_OB_KM_HOST>:8243/.well-known/openid-configuration) :

Open the <WSO2_OB_KM_HOME>/repository/conf/identity/identity.xml file.
Update the value of the <OAuth2DCREPUrl> property with the DCR endpoint.

<OAuth2DCREPUrl>${carbon.protocol}://localhost:8243/open-banking/0.1/register</OAuth2DCREPUrl>

Updating api-manager.xml

To store any properties retrieved from the SSA, add the server-level configuration to the <OB_AM_HOME>/repository/conf/api-manager.xml file as explained here. Ideally, you need to add the following application attributes under <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 since these attributes are not mandatory.

In addition to these, include software_jwks_endpoint in the SSA. This is required to obtain an application access token.

<ApplicationConfiguration>
	<ApplicationAttributes>
		<Attribute required="false">
			<Name>software_id_sandbox</Name>
			<Description>Software ID of the sandbox</Description>
		</Attribute>
		<Attribute required="false">
			<Name>software_id_production</Name>
			<Description>Software ID of the production</Description>
		</Attribute>		
		<Attribute required="false">
			<Name>software_roles_sandbox</Name>
			<Description>Software roles of the sandbox</Description>
		</Attribute>
		<Attribute required="false">
			<Name>software_roles_production</Name>
			<Description>Software roles of the production</Description>
		</Attribute>
	<Attribute required="false">
			<Name>software_jwks_endpoint_sandbox</Name>
			<Description>JWKS endpoint of sandbox</Description>
		</Attribute>
		<Attribute required="false">
			<Name>software_jwks_endpoint_production</Name>
			<Description>JWKS endpoint of production</Description>
		</Attribute>
	</ApplicationAttributes>
</ApplicationConfiguration>

[Back to Top]

Registering an application

If your application has one or more Callback URLs that exceed the default sizes, increase the column sizes of the CALLBACK_URL columns.

The Callback URLs are stored in the database as follows:

Database	Table	Column	Default Size
`openbank_apimgtdb`	`AM_APPLICATION`	`CALLBACK_URL`	`varchar 512`
`openbank_apimgtdb`	`IDN_OAUTH_CONSUMER_APPS`	`CALLBACK_URL`	`varchar 1024`

The API allows the ADR to request the Data Holder to register a new client. The process is as follows:

The ADR sends a registration request,

This is a POST request including a Software Statement Assertion (SSA) as a claim in the payload. If you want to change the request object, use the signing certificate and the private keys attached for the testing purpose:
1. Signing certificate
2. Private keys
  
  Note that the signature of the SSA is not currently validated due to the unavailability of the SSA verification JWKS URI of Australian Competition and Consumer Commission (ACCC).
The automated DCR process is carried out by calling a synapse API in the gateway.

An example request sent to the DCR registration endpoint is shown below:

Request

curl -X POST \https://localhost:8243/open-banking/0.1/register \
-H "accept: application/json" 
-H "Content-Type: application/jwt" 
-H "x-v: 0.1" 
-d eyJ0eXAiOiJKV1QiLCJhbGciOiJQUzI1NiIsImtpZCI6ImhjZ2V4dWd1VmI1cllTWVZCc2wtYzloQlB2WSJ9.eyJpc3MiOiJNb2NrIENvbXBhbnkiLCJpYXQiOjE1NzIyMjUzMzYsImV4cCI6MTYwMzg0NzczMSwianRpIjoiMzc3NDdjZDEtYzEwNS00NTY5LTlmNzUtNGFkZjI4YjczZTMxIiwiYXVkIjoiaHR0cHM6Ly93d3cuaW5mb3NlYy5jZHIuZ292LmF1L3Rva2VuIiwicmVkaXJlY3RfdXJpcyI6WyJodHRwczovL3d3dy5nb29nbGUuY29tL3JlZGlyZWN0cy9yZWRpcmVjdDEiLCJodHRwczovL3d3dy5nb29nbGUuY29tL3JlZGlyZWN0cy9yZWRpcmVjdDIiXSwidG9rZW5fZW5kcG9pbnRfYXV0aF9zaWduaW5nX2FsZyI6IlBTMjU2IiwidG9rZW5fZW5kcG9pbnRfYXV0aF9tZXRob2QiOiJwcml2YXRlX2tleV9qd3QiLCJncmFudF90eXBlcyI6WyJhdXRob3JpemF0aW9uX2NvZGUiLCJyZWZyZXNoX3Rva2VuIiwidXJuOmlldGY6cGFyYW1zOm9hdXRoOmdyYW50LXR5cGU6and0LWJlYXJlciJdLCJyZXNwb25zZV90eXBlcyI6WyJjb2RlIGlkX3Rva2VuIl0sImFwcGxpY2F0aW9uX3R5cGUiOiJ3ZWIiLCJpZF90b2tlbl9zaWduZWRfcmVzcG9uc2VfYWxnIjoiUFMyNTYiLCJyZXF1ZXN0X29iamVjdF9zaWduaW5nX2FsZyI6IlBTMjU2Iiwic29mdHdhcmVfc3RhdGVtZW50IjoiZXlKaGJHY2lPaUpRVXpJMU5pSXNJbXRwWkNJNkltSTRabUZqWmpKbVpqTTVORFEwWmpjNE1XVXdZbVUxWkdJMFlqRTBaakUySWl3aWRIbHdJam9pU2xkVUluMC5leUpwYzNNaU9pSmpaSEl0Y21WbmFYTjBaWElpTENKcFlYUWlPakUxTnpFNE1EZ3hOamNzSW1WNGNDSTZNakUwTnpRNE16WTBOaXdpYW5ScElqb2lNMkpqTWpBMVlURmxZbU01TkRObVltSTJNalJpTVRSbVkySXlOREV4T1RZaUxDSnZjbWRmYVdRaU9pSXpRakJDTUVFM1FpMHpSVGRDTFRSQk1rTXRPVFE1TnkxRk16VTNRVGN4UkRBM1F6Z2lMQ0p2Y21kZmJtRnRaU0k2SWsxdlkyc2dRMjl0Y0dGdWVTQkpibU11SWl3aVkyeHBaVzUwWDI1aGJXVWlPaUpOYjJOclUyOW1kSGRoY21VaUxDSmpiR2xsYm5SZlpHVnpZM0pwY0hScGIyNGlPaUpCSUcxdlkyc2djMjltZEhkaGNtVWdjSEp2WkhWamRDQm1iM0lnZEdWemRHbHVaeUJUVTBFaUxDSmpiR2xsYm5SZmRYSnBJam9pYUhSMGNITTZMeTkzZDNjdVoyOXZaMnhsTG1OdmJTSXNJbkpsWkdseVpXTjBYM1Z5YVhNaU9sc2lhSFIwY0hNNkx5OTNkM2N1WjI5dloyeGxMbU52YlM5eVpXUnBjbVZqZEhNdmNtVmthWEpsWTNReElpd2lhSFIwY0hNNkx5OTNkM2N1WjI5dloyeGxMbU52YlM5eVpXUnBjbVZqZEhNdmNtVmthWEpsWTNReUlsMHNJbXh2WjI5ZmRYSnBJam9pYUhSMGNITTZMeTkzZDNjdVoyOXZaMnhsTG1OdmJTOXNiMmR2Y3k5c2IyZHZNUzV3Ym1jaUxDSjBiM05mZFhKcElqb2lhSFIwY0hNNkx5OTNkM2N1WjI5dloyeGxMbU52YlM5MGIzTXVhSFJ0YkNJc0luQnZiR2xqZVY5MWNta2lPaUpvZEhSd2N6b3ZMM2QzZHk1bmIyOW5iR1V1WTI5dEwzQnZiR2xqZVM1b2RHMXNJaXdpYW5kcmMxOTFjbWtpT2lKb2RIUndjem92TDJ0bGVYTjBiM0psTG05d1pXNWlZVzVyYVc1bmRHVnpkQzV2Y21jdWRXc3ZNREF4TlRnd01EQXdNVWhSVVhKYVFVRllMMVpuVVU5SlFrMWxhRkJ1YkV4VlVYY3dRa1pOTlZNdWFuZHJjeUlzSW5KbGRtOWpZWFJwYjI1ZmRYSnBJam9pYUhSMGNITTZMeTlyWlhsemRHOXlaUzV2Y0dWdVltRnVhMmx1WjNSbGMzUXViM0puTG5Wckx6QXdNVFU0TURBd01ERklVVkZ5V2tGQldDOXlaWFp2YTJWa0wxWm5VVTlKUWsxbGFGQnViRXhWVVhjd1FrWk5OVk11YW5kcmN5SXNJbk52Wm5SM1lYSmxYMmxrSWpvaU56UXdRek0yT0VZdFJVTkdPUzAwUkRJNUxVRXlSVUV0TURVeE5FRTJOa0l3UTBSRklpd2ljMjltZEhkaGNtVmZjbTlzWlhNaU9pSmtZWFJoTFhKbFkybHdhV1Z1ZEMxemIyWjBkMkZ5WlMxd2NtOWtkV04wSWl3aWMyTnZjR1VpT2lKaFkyTnZkVzUwY3lKOS53V3RqR3h5cUpfcDRWSEZlY0xJQlJ2aXZRRXhoVzNlc0tGZTlnTUVFdXZYQ1VMYklFdUs1OTRHbEw1b1dvalNnQUFpcmtGV3BfRl9OU2NrR1Q0ajRDMzVaRmtybDgyTUlSemZUSmFGeHdrcklFSmpCRFhVdjhWRnVmTnlnS1BlbWxOM2FTUTVkei1ESU1uNWVDVWJpTWE4WGozN1R6THFNZi1nUm96ZFdVSTFPbmVnenJVYmsycC1Qd1c3U25UZkRyaUNLblRPZmRvZklRdnZMdmVqN0NUemhWTm01VS1tT0xWQUpJb285U2s1aE9oTVJuajlwa0FjTDVDX0JNWEk0WWgyXzZ5bWZVR3dFdDMxRkR2LS14NVhIU3dfdWFNaXE5Y05Nd19wTkZRY3NrMzFHTElaTU5qcW9CMFdRU1A0aUpuZS1QdDdiMDlWU3VmeTR5dl8tLUEifQ.lEAH2HBlPF4JThXV9Ume1EsjzutWroRHiHNdrF82wfpiWJaUWHJN0VtrAOFWD0rpBL30lwAseLAqjgqzMGv2NVCmTIJ6y7V6VQG3rbtsg3EdkjLSaMy8YQpyjrJgrqh0LpmjZbVJ7Y50PzwIImB63ouYLzECNKxB-Fic2vOoEJfiVleUXrMqTI24lAvK6Sa4nKRFB_-VRMlIEizKMjd0KqV0XBvjf6esQ6tQvs-1khafNSiGUOMuz8nFJtSUd8ojByZkW30i4XEcYEW4Ckb0NdYKqAIf6WCLxzi9D17DMFenSWsvytj0o3YaIxj1FLN5UvJ4FH32qOGjDJYrz2_YNg

Given below is the format of the payload JWT once decoded:

{
"typ": "JWT",
"alg": "PS256",
"kid": "UtWvx0VQCXAZgxUQP_AgoUScEMjZUcZ6d3vO_XmpSN0"
}
{
"iss": "Mock Company",
"iat": 1572225336,
"exp": 1703847731,
"jti": "37747cd1-c105-4569-9f75-4adf28b73e31",
"aud": "https://www.infosec.cdr.gov.au/token",
"redirect_uris": [
"https://www.google.com/redirects/redirect1",
"https://www.google.com/redirects/redirect2"
],
"token_endpoint_auth_signing_alg": "PS256",
"token_endpoint_auth_method": "private_key_jwt",
"grant_types": [
"authorization_code",
"refresh_token",
"urn:ietf:params:oauth:grant-type:jwt-bearer"
],
"response_types": [
"code id_token"
],
"application_type": "web",
"id_token_signed_response_alg": "PS256",
"request_object_signing_alg": "PS256",
"software_statement": "eyJhbGciOiJQUzI1NiIsImtpZCI6ImI4ZmFjZjJmZjM5NDQ0Zjc4MWUwYmU1ZGI0YjE0ZjE2IiwidHlwIjoiSldUIn0.eyJpc3MiOiJjZHItcmVnaXN0ZXIiLCJpYXQiOjE1NzE4MDgxNjcsImV4cCI6MjE0NzQ4MzY0NiwianRpIjoiM2JjMjA1YTFlYmM5NDNmYmI2MjRiMTRmY2IyNDExOTYiLCJvcmdfaWQiOiIzQjBCMEE3Qi0zRTdCLTRBMkMtOTQ5Ny1FMzU3QTcxRDA3QzgiLCJvcmdfbmFtZSI6Ik1vY2sgQ29tcGFueSBJbmMuIiwiY2xpZW50X25hbWUiOiJNb2NrIFNvZnR3YXJlIiwiY2xpZW50X2Rlc2NyaXB0aW9uIjoiQSBtb2NrIHNvZnR3YXJlIHByb2R1Y3QgZm9yIHRlc3RpbmcgU1NBIiwiY2xpZW50X3VyaSI6Imh0dHBzOi8vd3d3Lm1vY2tjb21wYW55LmNvbS5hdSIsInJlZGlyZWN0X3VyaXMiOlsiaHR0cHM6Ly93d3cuZ29vZ2xlLmNvbS9yZWRpcmVjdHMvcmVkaXJlY3QxIiwiaHR0cHM6Ly93d3cuZ29vZ2xlLmNvbS9yZWRpcmVjdHMvcmVkaXJlY3QyIl0sImxvZ29fdXJpIjoiaHR0cHM6Ly93d3cubW9ja2NvbXBhbnkuY29tLmF1L2xvZ29zL2xvZ28xLnBuZyIsInRvc191cmkiOiJodHRwczovL3d3dy5tb2NrY29tcGFueS5jb20uYXUvdG9zLmh0bWwiLCJwb2xpY3lfdXJpIjoiaHR0cHM6Ly93d3cubW9ja2NvbXBhbnkuY29tLmF1L3BvbGljeS5odG1sIiwiandrc191cmkiOiJodHRwczovL2dpc3QuZ2l0aHVidXNlcmNvbnRlbnQuY29tL2ltZXNoOTQvMzE3MmUyZTQ1NzU3Y2RhMDhlYzI3MjdmOTBiNzJjZWQvcmF3L2ZmMGQzZWFiZTRjZGRjZTQ3ZWVjMDIyOGY1OTIxNzUyMjNkZDkyYjIvd3NvMi1hdS1kY3ItZGVtby5qd2tzIiwicmV2b2NhdGlvbl91cmkiOiJodHRwczovL2dpc3QuZ2l0aHVidXNlcmNvbnRlbnQuY29tL2ltZXNoOTQvMzE3MmUyZTQ1NzU3Y2RhMDhlYzI3MjdmOTBiNzJjZWQvcmF3L3Jldm9rZWQvZmYwZDNlYWJlNGNkZGNlNDdlZWMwMjI4ZjU5MjE3NTIyM2RkOTJiMi93c28yLWF1LWRjci1kZW1vLmp3a3MiLCJzb2Z0d2FyZV9pZCI6Ijc0MEMzNjhGLUVDRjktNEQyOS1BMkVBLTA1MTRBNjZCMENESCIsInNvZnR3YXJlX3JvbGVzIjoiZGF0YS1yZWNpcGllbnQtc29mdHdhcmUtcHJvZHVjdCIsInNjb3BlIjoiYmFuazphY2NvdW50cy5iYXNpYzpyZWFkIGJhbms6YWNjb3VudHMuZGV0YWlsOnJlYWQgYmFuazp0cmFuc2FjdGlvbnM6cmVhZCBiYW5rOnBheWVlczpyZWFkIGJhbms6cmVndWxhcl9wYXltZW50czpyZWFkIGNvbW1vbjpjdXN0b21lci5iYXNpYzpyZWFkIGNvbW1vbjpjdXN0b21lci5kZXRhaWw6cmVhZCBjZHI6cmVnaXN0cmF0aW9uIn0.cjtwA7YZyr1oe6tjXUKYWmrBmznsd-6kRX6UVppz-oV_4wl4zjcy0jhJK9Jy22kxumzdFbp-zEfJmUldx5VWe4Tl_Bm1BRN8DjRfU4EsywqQILgKPBVQAkxFYgdPxxYjkypFiyYBCxaLRp9gtwEk_EP-0bcEmSzF2Dxm10LOVT9dJ_tw2GykuOZXUTdAk5J4bXDFbuIuSwF-pTDKVcx6CA4qa_BMXWvrijrJNldG3ABaW5kfSKw90nSs3TyjQG5xRL1ePnlDa3SxqNtEinuB3OvCofVSilpfQdccC1hrVWyJqspEMao8602d_sIXN6PxOYiKn0phX954jDzfPDCh_w"
}

Click here to find the claims in the body of the request payload...

Claim	Description	Optional
iss	Contains the identifier for the ADR Software Product as defined in the CDR Register	NO
iat	`Issued at time` claim	NO
exp	`Expiration Time` claim	NO
aud	Data Holder auth server URI	NO
jti	`JWT ID` claim. A unique identifier for the token used to prevent reuse of the token	NO
redirect_uris	An array of redirection URI strings for use in redirect-based flows. Only required if overwrites a list of values in the software statement. If used, redirect_uris MUST match or be a subset of the redirect_uris as defined in the SSA	YES
token_endpoint_auth_method	The requested authentication method for the token endpoint. The only supported method will be private_key_jwt	NO
grant_types	An array of OAuth 2.0 grant type strings that the client can use at the token endpoint. Supported values: [client_credentials, authorization_code, refresh_token, urn:ietf:params:oauth:grant-type:jwtbearer]	NO
response_types	value: [code id_token]	YES
software_statement	Software statement assertion issued by the CDR Register	NO
application_type	Kind of the application. The only supported application type will be web	YES
id_token_signed_response_alg	The algorithm which the ADR expects the id_token to be signed with, if an id_token is returned Supported values as constrained by FAPI-RW	YES
request_object_signing_alg	The algorithm which the ADR expects to sign the request object if a request object will be part of the authorization request sent to the Data Holder Supported values as constrained by FAPI-RW	YES

The Data Holder validates the SSA based as specified in the Consumer Data Right (CDR) Dynamic Client Registration specification.
The Data Holder registers the client application using the metadata sent in the SSA.

If client creation is successful, the Data Holder responds with a JSON payload that describes the client that was created. The ADR can then use the client to access resources on the Dara Holder's resource server.

If client creation is unsuccessful, the Data Holder responds with an error payload.

A sample response is given below:

{
    "clientId": "fZ1nESbD3xwqkXhchy6NHMqeBvMa",
    "clientIdIssuedAt": 1574233558,
    "clientName": "MockSoftware",
    "clientDescription": "A mock software product for testing SSA",
    "clientUri": "https://www.google.com",
    "orgId": "3B0B0A7B-3E7B-4A2C-9497-E357A71D07C8",
    "orgName": "Mock Company Inc.",
    "redirectUris": [
        "https://www.google.com/redirects/redirect1",
        "https://www.google.com/redirects/redirect2"
    ],
    "logoUri": "https://www.google.com/logos/logo1.png",
    "tosUri": "https://www.google.com/tos.html",
    "policyUri": "https://www.google.com/policy.html",
    "jwksUri": "https://keystore.openbankingtest.org.uk/0015800001HQQrZAAX/VgQOIBMehPnlLUQw0BFM5S.jwks",
    "revocationUri": "https://keystore.openbankingtest.org.uk/0015800001HQQrZAAX/revoked/VgQOIBMehPnlLUQw0BFM5S.jwks",
    "softwareId": "740C368F-ECF9-4D29-A2EA-0514A66B0CDE",
    "softwareRoles": "data-recipient-software-product",
    "scope": "accounts",
    "tokenEndpointAuthSigningAlg": "PS256",
    "tokenEndpointAuthMethod": "private_key_jwt",
    "grantTypes": [
        "authorization_code",
        "refresh_token",
        "urn:ietf:params:oauth:grant-type:jwt-bearer"
    ],
    "applicationType": "web",
    "idTokenSignedResponseAlg": "PS256",
    "requestObjectSigningAlg": "PS256"
}

Generate a Client Credentials grant access token for the application using the following command:

curl -k  POST \ https://<WSO2_OB_APIM_HOST>:8243/token \
-H 'Cache-Control: no-cache' \
-H 'Content-Type: application/x-www-form-urlencoded' \
--cert <PUBLIC_KEY_FILE_PATH> --key <PRIVATE_KEY_FILE_PATH> \
-d 'grant_type=client_credentials&scope=openid&client_assertion=<CLIENT_ASSERTION_JWT>&client_assertion_type=urn%3Aietf%3Aparams%3Aoauth%3Aclient-assertion-type%3Ajwt-bearer&redirect_uri=<APPLICATION_CALLBACK_URL>'

[Back to Top]

Retrieving an application

The API allows the ADR to retrieve the details for a client that has already been registered. The request consists of one path parameter named ClientId that the ADR wants to retrieve details for.

If the request is successful and the identifier ( ClientId) matches the client to whom the Client Credentials grant access token was issued, the Data Holder returns details of the requested client.
If the ClientId is unknown, the Data Holder responds with an Unauthorized status code.

You can find the sample request and response below:

[Back to Top]

Updating an application

The API allows the ADR to request the Data Holder to modify one or more attributes related to an existing client. The ADR submits ClientId as a path parameter and 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 Data Holder responds with a JSON payload.
If the ClientId is unknown, the Data Holder responds with an Unauthorized status code.
If client modification is unsuccessful, the Data Holder responds with an error payload.

You can find the sample request and response below:

[Back to Top]

Deleting an application

The API allows the ADR to request the Data Holder to delete an existing client. The request consists of one path parameter namely ClientId of the ADR, which should be deleted.

If the request is successful and the ClientIdmatches the client to whom the Client Credentials grant access token was issued, the Data Holder must delete the client and invalidate long-lived access tokens that were issued to the client.
If the ClientId is unknown, the Data Holder responds with an Unauthorized status code.

You can find the sample request and response below:

[Back to Top]