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
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.
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.
-
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.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 thescope
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 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 isAuthorised
.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 instep #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
againstrequested_scopes
- sharing period with
previous_cdr_arrangement.expiry
againstcdr_arrangement.expiry
- accounts using existing
previous_cdr_arrangement.account_ids
against the get accounts API from data holder itself
- scopes with
-
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 theredirect_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 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 theredirect_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.