We launched new developer portal. For the latest documentation visit developer.cloudentity.com
Home > Guides > Open Banking > CDR consumer dashboards

Building CDR Consumer Consent Dashboards

Learn how to build CDR-compliant consumer consent self-service portals, and consent administrator portals utilizing built-in consent APIs provided by Cloudentity .

Sandbox

Cloudentity delivers a reference Open Banking Quickstart GitHub project that can be used as reference application to build your own consent management applications and how you can integrate with Cloudentity platform. Additionally, if you need guidance on how to use reference portals, see Using reference consent self-service and admin portals article.

Consumer dashboards

Consent in the CDR must be voluntary, express, informed, specific as to purpose, time limited and easily withdrawn (rule 4.9). Allowing consumers to be able to manage theirs authorisation is very critical.

Consumer dashboards or consent self-service portals are the tools that consumers can use to review and manage their authorizations (consents). They allow the consumer to see a list of all CDR data recipients the consumer is sharing data with and the specific sharing arrangements the consumer has with the data recipients.

The consumer will have a possibility to withdraw (revoke) their consent at any given moment. Dashboards must provide consumers with information on, for example, when the consumer gave their authorization, the period for which the consumer gave their authorization, when the authorization is scheduled to expire, or if the authorization is expired/active and when it expired.

Requirements

  1. Consumer dashboards must be developed according to the CDR CX Guidelines and Rules

  2. The consumers must be able to withdraw their authorization. The withdrawal journey contains, for example:

    • Identifying the authorization to be withdrawn

    • Reviewing the implications and confirming the withdrawal

    • Receiving a final notification of success

  3. Consumer Dashboard applications must be of the confidential client type. It means that your application should be able to store client credentials securely. Such credentials are used in the client credentials OAuth grant flow.

Integrate consumer dashboards

[mermaid-begin]
sequenceDiagram autoNumber participant user as Consumer participant IDP participant cd as Data Holder Consumer dashboard (consent self-service portal) participant acp as Data Holder - Infosec provider (Cloudentity) user->>IDP: Authenticate user->>cd: Consumer is redirected cd->>acp: Request to /system/oauth2/token with `client credentials` grant type & `manage_openbanking_consents` scope acp->>cd: Cloudentity Access token with `manage_openbanking_consents` scope cd->>acp: List CDR arrangements with `customer_id` in request body POST /cdr/arrangements Note over cd, acp: The request contains the token the Consumer Dashboard got in the 4th step acp->>cd: List of arrangements for the user cd->>user: Display arrangements user->>cd: Select arrangement cd->>acp: GET /cdr/arrangements/{arrangementID} Note over cd, acp: The request may contain the same token Consumer Dashboard
got in the 4th step if it is still valid.
If it is not, the dashboard must again authenticate itself. acp->>cd: Arrangement of the requested identifier cd->>user: Display arrangement details user->>cd: Select revoke (withdraw) arrangement cd->>acp: DELETE /cdr/arrangements/{arrangementID} Note over cd, acp: The request may contain the same token Consumer Dashboard
got in the 4th step if it is still valid.
If it is not, the dashboard must again authenticate itself.

To integrate your Consumer Dashboard with Cloudentity, the following Cloudentity APIs need to be utilized as depicted in the above sequence diagram:

  • OAuth 2.0 token endpoint

    You need to be able to authenticate your Consumer Dashboard to Cloudentity when making your API requests. The client application that you create in Cloudentity platform must be created within the System workspace for your tenant (as you will be using System level APIs) and have the manage_openbanking_consents scope assigned.

    In the diagram above, you can see that the consent application makes requests to the /token endpoint for one purpose: when authenticating itself to make requests to Cloudentity consent APIs (in the 3rd step and, optionally, before the 9th or 13th step)

    Tip

    When requesting tokens, it is a good practice to explicitly define the scopes you need. It is recommended that you limit the scope of your token by explicitly providing the manage_openbanking_consents as the value of the scope parameter.

  • Cloudentity List APIs:

    You can use both APIs to fetch a list of CDR arrangements. Such list can be narrowed using filters provided in the request parameters (for the GET request) or in the request body (for the POST request). This API enables you to provide the consumer with a list of all of their consents, which is required by the CDR rules. You can see that, in the diagram, a GET List CDR arrangements endpoint is used in the 5th step.

  • Get CDR arrangement by ID

    Once the consumer is presented with a list of their consents and they select a specific arrangement, you can call Cloudentity Get CDR arrangement by ID API to get the consent of a speficic identifier. This allows you to get the details of a specific arrangement and display them to the consumer. In the diagram, you can see that this API is used in the 9th step.

  • Revoke CDR arrangement

    As Consumer Dashboards are required to provide a possibility to revoke (withdraw) consents, you can use this Cloudentity API to revoke a single CDR arrangement with a matching arrangement identifier. In the diagram, you can see that this API is used in the 13th step.

IDPs

In the diagram you can also see the IDP participant. When the consumer wants to access the Consumer Dashboard (consent self-service portal), they must authenticate themself with an Identity Provider. You can use Cloudentity platform to manage IDPs and provide your consumers with a means of authentication.

Consent administrator portals are tools that Data Holders' administrators can use to manage the arrangements on behalf of the consumers. Administrators can view the consents for a given account, see the details of an arrangement, and if needed they can withdraw the arrangement on behalf of the consumer.

Additionally, administrators can view all data recipients that the consumer authorized at any point. If needed, the administrator can revoke all arrangements issued to all users and tied to the specified data recipient.

Requirements

  • Consent management portal applications must be of the confidential client type. It means that your application must be able to store client credentials securely. Such credentials are used in the client credentials OAuth grant flow.

  • After authentication, either the administrative application should automatically provide account numbers for a consumer by integrating with the underlying data API or a provision to provide account number as an input to the Cloudentity APIs.

Data holders can pick one of the below integration patterns based on the application architecture and security required within the CDR ecosystem.

Trusted system token pattern

This pattern is recommended when there is a tight integration of all actors and is easy to implement.

[mermaid-begin]
sequenceDiagram autoNumber participant user as Administrator participant IDP participant cap as Data Holder consent Admin Portal participant acp as Data Holder - Infosec provider (Cloudentity) user->>IDP: Authenticate user->>cap: Admin is redirected, provides `customer_id` cap->>acp: Request to /system/oauth2/token with `client credentials` grant type & `manage_openbanking_consents` scope acp->>cap:Cloudentity Access token with `manage_openbanking_consents` scope alt Admin wants to revoke single consent cap->>acp: List CDR arrangements with `customer_id` in request body POST /cdr/arrangements Note over cap, acp: The request contains the token the admin portal got in the 4th step acp->>cap: List of arrangements for the `customer_id` cap->>user: Display arrangements user->>cap: Select arrangement cap->>acp: GET /cdr/arrangements/{arrangementID} Note over cap, acp: The request may contain the same token admin portal
got in the 4th step if it is still valid.
If it is not, the portal must again authenticate itself. acp->>cap: Arrangement of the requested identifier cap->>user: Display arrangement details user->>cap: Select revoke (withdraw) arrangement cap->>acp: DELETE /cdr/arrangements/{arrangementID} Note over cap, acp: The request may contain the same token the admin portal
got in the 4th step if it is still valid.
If it is not, the portal must again authenticate itself. end alt Admin wants to revoke all consents for given data recipient user->>cap: Admin accesses the view with Data Recipients cap->>acp: GET /clients/{wid} Note over cap, acp: The request may contain the same token the admin portal
got in the 4th step if it is still valid.
If it is not, the portal must again authenticate itself. acp->>cap: List of Data Recipients applications connected to the CDR workspace cap->>user: Display list of Data Recipients user->>cap: Select revoke (withdraw) for Data Recipient cap->>acp: DELETE /cdr/arrangements?client_id={client_ID} Note over cap, acp: The request may contain the same token the admin portal
got in the 4th step if it is still valid.
If it is not, the portal must again authenticate itself. end

User bound trusted system token pattern

This pattern is recommended when there is a requirement to pass on a user authorization context across system boundaries for more effective auditing. This might require more advanced integration effort compared to the cohesive sytem pattern but ensures there is an oppurtunity for user context to be transferred across system actors and boundaries.

[mermaid-begin]
sequenceDiagram Title: CDR Consent Management Admin Portal autoNumber participant user as Administrator participant IDP participant cap as Data Holder -
Consent Admin Portal participant dhapigw as Data Holder -
API GW participant acp as Data Holder -
Infosec provider
(Cloudentity) user->>IDP: Authenticate IDP->>IDP: Finish authentication user->>cap: Admin is redirected to consent management portal cap->>cap: Collect customerId for information lookup cap->>cap: Authorize admin to lookup
customer information cap->>cap: Create Cloudentity
JWT Bearer request Note right of cap: This JWT assertion should have the customerId
as subject `sub` and admin as act sub to indicate
delegation flow Note right of cap: "{ "aud":"https://cdr-demo.cloudentity.com/cdr-demo/cdr",
"sub":"admin@example.com",
"customer_id": "user@example.com" }" cap->>acp: Request to /system/oauth2/token with jwt bearer grant type
and scope `manage_openbanking_consents` acp->>cap: Cloudentity Access token alt API direct to Cloudentity cap->>acp: POST /cdr/customer-arrangements
Bearer jwt-bearer token Note right of cap: The request contains the token the admin portal
got in the 8th step acp->>acp: Validate token acp->>acp: Retrieves the `customer_id` claim from the
incoming access token acp->>dhapigw: List of arrangements dhapigw->>cap: List of arrangements end alt API proxied by DH gateway cap->>dhapigw: GET /cdr/arrangements
Bearer [Cloudentity accessToken] Note right of cap: The request contains the token the admin portal
got in the 8th step dhapigw->>dhapigw: Introspect Cloudentity token dhapigw->>acp: GET /cdr/arrangements acp->>acp: Validate token acp->>acp: Retrieves the sub from the
incoming access token acp->>dhapigw: List of arrangements dhapigw->>cap: List of arrangements end

To integrate your Consumer Dashboard with Cloudentity, use the following APIs:

  • OAuth 2.0 token endpoint

    You need to be able to authenticate your Consent Admin Portal to Cloudentity when making your API requests. The client application that you create in Cloudentity platform must be created within the System workspace for your tenant (as you will be using System level APIs) and have the manage_openbanking_consents scope assigned.

    In the diagram above, you can see that the consent application makes requests to the /token endpoint for one purpose: when authenticating itself to make requests to Cloudentity consent APIs (in the 4th step and, optionally, before the 9th, 13th, 15th, and 19th steps)

    Tip

    When requesting tokens, it is a good practice to explicitly define the scopes you need. It is recommended that you limit the scope of your token by explicitly providing the manage_openbanking_consents as the value of the scope parameter.

  • Cloudentity List APIs:

    You can use both APIs to fetch a list of CDR arrangements. Such list can be narrowed using filters provided in the request parameters (for the GET request) or in the request body (for the POST request). This API enables you to provide the administrators with a list of all consents for given account numbers. You can see that, in the diagram, a GET List CDR arrangements endpoint is used in the 5th step.

    • List clients by authorization server

      You can use this API to fetch all client applications (in this case, client applications from Data Recipients) registered within your CDR-compliant workspace in Cloudentity platform. You can see this API being used in the 15th step of the diagram above in the scenario where an administrator wants to revoke all consents for given Data Recipient software.

  • Get CDR arrangement by ID

    Once the consumer is presented with a list of their consents and they select a specific arrangement, you can call Cloudentity Get CDR arrangement by ID API to get the consent of a speficic identifier. This allows you to get the details of a specific arrangement and display them to the consumer. In the diagram, you can see that this API is used in the 9th step.

  • Revoke CDR arrangement

    To provide your administrators with a possibility to revoke a specific arrangement, you need to call this API with the arrangement identifier provided as the path parameter. You can see this API being used in the 13th step of the diagram above.

  • Revoke CDR arrangements

    Once you fetch the list of all client recipient’s registered within your CDR workspace, this endpoint can be used to revoke all CDR arrangements for the specified Data Recipient’s client application. You can see it used in the 19th step of the diagram above.