We launched new developer portal. For the latest documentation visit developer.cloudentity.com

Building CDR compliant consent application

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.

Consumer 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 to the Data Holder’s custom consent page, it 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.

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 Data Holder internal APIs to fetch all data that is needed to be displayed to the consumer to consciously make a consent decision.

    Example

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

  4. When the consumer accepts/rejects the consent, the consent application should redirect the consumer 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: /system/oauth2/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.