CDR Arrangement Amendment
This article provides an overview of 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
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
-
The custom consent application is registered as an OAuth Client application within Cloudentity and is available within the
system
workspace. This client application is automatically subscribed to getmanage_openbanking_consents
scope . The registered client application credentials must be used to authenticate the client and fetch an oAuth accessToken. This access token needs to be presented as bearer token while calling any consent API available in Cloudentity. API access is allowed for bearer tokens that hasmanage_openbanking_consents
scope.In the diagram above, you can see that the consent application makes requests to the /system/oauth2/token in
step #7
to fetch an accessToken to make requests to Cloudentity consent APIs. The consent application may cache this token for the validity of its lifetime to eliminate multiple networks being used.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. This API is utilized 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 faciliate 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 acceepts the amended consent.Tips
When calling this API, pass the Bearer token fetched is
step #8
This API requires
login
&login_state
parameters obtained instep #6
-
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 will persist the new arrangement over the existing arrangement and retain the same arrangement id. This API is utilized in
step #15
in 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
When calling this API, pass the Bearer token fetched is
step #8
This API requires
login
&login_state
parameters obtained instep #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 will retain the existing arrangement and discard the requested amended arrangement changes. This API is utilized in
step #21
in 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
When calling this API, pass the Bearer token fetched is
step #8
This API requires
login
&login_state
parameters obtained instep #6