Consumer Data Standards API v1.3.0

This document explains the flow of events related to the Consumer Data Standards API v1.3.0.

Before you begin:

If you want to support ID permanence, follow the below steps before deploying the CDS Standard API in <WSO2_APIM_HOME>/repository/resources/finance/apis/consumerdatastandards.org.au/<version>:

Click here to see how it is done...

This is available only as a WUM update and is effective from March 24, 2021 (03-24-2021). For more information on updating WSO2 Open Banking, see Updating WSO2 Products.

Open <WSO2_OB_APIM_HOME>/repository/resources/api_templates/velocity_template.xml

Under

#if($apiObj.additionalProperties.get("ob-spec") == "au" && $apiObj.additionalProperties.get("ob-api-type") != "dcr" && $apiObj.additionalProperties.get("ob-api-type") != "cdr-arrangement" && $apiObj.additionalProperties.get("ob-api-type") != "cds-admin")

, add <handler class="com.wso2.finance.open.banking.gateway.au.IdPermanenceHandler"/>

after <handler class="com.wso2.finance.open.banking.gateway.api.schema.validation.RequestSchemaValidationHandler"/> and before <handler class="com.wso2.finance.open.banking.au.consent.enforcement.AUConsentEnforcementHandler">:

Click here to see modified the configuration...

##
## Start of AU Specification Handlers
##

#if($apiObj.additionalProperties.get("ob-spec") == "au" && $apiObj.additionalProperties.get("ob-api-type") != "dcr"
&& $apiObj.additionalProperties.get("ob-api-type") != "cdr-arrangement"
&& $apiObj.additionalProperties.get("ob-api-type") != "cds-admin")
<handler class="com.wso2.finance.open.banking.custom.throttling.CDSThrottlingPolicyHandler"/>
<handler class="com.wso2.finance.open.banking.mtls.validator.handler.MTLSValidationHandler"/>
<handler class="com.wso2.finance.open.banking.gateway.common.APIResourceAccessHandler"/>
<handler class="com.wso2.finance.open.banking.mtls.validator.handler.HolderOfKeyValidationHandler"/>
<handler class="com.wso2.finance.open.banking.gateway.api.schema.validation.RequestSchemaValidationHandler"/>
<handler class="com.wso2.finance.open.banking.gateway.au.IdPermanenceHandler"/>
<handler class="com.wso2.finance.open.banking.au.consent.enforcement.AUConsentEnforcementHandler">
    <property name="validationBaseUrl" value="https://IAM_HOSTNAME:9446/api/openbanking/consent-mgt/au100"/>
</handler>
#end

In case you have already deployed and subscribed the CDS Standard API,

Open the <WSO2_OB_APIM_HOME>/repository/deployment/server/synapse-configs/default/api/<API_PUBLISHER_NAME>–ConsumerDataStandards_vv1.xml. For example, <WSO2_OB_APIM_HOME>/repository/deployment/server/synapse-configs/default/api/mark-AT-gold.com--ConsumerDataStandards_vv1.xml and locate the <handlers> tag
Add <handler class="com.wso2.finance.open.banking.gateway.au.IdPermanenceHandler"/>
after <handler class="com.wso2.finance.open.banking.gateway.api.schema.validation.RequestSchemaValidationHandler"/> and before <handler class="com.wso2.finance.open.banking.au.consent.enforcement.AUConsentEnforcementHandler">:
```
<handler class="com.wso2.finance.open.banking.gateway.api.schema.validation.RequestSchemaValidationHandler"/>
<handler class="com.wso2.finance.open.banking.gateway.au.IdPermanenceHandler"/> 
<handler class="com.wso2.finance.open.banking.au.consent.enforcement.AUConsentEnforcementHandler">
```

Configure the encryption/decryption key for ID permanence. By default, the secret value is "wso2".
Restart the servers.
If you want to support ID permanence, follow the below steps before deploying the CDS API in <WSO2_APIM_HOME>/repository/resources/finance/apis/consumerdatastandards.org.au/<version>:

You need to deploy the following APIS:

Consumer Data Standards API - See Deploying APIs, for instruction on how to deploy this API.
Dynamic Client Registration API v0.1 - See Dynamic Client Registration API v0.1, to register an Accredited Data Recipient (ADR) application

Step 1 - Authorising CDR Arrangement IDs
Step 2 - Generate user access token
Step 3 - Invoke Consumer Data Standards API

Step 1 - Authorising CDR Arrangement IDs

There are two ways to send request_object in the authorisation URL. Authorisation and pushed authorisation endpoints are used by the bank to redirect the bank customer to authenticate and approve/deny consents before a Data Recipient accesses account or transaction information. Let's see how it is done in WSO2 Open Banking...

Request objects which contain the cdr_arrangement_id claim must only be sent using the Push Authorisation request. cdr_arrangement_id is a unique value representing a consent arrangement between a Data Recipient and Data Holder for a given consumer. You have to include it in the request object of the consent amendment request in PAR.

Method 1: Send the authorisation details in the authorisation URL:

Authorisation endpoint uses request_object, which consists of authorisation details in the authorisation URL.

Click here to see how it is done

Generate the request object by signing the following JSON payload using the supported algorithms.

The scope claim is required to access the data available via an endpoint. See Consumer Data Standards Australia - Authorisation Scopes, for more information on Authorisation scopes.

The refresh token is used to regenerate an access token. The sharing_duration claim in the request object defines the validity period of the refresh token. This is to limit the validity of the CDR Arrangement ID to the defined period.

Run the following authorisation URL in a browser to prompt the invocation of the authorize API. Make sure you update the placeholders with the relevant values:

Once you run the authorisation URL, you are directed to a login page.

Log in with the credentials of a user that has a Subscriber role.
If a secondary factor is required. For example, SMS OTP, provide the relevant values.
Upon successful authentication, the user is redirected to a page where the user needs to select the accounts that need to be authorised.
Then confirm or deny the access to displayed details in the selected account(s).

Upon agreement, the consumer is redirected to the callback URL of the ADR with the authorization code. For example:

https://www.google.com/redirects/redirect1#code=2c8a03f7-af33-326f-839a-63a4eebfe3f5&id_token=eyJraWQiOiJEd01LZFdNbWo3UFdpbnZvcWZReVhWenlaNlEiLCJlbmMiOiJBMTI4R0NNIiwiYWxnIjoiUlNBMV81In0.KaRhQA63F2Sm72zSZrkoRucIiz4IC0pzqApjTzSOJSyV_J6fYBwHuIAjLn4MZA36ZfVCmm3-KzqJcGAv9W9sDWBi7aI80CVKLFVJ2rh9l_9bMnANjm5fCsZ-pE_F4eW5BnqiU7xOoel31W2WF2brEWf9l5dibILU5E7inYKkQ9qPCS3Ei7uo9LTYQMWR4RQSglAsb5TsnijOPtGBvQgyuwOeI9vWBIcm7Y64NXuWKiv1iManbTepggpKhCSj9qPPizVV4v7Vv1IgHbvViRCE0uIvomLsL9qTxkBVK2s_h3welM9-9CE0WvoGkbYgsDc3nBQEx7Vj4hBiYJ0nD2_dWw.zslxDgOETvBaMOTQ.XAPYdrt5HXhvF53llXp40YkRHWBSrosYDc0UVLnqwJkAcNs3CQo8vWKSNqfc8l6CezvFPinul4LEp-eRrOqrpnhzAMf-W4O-s0jjF0dPsa3NII_qdi5bmCQhwxTVzo31SBiKn1aCBu8lQXSLUAz7z3UF6JyH1OkCXU3Ld8puF45QTRoTRPru8oNy8W8ZbchDj11IhEzrT9RPmWznCDQ3rs8M16R636-TuULXdSqJUGtXB3wteXu8lcgGpIMno1T6Bq2rI8Ncg_rCe6RgepAlEjlC0J0hpgMOk-EiXFDXN5N0NfEo6VSv9-M1v5THSJBThZIlcZrL-njz4G2NiDa30PSrQFqLgusYpZNpL1bHGsUbz_Xqvwlpjq-A5TcrqjxwWHkK383pY-tE064FKQuk93HnOee1gp4iRc9GLiqOK4vawSKStaSWe1oWxeFkDDuY85H3rFL1U8JzAC-vbPpozju82q7mONQto0q1fnCa80jtl5rDVsxzXLkEDbfwrvE-_13MKTLGc9io-PbEy6UgD9bAz5qvoOtNLWh0rcAbT5yhnZnruecB9l3yBsnbo60HQC_83mMzPWjGQaTm-ujO-hockrUSkezEO2JhNKrMWI5V-2aBNin_0UcSShMQnFy4P9baFKcyvrt2r3LNOvqfl_mK9qh57AOQw4vjhJRRaPVVacB8h5WCoiq8ut8wnHq3L2MvF9HId9T0Ug9FaPP76ofLziM.u19pyEql02PpVrFrki3RWA&state=af0ifjsldkj&session_state=c57cc0825bf8838fd2b6f14597ed34b5d9404493b216092e9daa766749cdac40.-1D9AEiTjPN-3hzlRFN97Q

The authorization code from the above URL is in the code parameter (code=4489572f-83c9-3589-b403-c4ecf8fb77f4).

Method 2: Send the authorisation details as a reference in the authorisation URL:

Unlike in the Authorisation endpoint, in the Pushed Authorisation endpoint, Data Recipients pushes authorisation details directly to the authorisation server and obtains a reference. The reference is notated by the claim; request_uri.Thereby, it prevents:

Intruders from intercepting the authorisation information sent in the request_object
Authorisation request calls becoming large with the authorisation details signed in the JWT

and protects the confidentiality and integrity of the authorisation details when passing through a third-party application. Let's see how it is done in WSO2 Open Banking:

Click here to see how it is done...

Configure <WSO2_OB_IAM_HOME>/repository/conf/deployment.toml as follows:
1. To resolve authorisation request calls with request_uri, a new request object builder must be added as follows:
```
[[oauth.oidc.custom_request_object_builder]]
type = "request_uri_param_value_builder"
class = "com.wso2.finance.open.banking.identity.extensions.builders.RequestUriRequestObjectBuilder"
```
2. By default, the expiry time of the request_uri is set to 60 seconds. If you need to change the value, use the sample configuration as follows:
```
[open_banking.au.push_authorisation]
expiry_time = "60"
```
3. Add the following configuration to have the Data Holde identifier in the response under the request_uri parameter:
```
[open_banking.au]
holder_identifier = "abc-bank"
```
Data Recipient shares the authorisation details with the authorisation server as a signed JWT and obtains request_uri in the response:
You can update scope, accounts, and sharing duration of an existing consent that you retrieved from the PAR endpoint. If you want to update the existing consent, include the cdr_arrangement_id parameter in the request object as follows:

This is available only as a WSO2 Update and is effective from July 14, 2021 (07-14-2021). For more information on updating WSO2 Open Banking, see Updating WSO2 Products.

See the sample request given below:
curl --location --request POST 'https://localhost:8243/par' \ --header 'Accept: application/json' \ --header 'Cache-Control: no-cache' \ --header 'Content-Type: application/x-www-form-urlencoded' \ --data-urlencode 'request=<signed request object> \ --data-urlencode 'client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer' \ --data-urlencode 'request=eyJhbGciOiJQUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6IkR3TUtkV01tajdQV2ludm9xZlF5WFZ6eVo2USJ9.eyJhdWQiOiJodHRwczovL2xvY2FsaG9zdDo4MjQzL3Rva2VuIiwicmVzcG9uc2VfdHlwZSI6ImNvZGUiLCJjbGllbnRfaWQiOiJIeGFJVXQyTUtvMnBZekJZZlBhRm9iSER0WlFhIiwicmVkaXJlY3RfdXJpIjoiaHR0cHM6Ly93d3cuZ29vZ2xlLmNvbS9yZWRpcmVjdHMvcmVkaXJlY3QxIiwic2NvcGUiOiJvcGVuaWQgYmFuazpwYXllZXM6cmVhZCIsInN0YXRlIjoiYWYwaWZqc2xka2oiLCJub25jZSI6Im4tMFM2X1d6QTJNaiIsImNsYWltcyI6eyJzaGFyaW5nX2R1cmF0aW9uIjoiODY0MDAwIiwiY2RyX2FycmFuZ2VtZW50X2lkIjoiOGVjMzRjNjAtZDljOS00YTc4LThlMGUtZTliM2ZkMTAwYjc0IiwiaWRfdG9rZW4iOnsiYWNyIjp7ImVzc2VudGlhbCI6dHJ1ZSwidmFsdWVzIjpbInVybjpjZHMuYXU6Y2RyOjMiXX19LCJ1c2VyaW5mbyI6eyJnaXZlbl9uYW1lIjpudWxsLCJmYW1pbHlfbmFtZSI6bnVsbH19fQ.MX_eTIrhnYf-u64Yn2rKpaF51s_JJsCiRbn0Ec9GxpGweeWWJLj-uwSJcOuu6ck3fGG5mr9OeE2014hTMzgn3jd7aBRbsXVOqjb3OapdnR84k5VDl5lK31i0Uf4HFxjKWIwrG6hu0_O3IYGNdev_DuNb26KO3FWYKgDp_eHn12KWYUVpPm1SGcFEo_o5JHZp50k3NNiE0nPCdzP0lOXrmi99y4SB1Q-tf85YhvqsCqQLhSpv5xmwvWPG8XLowTEdnVCu68Je-Jomw_OLQI9LZJZJPHrcfUlUshIw4Hswd1O2Wp1aolbH_zWQJlLE2LXrfL0KVLRA17WFmjK-kXhq5'\ --data-urlencode 'client_assertion=eyJraWQiOiJXX1RjblFWY0hBeTIwcTh6Q01jZEJ5cm9vdHciLCJhbGciOiJQUzI1NiJ9.eyJzdWIiOiJVT05ZVGlGVll2a09mcUlyVkRxeTkwUmtMTU1hIiwiYXVkIjoiaHR0cHM6Ly9sb2NhbGhvc3Q6ODI0My9wYXIiLCJpc3MiOiJVT05ZVGlGVll2a09mcUlyVkRxeTkwUmtMTU1hIiwiZXhwIjoxNjM4NjIzMjU5LCJqdGkiOiIzOTIxMzExMjE0OTEifQ.id6Yi6DS-KVnpKmHt9uZwN5X9gaFcZD6L0b9vrss_iA46RtpzlqRNeRdtMtoWYW1fKbqCvgz-gq-7HlzRBm9XO5CxTevCVliO-ObWju4Vyc9iLXYYBWpUo9H04HJkU8HUY3KPQDLtrijNBoEwOTv0zcEwxy-qVdkrT4F6t5eU6aZQf2MSiG-XdAd54vE-m2vx2pNsFE_ZLUXSv3YVfHuGFXzA21C0kumRhc4Mr1W3svzaNxHPb5E7w-61RXeJtnQY2WsgxmdYkSzg_rYJ1kAVfkZjW2l1KNP9uYpIewUMPnayiZ-RT1vDYCIcjnqbBOGrfStGASTg-2tFaWN8xI7eQ'
Run the following authorisation URL in a browser to prompt the invocation of the authorize API. Make sure you update the placeholders with the relevant values:
Once you run the authorisation URL, you are directed to a login page.
1. Log in with the credentials of a user that has a Subscriber role.
2. If a secondary factor is required. For example, SMS OTP, provide the relevant values.
3. Upon successful authentication, the user is redirected to a page where the user needs to select the accounts that need to be authorised.
4. Then confirm or deny the access to displayed details in the selected account(s).
5. Upon agreement, the consumer is redirected to the callback URL of the ADR with the authorization code. For example:
  https://www.google.com/redirects/redirect1#code=2c8a03f7-af33-326f-839a-63a4eebfe3f5&id_token=eyJraWQiOiJEd01LZFdNbWo3UFdpbnZvcWZReVhWenlaNlEiLCJlbmMiOiJBMTI4R0NNIiwiYWxnIjoiUlNBMV81In0.KaRhQA63F2Sm72zSZrkoRucIiz4IC0pzqApjTzSOJSyV_J6fYBwHuIAjLn4MZA36ZfVCmm3-KzqJcGAv9W9sDWBi7aI80CVKLFVJ2rh9l_9bMnANjm5fCsZ-pE_F4eW5BnqiU7xOoel31W2WF2brEWf9l5dibILU5E7inYKkQ9qPCS3Ei7uo9LTYQMWR4RQSglAsb5TsnijOPtGBvQgyuwOeI9vWBIcm7Y64NXuWKiv1iManbTepggpKhCSj9qPPizVV4v7Vv1IgHbvViRCE0uIvomLsL9qTxkBVK2s_h3welM9-9CE0WvoGkbYgsDc3nBQEx7Vj4hBiYJ0nD2_dWw.zslxDgOETvBaMOTQ.XAPYdrt5HXhvF53llXp40YkRHWBSrosYDc0UVLnqwJkAcNs3CQo8vWKSNqfc8l6CezvFPinul4LEp-eRrOqrpnhzAMf-W4O-s0jjF0dPsa3NII_qdi5bmCQhwxTVzo31SBiKn1aCBu8lQXSLUAz7z3UF6JyH1OkCXU3Ld8puF45QTRoTRPru8oNy8W8ZbchDj11IhEzrT9RPmWznCDQ3rs8M16R636-TuULXdSqJUGtXB3wteXu8lcgGpIMno1T6Bq2rI8Ncg_rCe6RgepAlEjlC0J0hpgMOk-EiXFDXN5N0NfEo6VSv9-M1v5THSJBThZIlcZrL-njz4G2NiDa30PSrQFqLgusYpZNpL1bHGsUbz_Xqvwlpjq-A5TcrqjxwWHkK383pY-tE064FKQuk93HnOee1gp4iRc9GLiqOK4vawSKStaSWe1oWxeFkDDuY85H3rFL1U8JzAC-vbPpozju82q7mONQto0q1fnCa80jtl5rDVsxzXLkEDbfwrvE-_13MKTLGc9io-PbEy6UgD9bAz5qvoOtNLWh0rcAbT5yhnZnruecB9l3yBsnbo60HQC_83mMzPWjGQaTm-ujO-hockrUSkezEO2JhNKrMWI5V-2aBNin_0UcSShMQnFy4P9baFKcyvrt2r3LNOvqfl_mK9qh57AOQw4vjhJRRaPVVacB8h5WCoiq8ut8wnHq3L2MvF9HId9T0Ug9FaPP76ofLziM.u19pyEql02PpVrFrki3RWA&state=af0ifjsldkj&session_state=c57cc0825bf8838fd2b6f14597ed34b5d9404493b216092e9daa766749cdac40.-1D9AEiTjPN-3hzlRFN97Q
6. The authorization code from the above URL is in the code parameter (code=4489572f-83c9-3589-b403-c4ecf8fb77f4).

To add a back button to the consent confirmation page:

This is available only as a WSO2 Update and is effective from July 05, 2021 (07-05-2021). For more information on updating WSO2 Open Banking, see Updating WSO2 Products.

Open the <WSO2_OB_IAM_HOME>/repository/conf/deployment.toml file.

Set the remove_on_consume_from_api tag to false.

[authentication.endpoint.redirect_params]
remove_on_consume_from_api = "false"

Step 2 - Generate user access token

In this section, you will be generating an access token using the authorization code generated in the section above.

Click here to see how it is done

The client_assertion is a JSON Web Token (JWT). Generate the client_assertion by signing the following JSON payload using the supported algorithms:

The value of the aud claim should contain the same value as the Identity Provider Entity ID.

Click here to view the Identity Provider Entity ID:

Sign in to the Identity and Access Management console at https://<WSO2_OB_IAM_HOST>:9446/carbon.
In the Main menu, go to Home > Identity > Identity Providers > Resident.
View the value in Resident Identity Provider > Inbound Authentication Configuration > OAuth2/OpenID Connect Configuration > Identity Provider Entity ID. By default this value is set to https://localhost:8243/token.

Run the following cURL command in a command prompt to generate the access token as an ADR user. Use --cert and --key in the access token generation request, for Mutual TLS authentication.

curl -X POST \
  https://<WSO2_OB_APIM_HOST>:8243/token \
  -H 'Cache-Control: no-cache' \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  --cert <TRANSPORT_PUBLIC_KEY_FILE_PATH> --key <TRANSPORT_PRIVATE_KEY_FILE_PATH> \
  -d 'client_id=<APPLICATION_ID>&grant_type=authorization_code&code=<GENERATED_CODE>&redirect_uri=<APPLICATION_REDIRECT_URI>&client_assertion_type=urn%3Aietf%3Aparams%3Aoauth%3Aclient-assertion-type%3Ajwt-bearer&client_assertion=<CLIENT_ASSERTION>'

The response of the contains an access token and a refresh token as follows:

{
   "access_token":"4f939510-4330-336a-a3d6-3cee7e9f50da",
   "refresh_token":"cedd647f-cb01-3112-bfea-3a5eb61d05a8",
   "scope":"bank:accounts.basic:read bank:accounts.detail:read bank:transactions:read openid",
   "id_token":"eyJ4NXQiOiJORFV3WldGbE16WmlZalV6WmpJeE5USTNZV0V4T0dWXmw",
   "token_type":"Bearer",
   "expires_in":3496
}

The access tokens have an expiration period, once an access token expires, you need to regenerate it. Run the following cURL command to generate a new access token using the refresh token:

curl -X POST \
 https://<WSO2_OB_APIM_HOST>:8243/token \
 -H 'Content-Type: application/x-www-form-urlencoded' \
 -H 'cache-control: no-cache' \
 --cert <PUBLIC_KEY_FILE_PATH> --key <PRIVATE_KEY_FILE_PATH> \
 -d 'grant_type=refresh_token&refresh_token=<REFRESH_TOKEN>&client_assertion_type=urn%3Aietf%3Aparams%3Aoauth%3Aclient-assertion-type%3Ajwt-bearer&client_assertion=<CLIENT_ASSERTION>'

Step 3 - Invoke Consumer Data Standards API

This section shows how to invoke the endpoints in the ConsumerDataStandards v1.3.0 API using a few samples. These requests use the access token generated in the step above.

For the Product Reference Data (PRD) endpoints,

When invoking these endpoints the value of the x-v parameter needs to be 3
The Transport layer certificates are not required in the request header

For example:

curl -X GET \
  https://<WSO2_OB_APIM_HOST>:8243/cds-au/v1/banking/products/ \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer  <USER_ACCESS_TOKEN>' \ 
  -H 'Cache-Control: no-cache' \
  -H 'Content-Type: application/json' \
  -H 'x-v: 3'

The PRD endpoints are

GET /banking/products - Get Products
GET /banking/products/{productId} - Get Products Detail

For the rest of the endpoints, the x-v value is 1.

GET /banking/accounts

The ADR is able to obtain a list of accounts that the consumer has authorised the ADR to access.

POST /banking/accounts/balances

The ADR is able to obtain balances for a specified list of accounts. The request body contains a list of account IDs to obtain balances for.

See Consumer Data Standards Australia - Banking APIs, for more information on all the available endpoints.

WSO2 Open Banking 2.0.0