How-tos

Building CDR Compliant Consent Application

Learn how to build CDR compliant consent applications and integrate with Cloudentity using its built-in consent APIs.

Quickstart

Cloudentity offers a CDR reference application that you can use when creating your applications for a better understanding of how the flow works and how you can integrate with the Cloudentity platform. This reference application has a separate consent application that interacts with both Cloudentity and Data Holder APIs to display the data and scopes that is going to be shared with end consumer.

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. Authorisation and consent are central to the Consumer Data Right (CDR). Accredited Data Recipients (ADRs) and Data Holders (DHs) must obtain consent from the consumer before sharing consumer data. A Customer consent applies to specific customer data. The CDR Rules require that the customer must be fully informed regarding the data that is shared according to the consent.

Consent details are communicated between the ADR and DH via the OIDC authorization request object. Consent details are specified in the form of OIDC scopes and claims. According to the CDR CX 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 an extended integration point that provides Data Holders the customization flexibility to develop consent pages that adheres to CX guidelines via various digital channels.

When the consumer gets redirected to the Data Holder’s custom consent page from Cloudentity during any data authorization request flows, it receives the following parameters needed later on to fetch/accept/reject the consent arrangement within Cloudentity:

Parameter Description
login_id The identifier of the user’s session.
login_state Used to mitigate Cross-site request forgery (CSRF) attacks.

The Data language standards must be presented in consumer facing interactions(Consent app UI/UX/CX) to ensure there is consistent interpretation and description of the consumer data shared across organizations.

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.

Custom consent screen URL needs to be configured within Cloudentity. Cloudentity redirects consumers to this URL if Cloudentity authorization server finds a need to redirect consumers to the consent page (for example, if the consumer has not consented to share the requested information yet).

  1. Go to Auth Settings > Consent.

  2. In the Consent view

    1. Select Custom Consent to enable a custom consent screen for CDR.

    2. In the Consent URL field, provide the web address of your custom consent to be integrated.

    3. Select Save changes to proceed.

    Result

    When you save your changes, a trusted client is created automatically within Cloudentity that represents the custom consent application and its metadata gets displayed in the right-side pane. The client credentials displayed here must be used to fetch access tokens while interacting with the Cloudentity CDR Get/Accept/Reject arrangement APIs from the consent application.

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