This documentation is for WSO2 Open Banking version 1.5.0. View documentation for the latest release.
Skip to end of metadata
Go to start of metadata

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

Before you begin:

You need to deploy the following APIS.

  • Consumer Data Standards API in <WSO2_OB_APIM_HOME>/repository/resources/finance/apis/consumerdatastandards.org.au/1.2.0/consumer-data-standards-1.2.0.yaml file. See Deploying APIs, for instruction on how to deploy this API.
  • Consumer Data Standards Dynamic Client Registration API v0.1 to register an Accredited Data Recipient (ADR) application. See Dynamic Client Registration API v0.1.

Step 1 - Authorising account consents

The bank redirects the bank customer to authenticate and approve/deny application-provided consents.

 Click here to see how it is done
  1. Generate the request object by signing the following JSON payload using the supported algorithms.

    To configure the supporting algorithms:

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

    2. Update the following configurations with the algorithm:

      <UK>
      	<!-- The following configuration specifies the signature algorithms allowed in the DR requests.
              The JWTs signed in algorithms that are not in the following list, will be rejected. If the configuration
              is not present, no validation will occur and any algorithm will be passed through.
              Allowed values are:
                  1. PS256
                  2. RS256
              -->
      	<AllowedInboundSignatureAlgorithms>
      		<Algorithm>PS256</Algorithm>
      	</AllowedInboundSignatureAlgorithms>
      </UK>

    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 consent to the defined period.

    ## Decoded request JWT format
    {
      "kid": "<Certificate fingerprint>",
      "typ": "JWT",
      "alg": "<Supported algorithm>"
    }
    {
      "iss": "<Application ID>",
      "aud": "<Audience the ID Token is intended for. For example,https://<WSO2_OB_APIM_HOST>:8243/token>",
      "response_type": "<code:Retrieves authorize code, code id_token: Retrieves authorize token and ID token>",
      "exp": <A JSON number representing the number of seconds from 1970-01-01T00:00:00Z to the UTC expiry time>,
      "client_id": "<Application ID>",
      "redirect_uri": "<Redirect URL of the client application>",
      "scope": "<Available scopes are bank:accounts.basic:read, bank:accounts.detail:read, bank:transactions:read, bank:payees:read, bank:regular_payments:read, common:customer.basic:read, and common:customer.detail:read >",
      "state": "af0ifjsldkj",
      "nonce": "<Prevents replay attacks>",
      "claims": {
        "sharing_duration": "<Requested duration for sharing, in seconds>",
        "id_token": {
          "acr": {
            "values": ["urn:cds.au:cdr:3"]
          }
        }
      }
    }
    <signature>
    eyJhbGciOiJQUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6IjEyMyJ9.eyJhdWQiOiJodHRwczovL2xvY2FsaG9zdDo4MjQzL3Rva2VuIiwicmVzcG9uc2VfdHlwZSI6ImNvZGUgaWRfdG9rZW4iLCJjbGllbnRfaWQiOiJyVnB3dVlFNzJ2WlAyOHVjVGUzdlA3Y0gwemthIiwicmVkaXJlY3RfdXJpIjoiaHR0cHM6Ly93d3cuZ29vZ2xlLmNvbSIsInNjb3BlIjoib3BlbmlkIGJhbms6YWNjb3VudHMuZGV0YWlsOnJlYWQgYmFuazp0cmFuc2FjdGlvbnM6cmVhZCIsInN0YXRlIjoiYWYwaWZqc2xka2oiLCJub25jZSI6Im4tMFM2X1d6QTJNaiIsImNsYWltcyI6eyJzaGFyaW5nX2R1cmF0aW9uIjoiNzIwMCIsImlkX3Rva2VuIjp7ImFjciI6eyJlc3NlbnRpYWwiOnRydWUsInZhbHVlcyI6WyJ1cm46Y2RzLmF1OmNkcjozIl19fSwidXNlcmluZm8iOnsiZ2l2ZW5fbmFtZSI6bnVsbCwiZmFtaWx5X25hbWUiOm51bGx9fX0.HzS8ViBsLvZ_lDyf0ArmejPJfS0Ayz_aBwHHbQezd5iob6ybmIGae5l_pHfgy7-vfMmmpH8hAQp8YjfRy7NFDqw5TSabf_BS_u0Ff2Pj8nhumSRTQITMMoq0YatKJwJttpbFXdSurQWtGnhIFiT5Z2tWgb325ChYSwi4-k7Wk7K9HMFsqrhqqPRw-4lBjwiEYnQUd6Zu0R8ptNNxvZe7rRCB0BKH1Q1f1biE93YeZMkAHMe5TDQt0EHQxiQNwZnDGINGG-YqT4wtzw_ANU_Yll29fr6ed2Fcu1P64OVYpTNHDuWNEgT52Td-CM6-p3Dy8035lIeHB-GN6cyrz_4rqQ
  2. Run the following in a browser to prompt the invocation of the authorize API. Make sure you update the placeholders with the relevant values:

    https://<WSO2_OB_APIM_HOST>:8243/authorize?prompt=login&response_type=code id_token&client_id=<APPLICATION_ID>&redirect_uri=<APPLICATION_REDIRECT_URI>&scope=<AUTHORISATION_SCOPE_AS_PER_REQUEST_OBJECT>&nonce=n-0S6_WzA2Mj
    &state=af0ifjsldkj HTTP/1.1&request=<REQUEST_OBJECT>
    https://localhost:8243/authorize?prompt=login&response_type=code id_token&client_id=rVpwuYE72vZP28ucTe3vP7cH0zka&redirect_uri=https://www.wso2.com&scope=openid bank:accounts.detail:read bank:transactions:read&nonce=n-0S6_WzA2Mj &state=af0ifjsldkj HTTP/1.1&request=eyJhbGciOiJQUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6IjEyMyJ9.eyJhdWQiOiJodHRwczovL2xvY2FsaG9zdDo4MjQzL3Rva2VuIiwicmVzcG9uc2VfdHlwZSI6ImNvZGUgaWRfdG9rZW4iLCJjbGllbnRfaWQiOiJyVnB3dVlFNzJ2WlAyOHVjVGUzdlA3Y0gwemthIiwicmVkaXJlY3RfdXJpIjoiaHR0cHM6Ly93d3cuZ29vZ2xlLmNvbSIsInNjb3BlIjoib3BlbmlkIGJhbms6YWNjb3VudHMuZGV0YWlsOnJlYWQgYmFuazp0cmFuc2FjdGlvbnM6cmVhZCIsInN0YXRlIjoiYWYwaWZqc2xka2oiLCJub25jZSI6Im4tMFM2X1d6QTJNaiIsImNsYWltcyI6eyJzaGFyaW5nX2R1cmF0aW9uIjoiNzIwMCIsImlkX3Rva2VuIjp7ImFjciI6eyJlc3NlbnRpYWwiOnRydWUsInZhbHVlcyI6WyJ1cm46Y2RzLmF1OmNkcjozIl19fSwidXNlcmluZm8iOnsiZ2l2ZW5fbmFtZSI6bnVsbCwiZmFtaWx5X25hbWUiOm51bGx9fX0.ZNp8167aNsr_hn4tqQyOoeUbSkPqz5R1hWu_EE-uFgr7RhMHrBQM9JLXNLvwHMbkyQKZgRrer8jxJZceygJaQUerL8YMkN7886ySYlqS9DRtgAomXbfzC9Otl48BIa7sowy8b0YiSbVTnemCojX6mofIRp6WW2IImhsqxI77Jt6ELSSdGg4w0xkeupdEtrGuQoOSins9DkeDcUqFBwPSFWmMuPcRNDgWDqHztynRG0qtuopjO_ruF0ofPpzDq7GicO3gG-IRWdTakjOF3QGjVXh242m9jP745r69Xx1mrxLSGX6wbCybFJTsRereaP6Isbid6hlL-zeLl4TTjMjaIw
  3. You are directed to a login page. Log in with the credentials of a user that has a Subscriber role.

  4. If a secondary factor is required. For example, SMS OTP, provide the relevant values. Upon successful authentication, the user is redirected to the consent management page.

  5. Upon providing consent, the consumer is redirected to the callback URL of the ADR with the authorization code.


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
  1. The client_assertion is a JSON Web Token (JWT). Generate the client_assertion by signing the following JSON payload using the supported algorithms:

    {
    "alg": "<The algorithm used for signing>",
    "kid": "<The certificate fingerprint>",
    "typ": "JWT"
    }
     
    {
    "iss": "<The issuer of the token, e.g., client ID of your application>",
    "sub": "<The subject identifier of the issuer, e.g., client ID of your application>",
    "exp": "<The epoch time of the token expiration date/time>",
    "iat": "<The epoch time of the token issuance date/time>",
    "jti": "<An incremental unique value>",
    "aud": "<The audience that the ID token is intended for, e.g., https://<WSO2_OB_APIM_HOST>:8243/token>"
    }
    <signature>
    #Decoded client assertion
    
    {
      "kid": "hcgexuguVb5rYSYVBsl-c9hBPvY",
      "alg": "PS256",
      "typ": "JWT"
    }
    {
      "iss": "fSYYpF7XustLQF5Mc2shdmPCMKka",
      "sub": "fSYYpF7XustLQF5Mc2shdmPCMKka",
      "exp": 1576913134,
      "iat": 1574324479,
      "jti": "1574324489",
      "aud": "https://192.168.108.14:8243/token"
    }
    <signature>

    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:
    1. Sign in to the Identity and Access Management console at  https://localhost:9446/carbon
    2. In the Main menu, go to Home > Identity > Identity Providers > Resident.
    3. 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 .
  2. 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' -k \
      -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' \
     -k --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 API using a few samples. These requests use the access token generated in the step above .

GET /banking/accounts

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

curl -X GET \
  https://<WSO2_OB_APIM_HOST>:8243/cds-au/v1/banking/accounts/ \
  --cert <TRANSPORT_PUBLIC_KEY_FILE_PATH> --key <TRANSPORT_PRIVATE_KEY_FILE_PATH> \
  -H 'Accept: application/json'  \
  -H 'Authorization: Bearer  <USER_ACCESS_TOKEN>' \
  -H 'Cache-Control: no-cache' \
  -H 'Content-Type: application/json' \
  -H 'x-v: v1'
{
  "data": {
    "accounts": [
      {
        "accountId": "61636",
        "creationDate": "2019-05-01T15:43:00.12345Z",
        "displayName": "account_1",
        "nickname": "Alpha",
        "openStatus": "OPEN",
        "isOwned": true,
        "maskedNumber": "1234",
        "productCategory": "TRANS_AND_SAVINGS_ACCOUNTS",
        "productName": "Product name"
      }
    ]
  },
  "links": {
    "self": "https://api.alphabank.com/cds-au/v1/banking",
    "first": "https://api.alphabank.com/cds-au/v1/banking",
    "prev": "https://api.alphabank.com/cds-au/v1/banking",
    "next": "https://api.alphabank.com/cds-au/v1/banking",
    "last": "https://api.alphabank.com/cds-au/v1/banking"
  },
  "meta": {
    "totalRecords": 10,
    "totalPages": 10
  }
}

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.

curl -X POST \
  https://<WSO2_OB_APIM_HOST>:8243/cds-au/v1/banking/accounts/balances \
  --cert <TRANSPORT_PUBLIC_KEY_FILE_PATH> --key <TRANSPORT_PRIVATE_KEY_FILE_PATH> \
  -H 'Accept: application/json' -k \
  -H 'Authorization: Bearer  <USER_ACCESS_TOKEN>' \
  -H 'Cache-Control: no-cache' \
  -H 'Content-Type: application/json; charset=UTF-8' \
  -H 'x-v: v1' \
  -d '{
    "data": {
        "accountIds": [
            "30080012343456",
            "30080098763459"
        ]
    },
    "meta": {
        
    }
}'
{
  "data": {
    "balances": [
      {
        "accountId": "30080012343456",
        "currentBalance": "1234567.89",
        "availableBalance": "10234567.89",
        "creditLimit": "100234567.89",
        "amortisedLimit": "1034567.89",
        "currency": "AUD",
        "purses": [
          {
            "amount": "10.89",
            "currency": "AUD"
          }
        ]
      },
      {
        "accountId": "30080098763459",
        "currentBalance": "1234567.89",
        "availableBalance": "10234567.89",
        "creditLimit": "100234567.89",
        "amortisedLimit": "1034567.89",
        "currency": "AUD",
        "purses": [
          {
            "amount": "10.89",
            "currency": "AUD"
          }
        ]
      }
    ]
  },
  "links": {
    "self": "https://api.alphabank.com/cds-au/v1/banking",
    "first": "https://api.alphabank.com/cds-au/v1/banking",
    "prev": "https://api.alphabank.com/cds-au/v1/banking",
    "next": "https://api.alphabank.com/cds-au/v1/banking",
    "last": "https://api.alphabank.com/cds-au/v1/banking"
  },
  "meta": {
    "totalRecords": 10,
    "totalPages": 10
  }
}

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

  • No labels