Configuring Data Sharing for Nominated Representatives

This is a new requirement introduced to the Consumer Data Specification on 22 December 2020 via Competition and Consumer (Consumer Data Right) Amendment Rules (No. 3) 2020. 

Nominated Representatives

Non-individual consumers can nominate individuals as nominated representatives who can share Consumer Data Right (CDR) data and manage data sharing on their behalf. Non-individual consumers can make and revoke such nominations.

A non-individual consumer needs to nominate at least one individual as a nominated representative for CDR data to be shared on their behalf.

This page explains the following:

Enabling the business user profile

After a bank customer initiates a consent flow with an Accredited Data Recipient (ADR), they are redirected to the Data Holder’s authentication process. Upon successful authentication, the Data Holder redirects the customer to the account selection step and provides the relevant list of business bank accounts the nominated representative has the authority to share data from. 

If the particular customer’s credentials provide access to different customer accounts, you can include a profile selection step before the account selection step. The available profiles for profile selection are the business profile and the individual profile.

The profile selection can be done using one of the following 3 methods:

• Profile selection via the user interface

  This is only available as a WSO2 Update from WSO2 Open Banking Identity Server Level 2.0.0.205 onwards. For more information on updating WSO2 Open Banking, see Updating WSO2 Products.

  By default, the profile selection page is disabled. If the profile selection feature is enabled, the customer can select the profile as either business or individual. To enable the profile selection page, follow the steps below.

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

  2. Set the following value to true. By default, this configuration is set to false.

     [open_banking.profile_selection]
     enable=false

     Once the customers select the relevant profile from the profile page, they are redirected to the accounts selection page.

• Profile selection based on the user ID

  If the customer profile can be identified using the user ID, the profile selection can be done by configuring customerUtype. The value of customerUType could be either organisation or person.

  To enable the profile selection from customerUType, follow the steps below:

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

  2. Set the value of customer_u_type_based_profile_selection.enable to true.

     [open_banking.profile_selection]
     customer_u_type_based_profile_selection.enable=false

  3. The customer profile will be based on the customer details retrieval endpoint. Configure your endpoint under the [open_banking.au.customer.details.url] tag. For example:

     [open_banking.au.customer.details.url]
     url="https://<WSO2_OB_APIM_HOST>:9443/api/openbanking/backend-cds/services/customerdetails/details/{userId}"

• Profile selection based on the customerProfile cookie value

  The customer profile can be set using the customerProfile cookie, which needs to be set before the request is routed to the OBConsentServlet.

Integrating with the bank back end

The bank's back end endpoint for retrieving the user's accounts list returns a response in the following format:

Shareable accounts endpoint

{
	"account_id": "221-000 J000",
	"display_name": "Corporate Account-1",
	"accountId": "110-000 S8243",
	"accountName": "Corporate Account-1,,
	"authorizationMethod": "single",
	"nickName": "not-working",
	"customerAccountType": "Business",
	"type": "TRANS_AND_SAVINGS_ACCOUNTS",
	"isEligible": true,
	"isJointAccount": false,
	"jointAccountConsentElectionStatus": false,
	"isSecondaryAccount": false,
	"secondaryAccountPrivilegeStatus": false,
	"businessAccountInfo": {
		"AccountOwners": [{
				"memberId": "user1@wso2.com@carbon.super",
				"meta": {}
			},
			{
				"memberId": "user2@wso2.com@carbon.super",
				"meta": {}
			}
		],
		"NominatedRepresentatives": [{
				"memberId": "nominatedUser1@wso2.com@carbon.super",
				"meta": {}
			},
			{
				"memberId": "nominatedUser2@wso2.com@carbon.super",
				"meta": {}
			}
		]

	},
	"meta": {}
}

Creating database tables

Create a new table named OB_BUSINESS_STAKEHOLDER_ACCOUNT,

1. Go to the <WSO2_OB_IAM_HOME>/dbscripts/finance/ob-business-nominated-users directory.
2. Execute the relevant script according to your database type against the openbank_openbankingdb database.

Configuring the Identity Server

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

2. By default, the consent is not revoked upon the removal of the nominated representative. However, if you want to revoke the consents given by a nominated representative when the nominated representative is removed, add the following configuration and set it to true.

   [open_banking.revoke_consents_upon_nominated_representative_deletion]
   enable = true

3. Add the following configuration to add the business consent persistence step to store the business stakeholder consent details:

   [[open_banking.authorize.steps.persist.step]]
   class="com.wso2.finance.open.banking.consent.authorize.steps.impl.steps.persist.BusinessAccountConsentPersistenceStep"
   priority=7

Updating business stakeholders via endpoints

Two methods are introduced to add, update, and remove business stakeholders.

POST /au/account-access-consents/business-stakeholders

The Business Stakeholder Account Create API is invoked when creating or updating users related to business accounts.

Request

curl --location --request POST 'https://<WSO2_OB_IAM_HOME>:9446/api/openbanking/consent-mgt/au/account-access-consents/business-stakeholders' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic YWRtaW5Ad3NvMi5jb206d3NvMjEyMw==' \
--data-raw '{
   "data":[
      {
         "accountID":"300800123456",
         "accountOwners":[
            "AO1@wso2.com@carbon.super",
            "AO2@wso2.com@carbon.super"
            ],
         "nominatedRepresentatives":[
                 {
                    "name": "NR1@wso2.com@carbon.super",
                    "permission": "AUTHORIZE"
                  },
                  {
                    "name": "NR2@wso2.com@carbon.super",
                    "permission": "AUTHORIZE"
                  }
         ]
      }
   ]
}'

If the request is successful, you get a 200 OK response.

DELETE /au/account-access-consents/business-stakeholders

The Business Stakeholder Account Delete API is invoked when removing the users related to a particular business account.

Request

curl --location --request DELETE 'https://<WSO2_OB_IAM_HOME>:9446/api/openbanking/consent-mgt/au/account-access-consents/business-stakeholders' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic YWRtaW5Ad3NvMi5jb206d3NvMjEyMw==' \
--data-raw '{
    "data": [
        {
            "accountID": "30080012343456",
            
            "accountOwners":[
            "AO1@wso2.com@carbon.super",
            "AO2@wso2.com@carbon.super"
            ],
            "nominatedRepresentatives": [
                "NR1@wso2.com@carbon.super",
                "NR1@wso2.com@carbon.super"
            ]
        }
    ]
}'

If the request is successful, you get a 200 OK response.

Retrieving account consents based on the profile

GET https://<WSO2_OB_IAM_HOST>:9446/api/openbanking/consent-mgt/uk300/account-confirmation

This API provides you a list of available account consents that matches with the given search condition. A new API parameter named profile is introduced. Based on the value of profile, the API retrieves the relevant consents.

• If the value of profile is set to individual, only the consents related to the individual profile are returned.
• If the value of profile is set to business, only the consents related to the business profile are returned.

Sample CURL

curl --location --request GET 'https://localhost:9446/api/openbanking/consent-mgt/uk300/account-confirmation?clientId=Wciie5SyfpRSGhkFF_wHWpys5o0a&fromTime=2019-09-22T06:29:47+0000&limit=25&offset=0&status=revoked&toTime=2022-11-01T06:28:04+0000&userId=Admin@wso2.com@carbon.super&excludeExpiredConsents=false&profile=business' \
--header 'Accept: application/json' \
--header 'Authorization: Basic YWRtaW5Ad3NvMi5jb206d3NvMjEyMw==' \
--header 'Cache-Control: no-cache' \
--header 'Connection: Keep-Alive' \
--header 'Content-Type: application/json' \
--header 'Host: localhost:9446' \
--header 'User-Agent: Synapse-PT-HttpComponents-NIO' \
--header 'charset: utf-8' \
--header 'x-fapi-financial-id: open-bank'

Sample Response

{
  "metadata": {
    "count": 1,
    "offset": 0,
    "limit": 25,
    "total": 1
  },
  "List": [
    {
      "ConsentId": "df9ddbc9-c3d3-4fae-affe-68edecd2e5e7",
      "AccountResponseData": {
        "ConsentId": "df9ddbc9-c3d3-4fae-affe-68edecd2e5e7",
        "Status": "Revoked",
        "CreationDateTime": "2022-07-27T03:40Z",
        "Permissions": [
          "bank:accounts.basic:read",
          "bank:accounts.detail:read",
          "bank:payees:read",
          "bank:transactions:read",
          "common:customer.detail:read",
          "profile",
          "common:customer.basic:read",
          "bank:regular_payments:read",
          "given_name",
          "family_name"
        ],
        "ExpirationDateTime": "2022-07-20T12:17:53Z",
        "StatusUpdateDateTime": "2022-07-27T03:43Z"
      },
      "InitiationTimestamp": "2022-07-27T03:40:44Z",
      "Status": "Revoked",
      "ClientId": "Wciie5SyfpRSGhkFF_wHWpys5o0a",
      "UserId": "admin@wso2.com@carbon.super",
      "DebtorAccount": [
        "30080012343456",
        "30080098763459"
      ],
      "ConsentGivenTimestamp": "2022-07-27T03:40:54Z",
      "CollectionMethod": "PRIMARY",
      "JointAccountsData": [],
      "SecondaryAccountsData": [],
      "Metadata": {
        "organizationId": "Org1",
        "sharing_duration_value": "7200"
      }
    }
  ]
}

Configuring the Consent Manager dashboard

Configure the Consent Manager dashboard for business nominated users using the steps below:

The WSO2 Open Banking solution expects the banks to support the following two endpoints.

GET consent-mgt/au/account-access-consents/business-stakeholders/profiles

This API retrieves the user profiles of a bank customer.

Request

curl --request GET 'https://localhost:9446/api/openbanking/consent-mgt/au/account-access-consents/business-stakeholders/profiles?userId=admin@wso2.com' \
--header 'Authorization: Basic YWRtaW5Ad3NvMi5jb206d3NvMjEyMw==' \
--header 'Content-Type: application/json'

Response

{
   "UserId": "Admin@wso2.com@carbon.super",
   "userProfiles": [
       "individual",
       "business"
   ]
}

GET consent-mgt/au/account-access-consents/business-stakeholders/permission

This API retrieves the business account permission status of a customer for a given set of account IDs.

Request

curl --request GET 'https://localhost:9446/api/openbanking/consent-mgt/au/account-access-consents/business-stakeholders/permission?userId=admin@wso2.com&accountId=30080012343456:30080012343457' \
--header 'Authorization: Basic YWRtaW5Ad3NvMi5jb206d3NvMjEyMw==' \
--header 'Content-Type: application/json'

Response

{
   "UserId": "Admin@wso2.com@carbon.super",
   "PermissionStatus": {
       "30080012343456": "VIEW",
       "30080012343457": "VIEW"
   }
}

If a bank customer maintains both individual and business consents, the Consent Manager dashboard displays the individual consents and business consents separately in two tabs. The bank customer can select the consents related to the individual accounts and business accounts separately.

{
  "data": [
    {
      "account_id": "143-000-B1234",
      "display_name": "business_account_1",
      "accountId": "143-000-B1234",
      "accountName": "business_account_1",
      "authorizationMethod": "single",
      "nickName": "not-working",
      "customerAccountType": "Business",
      "profile": "Organization A",
      "profileId": "5678",
      "type": "TRANS_AND_SAVINGS_ACCOUNTS",
      "isEligible": true,
      "isJointAccount": false,
      "jointAccountConsentElectionStatus": false,
      "isSecondaryAccount": false,
      "businessAccountInfo": {
        "AccountOwners": [
          {
            "memberId": "user1@wso2.com@carbon.super",
            "meta": {}
          },
          {
            "memberId": "user2@wso2.com@carbon.super",
            "meta": {}
          }
        ],
        "NominatedRepresentatives": [
          {
            "memberId": "nominatedUser1@wso2.com@carbon.super",
            "meta": {}
          },
          {
            "memberId": "nominatedUser2@wso2.com@carbon.super",
            "meta": {}
          },
          {
            "memberId": "admin@wso2.com@carbon.super",
            "meta": {}
          }
        ]
      }
    }
  ]
}