Customising the Consent Page of the Authorise Flow

Customise the theme of the consent page

Given below is the default Consent page of WSO2 Open Banking. 

If an ASPSP wishes to customise the theme of the existing consent page, they can modify the files in the following directories:

Customise the layout of the consent page

The authentication endpoint in WSO2 Open Banking allows the ASPSP to customise the layout of the consent page. The consent page is designed in a servelet that consists of three main JSP pages as shown in the diagram below:

Users can also make changes to the relevant JSP pages and customise according to the requirement. In order to customise the layout of the authentication endpoint, locate the JSP pages in the following locations:

Customise the consent page to display the bank-specific information

Currently, the consent page displays specification-specific information. But there are scenarios where ASPSPs need displaying additional information, e.g., payment-charges or information of the PSU/TPP on the consent page. In that case, the user must follow the steps that are given below.

1. In order to invoke the bank API, add com.wso2.finance.open.banking.consent.authorize.steps-<version>.jar file as a dependency.

2. Extend the ConsentRetrievalStep class and implement the execute method as follows.

   /**
   * Method to be implemented as a step for consent retrieval. Once implemented add the step to the deployment.toml
   * configuration.
   *
   * @param consentData Includes all the data that is received to the consent page.
   * @param jsonObject Passed on through each step where the response body sent to the page is built.
   * @return boolean representing whether the step was executed successfully. If this is false, the remaining steps
   * will continue to execute after a warning log.
   */
   boolean execute(ConsentData consentData, JSONObject jsonObject);

• In the latest authentication endpoint, users can add customisations to the JSONObject directly.
  • Add the relevant configurations to invoke the API exposed by the Bank to display the additional information under <execute> method.
  • Add the data that needs to be displayed on the consent page in the JSONObject.

• A sample JSONObject looks as follows:

  {
     "application":"tpp-AT-gold.com_tppApp1_PRODUCTION",
     "user_id":"VVixWOdBGNFD8YJm2nHCrkCGJhka",
     "transactionData":{
        "reauthSelectedAccount":[
           
        ],
        "isReauthAccountUpdateEnabled":false,
        "isError":"false",
        "Permissions":[
           "ReadAccountsDetail",
           "ReadBalances",
           "ReadBeneficiariesDetail",
           "ReadDirectDebits",
           "ReadProducts",
           "ReadStandingOrdersDetail",
           "ReadTransactionsCredits",
           "ReadTransactionsDebits",
           "ReadTransactionsDetail",
           "ReadScheduledPaymentsDetail",
           "ReadStatementsDetail",
           "ReadOffers",
           "ReadParty"
        ],
        "isReauthorization":false,
        "dates":[
           "Expiration Date Time : 2019-09-02T00:00:00Z",
           "Transaction From Date Time : 2018-03-05T14:36Z",
           "Transaction To Date Time : 2018-07-02T00:00:00Z"
        ],
        "consent_id":"397e5e62-ee07-4b25-8275-5e451991701f",
        "client_id":"VVixWOdBGNFD8YJm2nHCrkCGJhka"
     },
     "accounts":[
        {
           "account_id":"30080012343456",
           "authorizationMethod":"single",
           "display_name":"30080012343456"
        },
        {
           "account_id":"30080098763459",
           "authorizationMethod":"single",
           "display_name":"30080098763459"
        }
     ],
     "authorizationUsers":[
        {
           "user_id":"psu1@wso2.com@carbon.super",
           "customer_id":"123"
        },
        {
           "user_id":"psu2@wso2.com@carbon.super",
           "customer_id":"456"
        }
     ],
     "type":"accounts",
     "region":"UK",
     "consent_id":"397e5e62-ee07-4b25-8275-5e451991701f",
     "client_id":"VVixWOdBGNFD8YJm2nHCrkCGJhka"
  }

3. Include the jar file of the extended class to the <WSO2_OB_IAM_HOME>/repository/components/lib directory.
4. Configure the deployment.toml file as follows:
   1. Open the <WSO2_OB_IAM_HOME>/repository/conf/deployment.toml file.

   2. Add the extended implementations to the file. Make sure to add the default classes as given below and set the priority according to the order of the steps that must be executed. For example:

      [[open_banking.authorize.steps.retrieve.step]]
      class="com.wso2.finance.open.banking.consent.authorize.steps.impl.steps.retrieval.OBConsentRetrievalStep"
      priority=1
      
      [[open_banking.authorize.steps.retrieve.step]]
      class="com.wso2.finance.open.banking.consent.authorize.steps.impl.steps.retrieval.AccountListRetrievalStep"
      priority=2
      
      [[open_banking.authorize.steps.retrieve.step]]
      class="com.wso2.finance.open.banking.consent.authorize.steps.impl.steps.retrieval.OBReportingRetrievalStep"
      priority=3
      
      [[open_banking.authorize.steps.retrieve.step]]
      class="com.wso2.finance.open.banking.consent.authorize.steps.impl.steps.retrieval.berlin.AuthorisationInfoRetrievalStep"
      priority=4
      
      [[open_banking.authorize.steps.retrieve.step]]
      class="SampleClass"
      priority=5

5. Now that the ASPSP needs to configure the information that displays on the consent page, the user must customise the body of the relevant JSP page. See Customise the layout of the consent page find out how it is done.
6. Restart the WSO2 Open Banking Identity and Access Management server.

Customise the consent page to persist bank-specific information

Currently, WSO2 Open Banking persists the data that is displayed on the consent page by default. If the ASPSP displays additional information on the consent page, that additional information can be persisted or validated as per the requirement. According to the above example where the ASPSP displays payment charges or information of the PSU/TPP, the user can persist or validate any of this additional information. See the below steps to find how it can be done:

1. In order to invoke the bank API, add the com.wso2.finance.open.banking.consent.authorize.steps-<version>.jar file as a dependency.

2. Extend the ConsentPersistStep class and implement the execute method as follows.

   /**
   Method to be implemented as a step for consent persistence. Once implemented add the step to the deployment.toml
   * configuration.
   *
   * @param consentPersistData Includes all the generic data of the consents.
   * @param metadata Contains the consent DTO object and other data which can be passed down through steps.
   * @return boolean representing whether the step was executed successfully. If this is false, the remaining steps
   * will not execute and an error will be shown in the consent page with warning log.
   */
   boolean execute(ConsentPersistData consentPersistData, Map<String, Object> metadata);

   
   

   • The data that needs to be persisted from the consent page should be included in the metadata map.
   • Under the <execute> method, pass the metadata and invokes the API that is exposed by the bank to persist or validate this information.
3. Configure the deployment.toml file as follows:
   1. Open the <WSO2_OB_IAM_HOME>/repository/conf/deployment.toml file.

   2. Add the extended implementations to the file. Make sure to add the step and set a priority before the PSU consent (approval or denial) is persisted. See the sample below:

      According to the below sample code, the UserConsentPersistenceStep step is given the third priority. In this step, consent (approval or denial) given by the PSU on the consent page is persisted. Therefore, users require to add new implementations set a priority according to the order of steps that must be executed. If a new implementation requires not to persist the user consent, see Block consent-persistence.

      [[open_banking.authorize.steps.persist.step]]
      class="com.wso2.finance.open.banking.consent.authorize.steps.impl.steps.persist.MultipleAuthPersistenceStep"
      priority=1
      
      [[open_banking.authorize.steps.persist.step]]
      class="com.wso2.finance.open.banking.consent.authorize.steps.impl.steps.persist.berlin.AuthorisationInfoPersistenceStep"
      priority=2
      
      [[open_banking.authorize.steps.persist.step]]
      class="com.wso2.finance.open.banking.consent.authorize.steps.impl.steps.persist.UserConsentPersistenceStep"
      priority=3
      
      [[open_banking.authorize.steps.persist.step]]
      class="com.wso2.finance.open.banking.consent.authorize.steps.impl.steps.persist.OBReportingPersistenceStep"
      priority=4
      
      [[open_banking.authorize.steps.persist.step]]
      class="SampleClass"
      priority=5

4. Include the jar file of the extended class to the <WSO2_OB_IAM_HOME>/repository/components/lib directory.

5. Restart the WSO2 Open Banking Identity and Access Management server.

Block consent-persistence

In WSO2 Open Banking, by default, the consent (approval or denial) given by the PSU is persisted. Imagine a new implementation added by extending the ConsentPersistStep class to validate information displayed on the consent page. Based on that validation, the ASPSP wants to block persisting the PSU consent. In that case, this is how it is done:

• In the extended class of the ConsentPersistStep class, the metadata map consists of the shouldAddUserConsent property.
  • Set the shouldAddUserConsent property as false to block consent-persistence. Thereby, the PSU consent is not persisted. By default, the value is set as true.

Integrate the bank's consent page

A REST API is introduced in the latest version of the authentication endpoint for banks who wish to integrate a consent page of their own. There are main functions that this REST API performs:

• Displays information on the consent page
• Captures the data on the consent page and persists them

For more information on this API and its endpoints, see Authorize API.

There are two API resources that perform the above-mentioned functions as below:

• GET /consent/data/{session-data-key}

An interface of the retrieval endpoint makes an HTTP GET call to the REST API to retrieve consent data and bank backend to retrieve account data. In that case, the consent page invokes the GET /consent/data/{session-data-key} endpoint.

The users can also add additional information on the consent page. See Customise the consent page to display the bank-specific information to find how it is done.

• PATCH /authorize/{consent-id}

The users can capture the information on the consent page and persist them. In that case, the consent page invokes the PATCH /authorize/{consent-id} endpoint. By default, account and consent information is persisted.

If the user requires to persist additional information on the consent page, see Customise the consent page to persist bank-specific information.

See the diagram below to find how the API calls are made. Authentication Web App is the component that a user must replace with the bank's consent page.

Follow the below steps to integrate the bank's consent page :

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

2. Update the URLs for OAuth2 and OIDC consent pages:

   By default, values are set to the consent page that WSO2 Open Banking supports.

   [oauth.endpoints]
   oauth2_consent_page = "${carbon.protocol}://<WSO2_OB_IAM_HOST>:${carbon.management.port}/ob/authenticationendpoint/oauth2_authz.do"
   oidc_consent_page = "${carbon.protocol}://<WSO2_OB_IAM_HOST>:${carbon.management.port}/ob/authenticationendpoint/oauth2_consent.do"

Customise Account Retrieval 

In some banks, some PSUs may have a certain number of accounts, but not all accounts have the ability to be shared externally or to make a payment online. In a bank, the shareable account list and the payable account list can either be the same or different.

In the default WSO2 Open Banking solution, at least two APIs are expected to return shareable and payable accounts when passing the user_id, and the given JSON response must be returned. Then it automatically loads the accounts list in the consent page. 

Payable Accounts API

The back end endpoint for the Payable Accounts API is used to get the payable accounts of the user during the authentication flow. If Third Party Application (TPP) has not provided any debtor account in payment initiation request, PSU is able to select one of these payable accounts when providing the consent to the payment. If the TPP has sent the debtor account in the initiation request, this API is used to validate the provided account against actual payable accounts. consentId and userId (PSU ID) requires to be sent in the URL as query parameters when calling this API.

The back end endpoint for payable accounts retrieval can be configured in the open-banking.xml file as below. By default, mock backend deployed in the API Manager is configured.

<PayableAccountsRetriveEndpoint>http://<WSO2_OB_APIM_HOST>:9763/open-banking/services/bankaccounts/bankaccountservice/payable-accounts</PayableAccountsRetriveEndpoint>

<PayableAccountsRetriveEndpoint>http://<WSO2_OB_APIM_HOST>:9443/as400/payable-accounts/{userId}</PayableAccountsRetriveEndpoint>

{
 "data": [{
	"account_id": "30080098971337",
	"display_name": "account 1",
	"authorizationMethod": "single",
}
	{
		"account_id": "30080098971337",
		"display_name": "30080098971337",
		"authorizationMethod": "multiple",
		"authorizationUsers": [{
		"customer_id": "123",
		"user_id": "psu1@wso2.com@carbon.super"
    },
    	{
			"customer_id": "456",
			"user_id": "psu2@wso2.com@carbon.super"
    	}
   ]
  }
 ]
}

<SharableAccountsRetriveEndpoint>http://<WSO2_OB_APIM_HOST>:9763/open-banking/services/bankaccounts/bankaccountservice/sharable-accounts</SharableAccountsRetriveEndpoint>

<SharableAccountsRetriveEndpoint>http://<WSO2_OB_APIM_HOST>:9443/as400/sharable-accounts/{userId}</SharableAccountsRetriveEndpoint>