How-tos

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 offers CDR quickstart that can be used as reference application to build your own CDR consent management applications and showcases how you can integrate CDR workflows with the 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 their authorization is critical in CDR.

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. As per the CX guidelines, 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. Consumer must be to view all their authorizations

  3. 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

    Read more about the consent withdrawal workflows here

Tips - Integration

Consumer Dashboard applications should have a component that must be of the confidential client type. It means that your application should be able to store client credentials securely. For example, secure Backend for Frontend (BFF) design pattern is recommended for this kind of application. 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 DH Consumer dashboard
(consent self-service portal) participant acp as DH - 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.

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

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.

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:

    • GET List CDR arrangements

    • POST List CDR arrangements

      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.

Get Tokens for User Bound Trusted System Token Pattern

Data Holders Consent Admin Portal’s client application needs to be able to get an access token using the JWT Bearer Flow (step #8 in the diagram above) when integrating with the Cloudentity platform and using the User Bound Trusted System Token Pattern. Additionally, the token the admin portal gets must include a customer_id claim that enables user authorization context to be passed across system boundaries for more effective auditing.

Access tokens the client applications get using the JWT Bearer Flow must be used by the Consent Administrator Portal to call the following Cloudentity APIs:

To get an access token using the JWT Bearer Flow and which includes the customer_id claim:

  1. In System workspace for your tenant, enable the JWT Bearer Grant Type.

    Access to the System Workspace

    Access to the System workspace is behind a feature flag. If you cannot access the System workspace and you need it, contact Cloudentity Sales Team.

  2. In System workspace, create a client application.

    For your new client application:

    1. In the OAuth tab, mark it as TRUSTED.

    2. For the Grant Type, select JWT bearer.

    3. Choose the Token Endpoint Authentication Method.

      Token Endpoint Authentication Method

      Although Cloudentity allows you to set any token endpoint authentication method of your preference, we recommend that for Consent Administrator Portal client applications you use secure methods such as, for example, OAuth 2.0 Mutual TLS Client Authentication methods.

    4. Generate a public and private keys pair and provide the public key in the JSON Web Key Set (JWKS) field.

      You can use any available algorithm type to create your keys, for example, RS256 or ES256.

    5. Save your changes.

    6. In the Scopes tab, assign the manage_openbanking_consents scope to your application.

  3. Create a JSON Web Token that includes the customer_id parameter in the token’s payload.

    The JWT will be used as the value for the assertion parameter in the JWT Bearer Grant Type client authentication. Make sure you include all mandatory claims in your token.

  4. Sign the JWT with the private key you created in the step #2.4.

  5. Make sure you add the customer_id claim to your tokens with the source type set to AuthN context and source path set to the attribute you created in your authentication context settings.

    Adding Claims with Data Lineage

    Cloudentity Data Lineage can also be used to configure token claims. The difference is that if you add the customer_id claim using the Data Lineage feature, a scope of the same name is created automatically. In this case, you need to request this scope as a part of the next step.

  6. Call the Cloudentity OAuth 2.0 token API to get an access token for your client.

    In your request to the /token endpoint:

    • Set the grant_type parameter to urn:ietf:params:oauth:grant-type:jwt-bearer

    • As the value for the assertion parameter provide the JSON Web Token you signed in the 4th step.

    • Use the client authentication method that you set for the Consent Admin Portal’s client application.

    • Request the manage_openbanking_consents scope.

    Example request:

    curl -X POST https://{tid}.us.authz.cloudentity.io/{tid}/system/oauth2/token -v \
    --header "Content-Type: application/x-www-form-urlencoded" \
    --data-raw "grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer&client_id={your-client-id}&client_secret={your-client-secret}&assertion=eyJ0eXAiOiJKV1QiLCJhbGciOiJFUzI1NiIsImtpZCI6ImQzMTk0ODM4OTc2NmU1ZTVmMGU1ZDI0OGRmZjBkNDhlIn0.eyJjdXN0b21lcl9pZCI6IjEyMzQiLCJpc3MiOiJjYXBkbDJ1c2UxMnBhZ3IwYzExMCIsInN1YiI6ImNhcGRsMnVzZTEycGFncjBjMTEwIiwiYXVkIjoiaHR0cHM6Ly9jbG91ZGVudGl0eS13a290bG93c2tpLnVzLmF1dGh6LmNsb3VkZW50aXR5LmlvL2Nsb3VkZW50aXR5LXdrb3Rsb3dza2kvc3lzdGVtL29hdXRoMi90b2tlbiIsImlhdCI6MTY1NTg5NTE0OCwiZXhwIjoxNjU1OTc0MzQ4LCJqdGkiOiIxIn0.P5INAXUyaNuXUIeKaI0pet-XRXUZDsJEM_xsKKnScCmeXZTS5iXM776jMkuD0zHVV5GFzdcB0UeYTbNFKvaXKw&scope=manage_openbanking_consents"
    
Updated: Jul 20, 2022