Internet-Draft DataRight+: Sharing Arrangement V2 November 2024
Low, et al. Expires 20 May 2025 [Page]
Workgroup:
datarightplus
Internet-Draft:
draft-authors-datarightplus-sharing-arrangement-v2-latest
Published:
Intended Status:
Experimental
Expires:
Authors:
S. Low
Biza.io
B. Kolera
Biza.io
W. Cai
Biza.io

DataRight+: Sharing Arrangement V2

Abstract

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.

Notational Conventions

The keywords "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in [RFC2119].

Status of This Memo

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 20 May 2025.

▲

Table of Contents

1. Scope

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.

2. Terms & Definitions

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

Action Identifier
A unique and discrete identifier for a given action, typically lodged at a resource server endpoint. This identifier is intended to bind an identifier returned from a resource server endpoint with the applicable authorisation. Authorisation initiation may be conducted multiple times for a single action identifier where the relevant action state permits it.

3. High Level Process

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:

  1. Initiator utilises a client credentials grant to obtain a token from the Provider;
  2. Initiator calls the Request Sharing Agreement endpoint and obtains an actionId with an actionStatus of PENDING;
  3. Initiator submits a pushed authorisation request with a Request Object containing the urn:dio:action_id parameter with a value equal to the actionId returned in (2). The Provider updates the associated actionStatus to CLAIMED;
  4. Initiator redirects the Consumer user-agent to complete the authorisation process. Once the Provider authorisation server has initiated the authorisation process for the user-agent the actionStatus is updated to IN_PROGRESS and the authStatus to PRE_IDENTIFICATION
  5. As the user-agent progresses through the authorisation process the authStatus is updated in line with the stage of the authorisation the user-agent is currently on.

  6. On completion of the authorisation process:

    1. the Provider, if not already assigned, assigns an agreementId to the associated actionId
    2. the Provider updates the actionStatus to either SUCCESS or FAILED and;
    3. performs client redirection back to the Initiator
  7. The Initiator performs authorization_code token exchange to access the Provider Resource Server resources

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.

4. Provider

The following provisions apply to services delivered by Providers.

4.1. Authorisation Server

In addition to the provisions outlined in [DATARIGHTPLUS-INFOSEC-BASELINE] the authorisation server:

  1. SHALL support the dio:sharing authorisation scope;
  2. SHALL include the dio:sharing authorisation scope within Dynamic Client Registration responses;
  3. SHALL update the data contained within the getSharingAgreement response;
  4. SHOULD update the authStatus with the last known stage the user-agent within the consent process;
  5. SHALL require an ID Token claim urn:dio:action_id referencing a valid Action Identifier;
  6. SHALL reject requests where the action referenced by urn:dio:action_id is unknown, not associated with the Initiator or in any other state other than PENDING

4.1.1. Example

The following is a non-normative example of a decoded request object requesting authorisation for a previously lodged actionId

{
  "iss": "33ff17d6-d967-4823-a4d3-1206fd2fff3f",
  "exp": 1725090872,
  "nbf": 1725090872,
  "aud": "https://www.provider.com.au",
  "response_type": "code",
  "response_mode": "jwt",
  "client_id": "33ff17d6-d967-4823-a4d3-1206fd2fff3f",
  "redirect_uri": "https://www.recipient.com.au/coolstuff",
  "scope": "openid",
  "claims": {
    "id_token": {
       "urn:dio:action_id": {
          "essential": true,
          "values": ["496a3ba7-04b4-4362-b775-9e0433e48eea"]
       },
      "acr": {
        "essential": true,
        "values": ["urn:cds.au:cdr:3"]
      }
    },
    "userinfo": {
      "given_name": null,
      "family_name": null
    }
  },
  "code_challenge": "rerbvXfTDYNECzwayM8-SLCWU1FDzBnqMCv1RB5AudU",
  "code_challenge_method": "S256"
}

4.1.2. Claims

The authorisation server:

  1. SHALL include within the Introspection Endpoint response:

    1. the exp claim, with a value equal to the expiry time of the underlying Sharing Agreement and;
    2. the urn:dio:action_id claim, containing the assigned Action Identifier;

4.1.3. CDR Arrangement V1 Compatibility

In order to maximise backward compatibility and facilitate orderly transition for endpoints already implemented the Authorisation Server SHALL ensure that the following authorisation scopes are mapped to Data Cluster values which are successfully authorised:

Table 1
EnumDataClusterV1 Value Authorization Scope
OPENID openid
PROFILE profile
BANK_ACCOUNTS_BASIC_READ bank:accounts.basic:read
BANK_ACCOUNTS_DETAIL_READ bank:accounts.detail:read
BANK_TRANSACTIONS_READ bank:transactions:read
BANK_REGULAR_PAYMENTS_READ bank:regular_payments:read
BANK_PAYEES_READ bank:payees:read
ENERGY_ACCOUNTS_BASIC_READ energy:accounts.basic:read
ENERGY_ACCOUNTS_DETAIL_READ energy:accounts.detail:read
ENERGY_ACCOUNTS_CONCESSIONS_READ energy:accounts.concessions:read
ENERGY_ACCOUNTS_PAYMENTSCHEDULE_READ energy:accounts.paymentschedule:read
ENERGY_BILLING_READ energy:billing:read
ENERGY_ELECTRICITY_SERVICEPOINTS_BASIC_READ energy:electricity.servicepoints.basic:read
ENERGY_ELECTRICITY_SERVICEPOINTS_DETAIL_READ energy:electricity.servicepoints.detail:read
ENERGY_ELECTRICITY_DER_READ energy:electricity.der:read
ENERGY_ELECTRICITY_USAGE_READ energy:electricity.usage:read
COMMON_CUSTOMER_BASIC_READ common:customer.basic:read
COMMON_CUSTOMER_DETAIL_READ common:customer.detail:read

4.2. Resource Server

The Provider Resource Server:

  1. SHALL support the requestDataSharing and getSharingRequest endpoints as described in [DATARIGHTPLUS-REDOCLY];
  2. SHALL support the getSharingAgreement endpoint as described in [DATARIGHTPLUS-REDOCLY];
  3. SHALL support [DATARIGHTPLUS-DISCOVERY-V1] and advertise the supported endpoints;
  4. SHALL support providing an existing agreementId in order to extend an existing agreement in subsequent Request Sharing Arrangement requests
  5. MAY support Consumer Type (consumerType) authorisation filtering and, if supported, include the SUPPORTS_CONSUMER_TYPE flag at the requestDataSharingAgreement endpoint
  6. MAY support record filtering by date (oldestDate/newestDate) and, if supported, include the SUPPORTS_DATE_FILTER flag at the requestDataSharingAgreement endpoint
  7. SHOULD expire actions which are in an actionStatus of PENDING within 60 minutes and update the actionStatus to EXPIRED;

5. Initiator

The following provisions apply to participants operating Initiators.

5.1. Authorisation Client

In addition to the provisions outlined in Section 4 of [DATARIGHTPLUS-INFOSEC-BASELINE] the Initiator authorisation client:

  1. SHALL support the Initiator provisions of [DATARIGHTPLUS-DISCOVERY-V1] to discover the endpoints of the Provider Resource Server;
  2. SHALL perform a Dynamic Client Registration update, as described in [DATARIGHTPLUS-ADMISSION-CONTROL-00], to be granted access to the dio:sharing scope;
  3. SHALL only include optional Request Sharing Agreement parameters if they are advertised as supported within the Provider discovery document

6. Non-Normative Examples

6.1. Request Data Sharing Request

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"
   }
}

6.2. Get Sharing Request

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"
   }
}

6.3. Get Sharing Arrangement

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"
   }
}

7. Implementation Considerations

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.

Despite the metadata being essentially overlapping, it is RECOMMENDED to store Sharing Arrangement V2 metadata distinctly from that stored for Sharing Arrangement V1, and by proxy the current form of a CDR Arrangement. This ensures that the sharing arrangement types can be bifurcated in future if required.

8. Security Considerations

The Action Identifier SHALL NOT be guessable, derivable nor identify the Consumer.

9. Normative References

[CDS]
Data Standards Body (Treasury), "Consumer Data Standards (CDS)", <https://consumerdatastandardsaustralia.github.io/standards>.
[DATARIGHTPLUS-ADMISSION-CONTROL-00]
Low, S. and B. Kolera, "DataRight+: Admission Control Baseline", <https://datarightplus.github.io/datarightplus-admission-control-baseline/draft-authors-datarightplus-admission-control-00/draft-authors-datarightplus-admission-control.html>.
[DATARIGHTPLUS-DISCOVERY-V1]
Low, S., "DataRight+: Provider Discovery V1", <https://datarightplus.github.io/datarightplus-discovery/draft-authors-datarightplus-discovery.html>.
[DATARIGHTPLUS-INFOSEC-BASELINE]
Low, S., "DataRight+ Security Profile: Baseline", <https://datarightplus.github.io/datarightplus-infosec-baseline/draft-authors-datarightplus-infosec-baseline.html>.
[DATARIGHTPLUS-REDOCLY]
Low, S., Kolera, B., and W. Cai, "DataRight+: Redocly (latest)", <https://datarightplus.github.io/datarightplus-redocly>.
[DATARIGHTPLUS-ROSETTA]
Low, S., "DataRight+ Rosetta Stone", <https://datarightplus.github.io/datarightplus-rosetta/draft-authors-datarightplus-rosetta.html>.
[DATARIGHTPLUS-SHARING-ARRANGEMENT-V1-00]
Low, S. and B. Kolera, "DataRight+: Sharing Arrangement V1", <https://datarightplus.github.io/datarightplus-sharing-arrangement-v1/draft-authors-datarightplus-sharing-arrangement-v1-00/draft-authors-datarightplus-sharing-arrangement-v1.html>.
[FAPI-GRANT-MANAGEMENT]
Hardt, D., "The OAuth 2.0 Authorization Framework", , <https://openid.net/specs/fapi-grant-management.html>.
[RFC2119]
Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, DOI 10.17487/RFC2119, , <https://www.rfc-editor.org/info/rfc2119>.

Authors' Addresses

Stuart Low
Biza.io
Ben Kolera
Biza.io
Wei Cai
Biza.io