How-tos

6 mins read

Customer Data Right Arrangement Amendment

This article provides an overview of Consumer Data Right (CDR) consent (arragement) amendement process when an accredited data recipient wants to modify an existing data sharing consent obtained from a consumer

CDR Arrangement Amendment

An existing data sharing agreement between an Accredited Data Recipient (ADR) and a Data Holder (DH) consented by a consumer is termed as a CDR arrangement. cdr_arrangement_id is a unique identifier of the CDR arrangement related to the authorization which is internally mapped to a consumer and related data sharing details as part of a specific consumer consent. The ADR is not obliged to pass an existing arrangement ID when creating new consent. If a new concurrent consent is to be created, then a consent is established without a pre-existing arrangement ID. An arrangement ID needs to be passed by the ADR only when an existing consent is being revoked and amended in an atomic step such as extension or modification of the consent.

Concurrent consent allows the same Accredited Data Recipient software product to establish more than one active consent with a Data Holder (DH) on the consumer’s behalf. The purpose is to allow consents with different scopes, use cases or purposes to be established under one ADR application, so that ADRs can correctly observe the Data Minimisation principle. This is achieved technically through the establishment of separate CDR Arrangement ID for each individual consent.An ADR can have multiple concurrent consents for a particular consumer with the same DH.

Amendment Workflow

Below sequence diagram depicts a consumer consent amendment flow initiated by ADR with a Pushed Authorization Request (PAR) request to the Cloudentity endpoint along with the existing “cdr_arrangement_id” and the new consent scope and sharing duration that needs to be amended.

[mermaid-begin]
sequenceDiagram autoNumber participant user as User participant adr as Data Recipient participant dh as Data Holder -
Infosec Provider (Cloudentity) participant consentApp as Data Holder -
Consent Application participant dhapi as Data Holder -
API adr->>dh: Initiate PAR request with CDR arrangement id dh->>dh: Verify request alt Consent Amendment required dh->>dh: Create a new temporary arrangement id dh->>dh: Store the existing arrangement id as amending arrangement id dh->>consentApp: Redirect user to consent application with `login_id` and `login_state` query parameters consentApp->>consentApp: Retain login and login_state values for usage in below calls consentApp->>dh: Get Cloudentity token(/system/oauth2/token) with scope `manage_openbanking_consents` dh->>consentApp: Cloudentity API accessToken with scope `manage_openbanking_consents` consentApp->>dh: Get CDR arrangement API
Bearer Cloudentity accessToken dh->>consentApp: CDR arrangement details with existing & temporary arrangement details consentApp->>dhapi: Get user account details from internal account API consentApp->>consentApp: Get difference between existing
arrangement(`previous_arrangement_id`) and temporary arrangement consentApp->>user: Display consent page with details user->>consentApp: Accept/Deny consent changes alt Consent Amendment accepted consentApp->>dh: Accept CDR consent API
Bearer Cloudentity accessToken dh->>dh: Take all values from temporary arrangement and update original arrangement id and details dh->>dh: Discard temporary arrangement id & details consentApp->>dh: Redirect to Cloudentity redirect uri dh->>dh: Mint authorization access code dh->>adr: Return accessCode to data recipient end alt Consent Amendment rejected consentApp->>dh: Reject CDR consent API
Bearer Cloudentity accessToken dh->>dh: Retain original arrangement id details dh->>dh: Discard temporary arrangement id & details consentApp->>dh: Redirect to Cloudentity redirect uri dh->>adr: return authorization error to data recipient end alt Consent Amendment not required dh->>dh: Mint authorization access code dh->>adr: Return accessCode to data recipient end end

API usage

To allow consent application to handle consent amendment workflows as depicted above, following Cloudentity APIs must be utilized by the custom consent application.

  • OAuth 2.0 token endpoint

    The custom consent application is configured within the regular CDR workspace and it is internally registered as an OAuth Client application within the tenant System workspace. This client application is automatically subscribed to manage_openbanking_consents scope. This client application credentials must be used to authenticate the client and fetch an OAuth access token. The client application credentials can be obtained from the CDR workspace itself after the consent application is registered.

    cdr_qs_consent_setup_acp

    This access token needs to be presented as Bearer token while calling the consent APIs for CDR within Cloudentity. API access is allowed for Bearer tokens that have the manage_openbanking_consents scope.

    In the above diagram, you can see that the consent application makes requests to the {tenantId}/system/oauth2/token in step #7 to fetch an access token to make requests to Cloudentity consent APIs.

    Tips

    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.

    The consent application may cache this token for the validity of its lifetime to eliminate multiple network calls to refetch access token and can reuse this token while interacting with Cloudentity APIs

  • Get CDR arrangement

    Get CDR arrangement API is used to retrieve detailed information about the CDR arrangement from Cloudentity, as shown in step #9 in above sequence diagram. This API returns the previous cdr arrangement details as well as the new amended arrangement request in the API response. This will allow the consent application to show a difference in the arrangement consents to consumer to approve/deny.

    It is to be noted that the amending arrangement is a temporal request scope and is not persisted until user explictly accepts the amended consent. According to the CDR spec, the previous arrangement is still valid until the new one is finalized, so during an amendment flow the value of status field within the response is Authorised.

    Tips - API access

    This API is protected with tokens that has manage_openbanking_consents scope, use the Bearer token obtained in step #8.

    This API requires login & login_state parameters obtained in step #6

    CX Guidance

    It is the responsibility of consent application to work out new scopes, sharing period, accounts that needs to be displayed to consumer. From the API response, following data elements can be used to derive the UI data values

    • scopes with previous_cdr_arrangement.scope_grants against requested_scopes
    • sharing period with previous_cdr_arrangement.expiry against cdr_arrangement.expiry
    • accounts using existing previous_cdr_arrangement.account_ids against the get accounts API from data holder itself
  • Accept CDR arrangement

    Accept CDR arrangement API must be called by the Consent application to notify Cloudentity that the consumer has accepted the amended consent and authorized the data recipient’s request. Once the amended arrangement is accepted, Cloudentity persists the new arrangement over the existing arrangement and retains the same arrangement id. This API is utilized in step #15 in the above sequence diagram.

    If the API call succeeds, 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.

    Tips - API access

    This API is protected with tokens that has manage_openbanking_consents scope, use the Bearer token obtained in step #8.

    This API requires login & login_state parameters obtained in step #6.

  • Reject CDR arrangement

    Reject CDR arrangement API must be called by the Consent application to notify Cloudentity that the consumer has rejected the amended consent and has not authorized the data recipient’s request. Once the amended arrangement is rejected, Cloudentity retains the existing arrangement and discards the requested amended arrangement changes. This API is utilized in step #21 in the above sequence diagram.

    If the API call succeeds, 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.

    Tips - API access

    This API is protected with tokens that has manage_openbanking_consents scope, use the Bearer token obtained in step #8.

    This API requires login & login_state parameters obtained in step #6.

Updated: Jun 22, 2023