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.
Consent applications
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
-
Consent applications must follow the Consumer Data Standard CX Guidelines.
-
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.
-
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.
-
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.
Integrate custom consent apps
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:
-
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 thescope
parameter. -
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.
-
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 theredirect_to
parameter. -
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 theredirect_to
parameter.