Building CDR-compliant consent apps and portals

Learn how to build CDR-compliant consent applications, consent self-service portals, and consent administrator portals. Check how to integrate with Cloudentity using its built-in consent APIs.

Sandbox

Cloudentity delivers a reference Open Banking Quickstart GitHub project that you can use when creating your applications for a better understanding of how the flow works 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.

The Open Banking Quickstart project simulates an open banking ecosystem that consists data recipient’s fintech application (Financroo) and financial institution (Go Bank). Go Bank exposes OB Data APIs and utilizes Cloudentity for user consent, authorization, enable access to APIs to fintech applications. The quickstart lets emulate read and read-write open banking scenarios that show how Cloudentity supports these flows. In particular, it lets understand the concept of sample consent application that renders custom fine-grained consent page that becomes part of the OAuth flow. There is a possibility to customize the CSS design of the Openbanking Quickstart environment. You can also modify .go templates for more advanced use-cases. Both of the solutions, however, have its limits.

To have full control over your custom consent page and to be able to tailor it to match your needs you can implement your own consent page. It can be, later on, integrated and enabled within Cloudentity. What technology you use to implement custom consent pages is totally up to you, but to be CDR compliant, your custom consent application has to fulfill certain requirements.

User consent is one of the pillars of Consumer Data Right. According to the CDR UX guidelines, consent must be fine-grained and allow for the account selection. At the same time, the consent request must comply with OAuth flows. Cloudentity’s concept of custom consent application is a tool to achieve that. It gives Data Holders freedom of customization and flexibility for consent page integration according to their needs.

When the consumer gets redirected, Data Holder’s custom consent page receives the following parameters needed later on:

Parameter Description
login_id The identifier of the user’s session.
login_state Used to mitigate Cross-site request forgery (CSRF) attacks.
cdr_arrangement_id The CDR Arrangement ID is a unique string representing a consent arrangement between a Data Recipient Software Product and Data Holder for a given consumer.
consent_type Type of the consent. For CDR, the value of the consent_type parameter is set to cdr_arrangement

Requirements

  1. Consent applications must follow the Consumer Data Standard CX Guidelines.

  2. Consent page applications must be of the confidential client type. It means custom consent application must be able to store client credentials securely. Such credentials are used in the client credentials OAuth grant flow.

    Remember

    Custom consent page is also going to make calls to Data Holder’s internal APIs, for example, to retrieve consumers' accounts. Such requests may contain your consumer’s personal data.

    When the third-party provider’s application gets authorized, as the result of the users authentication, consent pages may receive your consumer’s identity (authentication) context. Such request can consist of sensitive data and, because of that, full confidentiality of your consent page application is a must.

  3. Consent pages should be able to make requests to your bank’s internal APIs to fetch all data that is needed for the authenticated consumer to consciously make a consent decision.

    Example

    Your consent page should be able to call appropriate data APIs to fetch the list of your consumers' accounts and display them in the UI.

  4. When the consumer accepts/rejects the consent, the consent application should redirect the user to the Cloudentity specific URL it received as the response to the accept/reject arrangement API calls in the redirect_to field to complete the consent capture workflow in the Cloudentity system.

[mermaid-begin]
sequenceDiagram autoNumber participant user as Consumer participant dr as Data Recipient participant cApp as Consent application participant acp as Data Holder - Infosec provider (Cloudentity) participant dh as Data Holder user->>dr: Access software dr->>acp: /authorize acp->>cApp: Redirects user with cdr_arrangement_id & logind_id cApp->>acp: /token with client credentials grant type Note over cApp, acp: This token is going to be used in API calls to Cloudentity acp->>cApp: Access token Note over acp, cApp: The access token contains the manage_openbanking_consents scope cApp->>acp: GET /cdr/cdr-arrangement/{login} Note over cApp, acp: The request contains the access token
the consent application got in the 5th step cApp->>acp: /token with client credentials grant type acp->>cApp: Access token Note over cApp, acp: This token is going to be used in requests to
Data Holder's Open Banking APIs cApp->>dh: Retrieve consumer's accounts Note over cApp, dh: The request contains the access token
the consent application got in the 8th step user->>cApp: Accept/reject consent in consent app's UI alt User rejected cApp->>acp: POST /cdr/cdr-arrangement/{login}/reject with token Note over cApp, acp: The request may contain the same token consent application
got in the 5th step if it is still valid.
If it is not, consent application must again authenticate itself. acp->>cApp: redirect_uri (used for redirecting user back to Data Recipient client app) cApp->>user: Redirects the consumer back to the Data Recipient's software else User accepted cApp->>acp: POST /cdr/cdr-arrangement/{login}/accept with token Note over cApp, acp: The request may contain the same token consent application
got in the 5th step if it is still valid.
If it is not, consent application must again authenticate itself. acp->>cApp: redirect_uri (used for redirecting user back to Data Recipient client app) cApp->>user: Redirect the consumer back to the Data Recipient's software acp->>dr: Authorization code dr->>acp: /token acp->>dr: Access token Note over cApp, acp: This token is going to be used in requests to
Data Holder's Open Banking APIs dr->>dh: Call API end

To integrate your consent application with Cloudentity, use the following APIs:

  • OAuth 2.0 token endpoint

    You need to be able to authenticate your consent application to Cloudentity when making your API requests. When you choose consent type in your workspace Auth settings, the client application is automatically created within the System workspace for your tenant (as you use 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 two purposes: when authenticating itself to make requests to Cloudentity consent APIs (in the 4th step and, optionally, before the 11th or 14th step) and when authenticating itself to make requests to Data Holder’s Open Banking APIs (in steps 7 and 20).

    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.

  • Get CDR arrangement

    You can use this API to retrieve information on the CDR arrangement from Cloudentity. In the sequence diagram above, you can see the consent application makes such a request in the 6th step as it needs it to get consent details to render its UI to the consumer.

  • Accept CDR arrangement

    Use this API to notify Cloudentity that the consumer has accepted the consent and authorized the data recipient’s software. In the diagram, you can see that the consent application uses this endpoint in the 14th step only if the consent was approved by the consumer.

    As a result of the call, the consent application receives the redirect_to parameter in the response. Consent applications must redirect the consumer to the URL provided as the value of the redirect_to parameter.

  • Reject CDR arrangement

    Use this API to notify Cloudentity that the consumer has rejected the consent. The data recipient is not authorized to request resources. In the diagram, you can see that the consent application uses this endpoint in the 11th step only if the consent was rejected by the consumer.

    As a result of the call, the consent application receives the redirect_to parameter in the response. Consent applications must redirect the consumer to the URL provided as the value of the redirect_to parameter.

Consumer dashboards

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 custom 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 /token with client credentials grant type acp->>cd: Access token Note over acp, cd: The access token contains the `manage_openbanking_consents` scope cd->>acp: GET /cdr/arrangements Note over cd, acp: The request contains the token the Consumer Dashboard got in the 4th step acp->>cd: List of arrangements 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 page 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.

[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 account number cap->>acp: Request to /token with client credentials grant type acp->>cap: Access token Note over acp, cap: The access token contains the `manage_openbanking_consents` scope alt Admin wants to revoke single consent cap->>acp: GET /cdr/arrangements Note over cap, acp: The request contains the token the admin portal got in the 4th step acp->>cap: List of arrangements 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. else 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

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.