Versions Compared

Old Version 29

changes.mady.by.user Former user

Saved on

compared with

New Version 30

changes.mady.by.user Former user

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.
Comment: update sharing duration note

...

Table of Content Zone
maxLevel3
locationtop

Step 1 - Sign up as an Accredited Data Recipient 

In this step, the Accredited Data Recipient (ADR) registers its application in WSO2 API store.

Expand
titleClick here to see how it is done...

  1. Navigate to the API Store at https://<WSO2_OB_APIM_HOST>:9443/store.

  2. Select Sign-up on the top left corner of the homepage.

  3. Provide the requested details on the signup page.

    Expand
    titleClick here for more information..

    a. Generic details:

    Field

    Description

    Username/Email

    The username/email that the DR uses to sign in to the API Store.

    Password

    The password that the DR uses to sign in to the API Store.

    Retype Password

    This is to prevent the DR from accidentally setting an incorrect password.

    Last Name

    This is the last name of the DR.

    First Name

    This is the first name of the DR.


    b. Company details:

    Field

    Description

    Legal Entity Name

    The official name of the DR.

    Country of Registration

    The country in which the DR is registered.

    Legal Identifier Number (LEI)

    This identifies the DR.

    Company Register

    The organization that registered the DR.

    Company Registration Number

    Identifier issued at the DR registration.

    Address Line 1

    Address of the DR.

    Address Line 2

    Address of the DR.

    City

    City in which the DR is located.

    Postal Code

    Postal code of the geographical location of the DR.

    Country

    The country in which the DR is located.

    c. Competent authority registration details:

    Field

    Description

    Competent Authority

    The regulatory body that authorises and supervises the open banking services delivered by the DR.

    Competent Authority Country

    Country of the competent authority that authorised the DR to provide open banking services.

    Competent Authority Registration Number

    The registration number issued by the Competent Authority to the DR.

    URL of the Competent Authority Register Page

    URL of the page that has the list of organizations authorised by the competent authority.

  4. Read terms and conditions. Click the checkbox to agree to the terms and conditions.

  5. Click Sign Up. A request to approve the DR sign up is now sent to the Approver users.



Step 2 - Approve the ADR

Now that you have signed up as an ADR, an admin who overlooks all ADR sign-up forms must approve it. 


Note

It is not mandatory to include the approval step for approving the ADR. In order to add this step, you need to configure workflows in the WSO2 Open Banking solution.

Expand
titleClick here to see how it is done...

  1. Sign in to the WSO2 Open Banking API Manager Admin portal as an Approver at https://<WSO2_OB_APIM_HOST>:9443/admin.

  2. Locate the approval request and click Assign To Me.

  3. Click Start to start the approval process.

  4. Select Approve then Complete.

Now the DR can sign in to the API store. 

Step 3 - Sign in to the API store as the ADR

Users can sign in to the API store and proceed with the steps mentioned below.


Expand
titleClick here to see how it is done...

  1. Sign in to the API Store as the ADR at https://<WSO2_OB_APIM_HOST>:9443/store.

  2. Click Sign In and navigate to the Sign In page.

  3. Enter the username and the password you entered when signing up as an ADR.

  4. Click Sign In. 

The homepage of the API store is now displayed along with the APIs.

Step 4 - Create an application

The ADR with an application needs to create an application using WSO2 API store. The application created via WSO2 API store allows to observe statistics of APIs, subscribe to APIs, and access the subscribed APIs.
Expand
titleClick here to see how it is done...

  1. Go to the Applications tab in the API Store.

  2. Click Add Application.

  3. Enter application details.

    Field

    Description

    Name

    Application name.

    Per Token Quota

    Determines the maximum number of API requests accepted within a given duration.

    Description

    This describes the purpose of the application.

  4. Click Add. 

Note

An application can be used to subscribe to multiple APIs. See Subscribe to an API for instructions.

Step 5 - Subscribe to API

The ADR user needs to subscribe to the ConsumerDataStandards v1 API in order to access its API resources. Once subscribed, the users can access all the supported services of the API resources.


Expand
titleClick here to see how it is done...

  1. Go to the APIs tab in the API Store.

  2. Select the ConsumerDataStandards v1 API.

  3. Select the application you created in the Create an application section.

  4. Set the Tiers to Unlimited.

  5. Click Subscribe.

Now that you have subscribed to the API, generate access tokens and invoke the API.

Step 6 - Create certificates

The ADR user needs to create certificates to validate whether the ADR is registered in a governing entity.

Expand
titleClick here to see how it is done...

  1. A keystore file is used to store the trusted certificates of the ADR in the WSO2 Open Banking solution. Use the commands given below in a command-line interface in order to create a keystore file as an ADR.

    Make sure to update the following placeholders:

    <alias>A preferred alias for the keystore file.
    <filename>A preferred name for the keystore file.
    Code Block
    keytool -genkey -alias <alias> -keyalg RSA -keystore <filename>.jks

    During the command execution, the ADR user requires to;

    1. Anchor
      sourcekeystorePS
      sourcekeystorePS
      Set a password for the keystore.
    2. Provide information, acquired when registering with a governing entity.
    3. Set a password for user-defined alias (<alias>).

  2. Convert the keystore from the .jks format to .PKCS12.  Make sure to update the following placeholders:

    <keyStoreName>This is the name of the <filename>, given above.
    <PKCS12FileName>This is the name of the keystore in the .PKCS12 format.
    Code Block
    keytool -importkeystore -srckeystore <keystoreStoreName>.jks -destkeystore <PKCS12FileName>.p12 -deststoretype PKCS12

    During the command execution, the ADR user requires to;

    1. Set a password for the destination keystore.
    2. Enter the source keystore password, as defined in the above step .

  3. Create the application certificate (.pem) file in the PKCS12 format using the keystore. e.g: dr.p12.

    Make sure to update the following placeholders:

    <PKCS12FileName>This is the name of the keystore in the PKCS12 format, as mentioned above for the <PKCS12FileName>.
    <PEMFileName>This is the name of the application certificate that is created in the .pem format.
    Code Block
    openssl pkcs12 -in <PKCS12FileName>.p12 -nokeys -out <PEMFileName>.pem

    During the command execution, the ADR user requires to;

    1. Set a password to import the .pem file.

  4. Import the public key you extracted in the previous step to the truststore file.

    Update the placeholder values and use the given command.

    <alias>The alias for the keystore file.
    <PEMFileName>The name of the application certificate that is created in the .pem format.
    <truststoreFileName>The name of the truststore file that you want to import the public key.
    <password>The keystore password of the truststore file.
    Code Block
    keytool -import -alias <alias> -file <PEMFileName>.pem -keystore <truststoreFileName>.jks -storepass <password>

Step 7 - Generate keys

The ADR user requires a Client ID (Consumer Key) and a Client secret (Consumer Secret) to access the subscribed APIs.

Expand
titleClick here to see how it is done...

  1. Sign in to the API store as an ADR user and go to the Applications tab.

  2. Choose your application from the Application List and select either of the following:

    1. Production Keys: Generates access tokens in the production environment.

    2. Sandbox Keys: Generates access tokens in the sandbox environment.

  3. Provide the requested information as defined below:  

    Field

    Description

    Grant Types

    These determine the credentials that are used to generate the access token.

    • Refresh Token: This is to renew an expired access token.

    • Client Credential: This relates to the client credentials grant type and is applicable when consuming the API as an application.

    • Code: This relates to the authorisation code grant type and is applicable when consuming the API as a user.

    Callback URL

    This is the URL used by the ADR to receive the authorisation code sent from the Data Holder (bank). The authorisation code can be used later to generate an OAuth2 access token.

    Application Certificate

    This is the content between the BEGIN CERTIFICATE and END CERTIFICATE strings of the application certificate (.pem) that you created above.

  4. Click Request Access if you are generating production keys. If workflows are configured in the solution, it sends a request to Approver user to approve the token generation. Otherwise, it generates consumer key and consumer secret.

  5. Click Generate Keys if you are generating sandbox keys. It generates consumer key and consumer secret.

Step 8 - Approve Production Key generation

This step includes instructions to an Approver user to review and approve a request to generate production keys for an application.

Note

It is not mandatory to include the approval step for the Production Key generation. In order to add this step, you need to configure workflows in the WSO2 Open Banking solution.

Expand
titleClick here to see how it is done...

  1. Sign in to the WSO2 Open Banking API Manager Admin portal as an Approver at https://<WSO2_OB_APIM_HOST>:9443/admin.

  2. Click Tasks and then Application Registration.

  3. Locate the approval request and click Assign To Me.

  4. Click Start to start the approval process.
  5. Select Approve and then click Complete.
  6. Navigate back to the API Store and click Applications.
  7. On the Applications tab in the API Store, click View of the application that you created.
  8. Select the Production Keys or Sandbox Keys tab to find the generated keys.
    The consumer key and consumer secret are displayed as follows:

Step 9 - Authorising account consents

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

Expand
titleClick here to see how it is done

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

    Note

    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:

      Code Block
      languagexml
      <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>
    Tip

    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.

    Note

    The refresh token is used to regenerate an access token. The  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.

    Localtabgroup
    Localtab
    titleRequest object format
    Code Block
    ## 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>
    Localtab
    titleRequest object sample
    Code Block
    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:

    Localtabgroup
    Localtab
    titleFormat
    Code Block
    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>
    Localtab
    titleSample
    Code Block
    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 10 - Generate user access token

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

Expand
titleClick 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:

    Localtabgroup
    Localtab
    titleclient_assertion format
    Code Block
    {
"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>
    Localtab
    titlesample client_assertion (decoded)
    Code Block
    languagejs
    #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>
    Note

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

    Expand
    titleClick 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.

    Code Block
    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:

    Code Block
    {
   "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
}
    Note
    Multiexcerpt
    MultiExcerptNamerefresh_token

    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:

Step 11 - 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.

Localtabgroup
Localtab
titleRequest
Code Block
curl -X GET \
  https://<WSO2_OB_APIM_HOST>:8243/cds-au/v1/banking/accounts/ \
  -H 'Accept: application/json' -k \
  -H 'Authorization: Bearer  <USER_ACCESS_TOKEN>' \
  -H 'Cache-Control: no-cache' \
  -H 'Content-Type: application/json' \
  -H 'x-v: v1'
Localtab
titleResponse
Code Block
{
  "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.

Localtabgroup
Localtab
titleRequest
Code Block
curl -X POST \
  https://<WSO2_OB_APIM_HOST>:8243/cds-au/v1/banking/accounts/balances \
  -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": {
        
    }
}'
Localtab
titleResponse
Code Block
{
  "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
  }
}
Tip

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