Integrating the custom consent page with ACP

Instructions on how to integrate the custom consent page with ACP

Overview

Before you start, have a look at the flow overview.

flow

Prerequisites

  1. Enable the custom consent page and add the consent URL in your workspace settings in the ACP portal.

    More information

    See Enabling the custom consent page in ACP for information on how to set up your workspace to use the custom consent page.

  2. In the system workspace, create an application that

    • Uses the client credentials flow to authorize to internal APIs of ACP.

    • Has the openbanking_manage_consents scope assigned.

    Note

    It’s recommended to use mTLS as a token authentication method.

Integration flow

  1. When the user gets authenticated, ACP redirects them to a custom consent page.

    Location: 302
    https://bank.com/consent_page?login_id=43579ea6860f6&login_state=29n93
    
  2. The custom consent page calls ACP to acquire details on the access consent of the requested account.

    curl "https://authorization.cloudentity.com:8443/api/system/default/open-banking/account-access-consent/43579ea6860f6" \
      -H "Authorization: Bearer PUT-CLIENT-CREDENTIALS-ACCESS-TOKEN-HERE"
    
    {
      "consent_id":"bumh9la8sbs8k5btpqmg",
      "creation_date_time":"2020-11-11T10:56:21.087Z",
      "creation_date_time":"2020-11-12T10:56:21.087Z",
      "permissions":[
        "ReadAccountsBasic"
      ],
      "requested_scopes":[
        {
          "authorization_server_id":"openbanking",
          "description":"This scope value requests access to the sub claim which uniquely identifies the user.",
          "display_name":"OpenID",
          "id":"bugkg8q3g9kregtu04ng",
          "name":"openid",
          "params":[
    
          ],
          "requested_name":"openid",
          "tenant_id":"default",
          "with_service":true,
          "service":{
            "audience":"spiffe://localhost/default/openbanking/bugkg8q3g9kregtu04l0",
            "authorization_server_id":"openbanking",
            "id":"bugkg8q3g9kregtu04l0",
            "name":"Profile",
            "system":true,
            "tenant_id":"default"
          }
        },
        {
          "authorization_server_id":"openbanking",
          "description":"Ability to read Accounts information",
          "display_name":"Accounts",
          "id":"bugkg8q3g9kregtu04tg",
          "name":"accounts",
          "params":[],
          "requested_name":"accounts",
          "tenant_id":"default",
          "with_service":true,
          "service":{
            "audience":"spiffe://localhost/default/openbanking/bugkg8q3g9kregtu04t0",
            "authorization_server_id":"openbanking",
            "id":"bugkg8q3g9kregtu04t0",
            "name":"Openbanking",
            "system":true,
            "tenant_id":"default"
          }
        }
      ],
      "status":"AwaitingAuthorisation",
      "status_update_date_time":"2020-11-12T11:56:21.087Z",
      "subject":"user",
      "transaction_from_date_time":"2020-11-11T10:43:39.398Z",
      "transaction_to_date_time":"2020-11-12T10:43:39.398Z"
    }
    

    The consent page displays:

    • List of accounts that belong to the user, which is bank-specific and, hence, excluded from this article.
    • List of permissions.
  3. The consent page calls ACP to approve or deny the account access consent and redirects the user to the returned redirect URL.

    More information on the consent page

    The consent page needs to pass login_state from query parameters to the body of the accept account consent request and use login_id from query parameters as login_id in the path to the accept account access consent request.

    The consent page is to provide

    • Account IDs that the user agrees to share. They are available as account_ids in the body of the accept account access consent request.

    • Scopes to be granted. The list of requested scopes is available in the get account access consent response body. They are available as granted_scopes in the body of the accept account access consent request.

    curl -X POST "https://authorization.cloudentity.com:8443/api/system/default/open-banking/account-access-consent/43579ea6860f6/accept" \
      -d '{ "login_state": "29n93", account_ids": ["1234", "5678"], "granted_scopes": ["openid", "accounts"]}' \
      -H "Authorization: Bearer PUT-CLIENT-CREDENTIALS-ACCESS-TOKEN-HERE"
    
    > {"redirect_to": "https://authorization.cloudentity.com:8443/default/default/oauth2/authorize?..."}
    

APIs

There are three system APIs provided by ACP that can be used for the consent page integration:

  • GET /api/system/{tenant_id}/open-banking/account-access-consent/{login_id} for getting the account access consent
  • POST /api/system/{tenant_id}/open-banking/account-access-consent/{login_id}/accept for accepting the account access consent
  • POST /api/system/{tenant_id}/open-banking/account-access-consent/{login_id}/reject for rejecting the account access consent

Note

login_id is provided as a query parameter when the user gets redirected to the consent page.

Learn more

See APIs for more information.

Result

You have successfully integrated your custom consent page with ACP.