Internet-Draft | DataRight+: Sharing Arrangement V2 | September 2024 |
Low & Kolera | Expires 25 March 2025 | [Page] |
This specification outlines the technical requirements related to the delivery of an enhanced establishment process for data sharing arrangements under DataRight+ and the Consumer Data Right.¶
Sharing Arrangement V2 is intended to be the next evolution of [DATARIGHTPLUS-SHARING-ARRANGEMENT-V1-00] and incorporates modern and international standards aligned practices to achieve like for like outcomes. This specification takes significant inspiration from the [FAPI-GRANT-MANAGEMENT] specification and the original intent based pattern first presented within the UK Open Banking scheme.¶
The keywords "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in [RFC2119].¶
This Internet-Draft is submitted in full conformance with the provisions of BCP 78 and BCP 79.¶
Internet-Drafts are working documents of the Internet Engineering Task Force (IETF). Note that other groups may also distribute working documents as Internet-Drafts. The list of current Internet-Drafts is at https://datatracker.ietf.org/drafts/current/.¶
Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as "work in progress."¶
This Internet-Draft will expire on 25 March 2025.¶
Copyright (c) 2024 IETF Trust and the persons identified as the document authors. All rights reserved.¶
This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (https://trustee.ietf.org/license-info) in effect on the date of publication of this document. Please review these documents carefully, as they describe your rights and restrictions with respect to this document.¶
The scope of this specification is focused on describing the authorisation related components of establishing an authentication and authorisation context for data sharing under the DataRight+ framework. This specification achieves the same objectives as those prescribed within [CDS] but avoids the ecosystem specific components in favour of a more extensible and international standards aligned mechanisms.¶
This specification uses the terms "Agreement Identifier", Consumer", "Provider", "Initiator", "Personally Identifiable Information (PII)", "Pairwise Pseudonymous Identifier (PPID)", "Initiator", "CDR Sharing Arrangement" and "CDR Sharing Agreement Identifier" as defined by [DATARIGHTPLUS-ROSETTA].¶
This document, as extended further in OpenAPI format within [DATARIGHTPLUS-REDOCLY], describes the endpoints to deliver the Sharing Arrangement V2 capability. The current approach to data sharing within the Consumer Data Right is brittle and does not provide sufficient feedback as to the status of sharing requests as they are handed over from Initiator to the Provider. The existing sharing establishment process also assumes a live establishment rather than a potentially asynchronous, back-channel or machine to machine (IoT) authorisation approach.¶
At a high level the process expected to be followed through the implementation of this specification is:¶
actionId
in the initial status of PENDING
;¶
urn:dio:action_id
parameter with a value equal to the actionId
returned in (2)¶
On completion of the authorisation process:¶
Note: At any time before, during or after the authorisation process the Initiator can use the Get Sharing Agreement endpoint provided by the Resource Server utilising the obtained actionId
.¶
The following provisions apply to services delivered by Providers.¶
The Provider Resource Server:¶
requestDataSharing
and getSharingRequest
endpoints as described in [DATARIGHTPLUS-REDOCLY];¶
getSharingAgreement
endpoint as described in [DATARIGHTPLUS-REDOCLY];¶
getCurrentSharingAgreement
endpoint as described in [DATARIGHTPLUS-REDOCLY];¶
agreementId
in order to extend an existing agreement in subsequent Request Sharing Arrangement requests¶
consumerType
) authorisation filtering and, if supported, include the SUPPORTS_CONSUMER_TYPE
flag at the requestDataSharingAgreement
endpoint¶
oldestDate
/newestDate
) and, if supported, include the SUPPORTS_DATE_FILTER
flag at the requestDataSharingAgreement
endpoint¶
Initialise a sharing request for Basic Bank Accounts Read for 365 Days:¶
POST /dio-au/actions/request-data-sharing Host: api.provider.com.au Content-Type: application/json Bearer: <client credentials token containing dio:sharing> Accept: application/json x-v: V2 { "version": "V2", "data": { "sharingDuration": 31536000, "dataClusters": [ "BANK_ACCOUNTS_BASIC_READ" ] } }¶
Response indicating an assigned Action Identifier pending authorisation establishment. It would be expected the actionId
is then used to create a PAR request containing the required identifier.¶
{ "version": "V2", "data": { "sharingDuration": 31536000, "dataClusters": [ "BANK_ACCOUNTS_BASIC_READ" ] }, "links": { "self": "https://api.provider.com.au/dio-au/actions/request-data-sharing/8ba3f97e-c22c-4516-b6ed-05c0486db195" }, "meta": { "actionId": "8ba3f97e-c22c-4516-b6ed-05c0486db195", "actionStatus": "PENDING", "actionStatusDescription": "Sharing Arrangement Request Pending", "authStatus": "PENDING", "authStatusDescription": "Pending Authorisation Initiation" } }¶
This retrieves the details of a current sharing request.¶
GET /dio-au/actions/request-data-sharing/8ba3f97e-c22c-4516-b6ed-05c0486db195 Host: api.provider.com.au Accept: application/json Bearer: <client credentials token containing dio:sharing> x-v: V2¶
Response indicating a completed authorisation and established agreement.¶
{ "version": "V2", "data": { "sharingDuration": 31536000, "dataClusters": [ "BANK_ACCOUNTS_BASIC_READ" ] }, "links": { "self": "https://api.provider.com.au/dio-au/actions/request-data-sharing/8ba3f97e-c22c-4516-b6ed-05c0486db195" }, "meta": { "actionId": "8ba3f97e-c22c-4516-b6ed-05c0486db195", "agreementId": "e1529071-601f-46ff-a097-97cdaba84065", "actionStatus": "SUCCESS", "actionStatusDescription": "Sharing Arrangement Established", "authStatus": "COMPLETE", "authStatusDescription": "Authorisation for sharing has been completed" } }¶
This retrieves an arrangements details after establishment.¶
GET /dio-au/actions/data-sharing/e1529071-601f-46ff-a097-97cdaba84065 Host: api.provider.com.au Accept: application/json Bearer: <client credentials token containing dio:sharing> x-v: V2¶
Response indicates an arrangement in Active state with an expiration time and set of data clusters.¶
{ "version": "V2", "data": { "agreementId": "e1529071-601f-46ff-a097-97cdaba84065", "status": "ACTIVE", "creationDateTime": "2023-09-21T14:44:16+10:00", "expiryDateTime": "2024-08-21T14:44:16+10:00", "dataClusters": [ "BANK_ACCOUNTS_BASIC_READ" ] }, "links": { "self": "https://api.provider.com.au/dio-au/actions/data-sharing/e1529071-601f-46ff-a097-97cdaba84065" } }¶
This retrieves the arrangement details for the specified Bearer token.¶
GET /dio-au/actions/data-sharing/self Host: api.provider.com.au Accept: application/json Bearer: <token obtained from completed sharing request authorisation> x-v: V2¶
Response indicates an arrangement in Active state with an expiration time and set of data clusters.¶
{ "version": "V2", "data": { "agreementId": "e1529071-601f-46ff-a097-97cdaba84065", "status": "ACTIVE", "creationDateTime": "2023-09-21T14:44:16+10:00", "expiryDateTime": "2024-08-21T14:44:16+10:00", "dataClusters": [ "BANK_ACCOUNTS_BASIC_READ" ] }, "links": { "self": "https://api.provider.com.au/dio-au/actions/data-sharing/self" } }¶
This specification does not explicitly state how long an assigned Action Identifier persists for however it is expected that an Initiator shall be able to reference an Action Identifier while the associated authorisation is still active and for a significant period (more than a year) after it becomes inactive.¶
The Action Identifier SHALL NOT be guessable, derivable nor identify the Consumer.¶