DataRight+: Sharing Arrangement V1
draft-authors-datarightplus-sharing-arrangement-v1-00
| Document | Type | Active Internet-Draft (individual) | |
|---|---|---|---|
| Authors | Stuart Low , Ben Kolera | ||
| Last updated | 2024-04-01 | ||
| RFC stream | (None) | ||
| Intended RFC status | (None) | ||
| Formats | |||
| Stream | Stream state | (No stream defined) | |
| Consensus boilerplate | Unknown | ||
| RFC Editor Note | (None) | ||
| IESG | IESG state | I-D Exists | |
| Telechat date | (None) | ||
| Responsible AD | (None) | ||
| Send notices to | (None) |
draft-authors-datarightplus-sharing-arrangement-v1-00
datarightplus S. Low
Internet-Draft B. Kolera
Intended status: Experimental Biza.io
Expires: 3 October 2024 1 April 2024
DataRight+: Sharing Arrangement V1
draft-authors-datarightplus-sharing-arrangement-v1-00
Abstract
This specification outlines the technical requirements related to the
delivery of Sharing Arrangement V1.
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 3 October 2024.
Copyright Notice
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.
Low & Kolera Expires 3 October 2024 [Page 1]
Internet-Draft DataRight+: Sharing Arrangement V1 April 2024
Table of Contents
1. Scope . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2
2. Terms & Definitions . . . . . . . . . . . . . . . . . . . . . 2
3. Provider . . . . . . . . . . . . . . . . . . . . . . . . . . 2
3.1. Authorisation Server . . . . . . . . . . . . . . . . . . 2
3.1.1. Request Object . . . . . . . . . . . . . . . . . . . 3
3.1.2. Claims . . . . . . . . . . . . . . . . . . . . . . . 3
3.2. Provider CDR Arrangement Revocation Endpoint (PCARE) . . 4
3.2.1. PCARE Discovery . . . . . . . . . . . . . . . . . . . 4
3.2.2. PCARE Request . . . . . . . . . . . . . . . . . . . . 4
3.2.3. PCARE Response . . . . . . . . . . . . . . . . . . . 5
4. Initiator . . . . . . . . . . . . . . . . . . . . . . . . . . 6
4.1. Authorisation Client . . . . . . . . . . . . . . . . . . 6
4.2. Initiator CDR Arrangement Revocation Endpoint (ICARE) . . 6
4.2.1. ICARE Request . . . . . . . . . . . . . . . . . . . . 6
4.2.2. ICARE Response . . . . . . . . . . . . . . . . . . . 8
5. Implementation Considerations . . . . . . . . . . . . . . . . 9
6. Security Considerations . . . . . . . . . . . . . . . . . . . 9
7. Normative References . . . . . . . . . . . . . . . . . . . . 9
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 10
1. Scope
The scope of this specification is focused on describing the
authorisation related components of establishing a CDR Sharing
Arrangement. This specification unavoidably references ecosystem
specific concepts (Australian CDR) due to the very nature of
localised claim names. Sharing Arrangement V1 therefore is aligned
with the definition of a CDR Arrangement as originally outlined
within [CDS].
2. Terms & Definitions
This specification uses the terms "Consumer", "Provider",
"Initiator", "Personally Identifiable Information (PII)", "Pairwise
Pseudonymous Identifier (PPID)", "Initiator", "CDR Sharing
Arrangement" and "CDR Sharing Arrangement Identifier" as defined by
[DATARIGHTPLUS-ROSETTA].
3. Provider
The following provisions apply to services delivered by Providers.
3.1. Authorisation Server
In addition to the provisions outlined in
[DATARIGHTPLUS-INFOSEC-BASELINE] the authorisation server:
Low & Kolera Expires 3 October 2024 [Page 2]
Internet-Draft DataRight+: Sharing Arrangement V1 April 2024
1. SHALL NOT issue a refresh token unless the duration of the CDR
Arrangement is greater than 0 (see [Request Object])
2. SHALL, where the supplied cdr_arrangement_id, if provided, does
not match the authenticated Consumer and as soon as practicable,
return an OAuth2 Error
3. SHALL modify the existing authorisation grant referenced by the
cdr_arrangement_id, if provided, while maintaining the
cdr_arrangement_id between such authorisations
4. SHALL revoke previously issued Access and refresh tokens when
modifying existing authorisation grants;
5. SHALL support the Provider CDR Arrangement Revocation Endpoint
(PCARE);
6. SHALL publish the url for the [Provider CDR Arrangement
Revocation Endpoint (PCARE)] as an attribute named
cdr_arrangement_revocation_endpoint within the OpenID Connect
Discovery 1.0 [OIDC-Discovery] endpoint response;
3.1.1. Request Object
The request object submitted to the authorisation server:
1. SHALL support an optional integer parameter of sharing_duration
representing the number of seconds requested for data sharing.
The default value of this parameter SHALL be 0 and the maximum
value SHALL NOT exceed 31536000.
2. SHALL support an optional string parameter cdr_arrangement_id
referencing an existing CDR Arrangement (see CDR Sharing
Arrangement Identifier);
3. SHALL reject requests containing a cdr_arrangement_id parameter
that is unknown, expired or not associated with the requesting
Initiator
3.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 CDR Arrangement and;
2. the cdr_arrangement_id claim, containing the assigned [CDR
Sharing Arrangement Identifier]
2. SHALL ensure the cdr_arrangement_id claim is persistent and does
not change between token interactions;
Low & Kolera Expires 3 October 2024 [Page 3]
Internet-Draft DataRight+: Sharing Arrangement V1 April 2024
3.2. Provider CDR Arrangement Revocation Endpoint (PCARE)
The Provider CDR Arrangement (PCARE) Revocation endpoint accepts a
CDR Sharing Arrangement Identifier and immediately revokes the CDR
Sharing Arrangement.
3.2.1. PCARE Discovery
The PCARE endpoint SHALL be advertised using the
cdr_arrangement_revocation_endpoint attribute at the OpenID Connect
Discovery 1.0 [OIDC-Discovery] endpoint.
3.2.2. PCARE Request
The PCARE endpoint receives requests using the HTTP POST [RFC7231]
method with parameters sent as application/x-www-form-urlencoded data
as defined in [W3C.REC-html5-20141028].
In addition to authentication credentials described in Section 2.2 of
[RFC7523] the endpoint includes the CDR Sharing Arrangement
Identifier as an additional parameter, specified as follows:
* cdr_arrangement_id: REQUIRED The CDR Sharing Arrangement
Identifier previously provided in the token and introspection
endpoint responses.
An example request to the Provider CDR Arrangement Revocation
Endpoint is as follows:
POST https://data.provider.com.au/arrangements/revoke
HTTP/1.1
Host: data.Provider.com.au
Content-Type: application/x-www-form-urlencoded
client_id=s6BhdRkqt3&
client_assertion_type=urn%3Aietf%3Aparams%3Aoauth%3Aclient-assertion-type%3Ajwt-bearer&
client_assertion=eyJhbGciOiJQUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6IjEyNDU2In0.ey ...&
cdr_arrangement_id=5a1bf696-ee03-408b-b315-97955415d1f0
On receipt of a valid request the Provider authorisation server:
1. SHALL validate the client credentials as per Section 2.2 of
[RFC7523] and;
2. SHALL validate the cdr_arrangement_id relates to a valid CDR
Sharing Arrangement and;
3. SHALL verify the CDR Sharing Arrangement referenced by specified
cdr_arrangement_id belongs to validated client
4. If all of the above conditions are met the authorisation server:
Low & Kolera Expires 3 October 2024 [Page 4]
Internet-Draft DataRight+: Sharing Arrangement V1 April 2024
* SHALL immediately invalidate the CDR Arrangement
* SHALL immediately invalidate all refresh tokens associated
with the CDR Arrangement
* SHALL immediately invalid all access tokens associated with
the CDR Arrangement
3.2.3. PCARE Response
3.2.3.1. Successful Response
In the event of a successful revocation, the authorisation server:
1. If the CDR Sharing Arrangement is revoked, SHALL respond with a
204 HTTP status code containing no content
2. If the CDR Sharing Arrangement was already revoked prior to the
request being received, SHOULD respond with a 204 HTTP status
code containing no content
3.2.3.2. Failure Response
In the event of a failure to validate the CDR Arrangement conditions
the authorisation server:
1. SHALL respond with a 422 Unprocessable Entity response containing
a JSON payload structured as as described below and;
2. SHOULD respond with a 503 Service Unavailable if currently
unavailable and MAY supply a Retry-After indicating the earliest
retry time
3.2.3.2.1. Failure Response Body
The failure response body is an object with a single attribute of
errors containing an array of one object with the following fields:
* code with the value of urn:au-cds:error:cds-all:Authorisation/
InvalidArrangement
* title with the value of The arrangement could not be found.
* detail with a value containing the provided cdr_arrangement_id
A non-normative example of the payload is provided below:
Low & Kolera Expires 3 October 2024 [Page 5]
Internet-Draft DataRight+: Sharing Arrangement V1 April 2024
{
"errors": [
{
"code": "urn:au-cds:error:cds-all:Authorisation/InvalidArrangement",
"title": "The arrangement could not be found.",
"detail": "b3f0c9d0-457d-4578-b0cd-52e443ae13c5"
}
]
}
4. Initiator
The following provisions apply to participants operating individual
Initiators.
4.1. Authorisation Client
An Initiators authorisation client:
1. SHALL support the provisions specified in Section 4 of
[DATARIGHTPLUS-INFOSEC-BASELINE]
2. SHALL support the submission of Request Object parameters
outlined in [Request Object]
3. SHALL call the [Provider CDR Arrangement Revocation Endpoint
(PCARE)] following;
1. revocation request is requested by the Consumer using the
Initiator Consumer Dashboard or;
2. where a refresh token has not been issued, as soon as
practicable following the completion of data collection
4. SHALL support the [Initiator CDR Arrangement Revocation Endpoint
(ICARE)]
5. SHALL retry requests to the [Provider CDR Arrangement Revocation
Endpoint (PCARE)] where the response received was a HTTP Status
503. The retry time SHOULD be informed by the presence of the
Retry-After header.
4.2. Initiator CDR Arrangement Revocation Endpoint (ICARE)
The Initiator CDR Arrangement (ICARE) Revocation endpoint accepts a
CDR Sharing Arrangement Identifier and immediately revokes the CDR
Sharing Arrangement.
4.2.1. ICARE Request
The protected resource calls the ICARE endpoint using an HTTP POST
[RFC7231] request with parameters sent as application/x-www-form-
urlencoded data as defined in [W3C.REC-html5-20141028].
Low & Kolera Expires 3 October 2024 [Page 6]
Internet-Draft DataRight+: Sharing Arrangement V1 April 2024
cdr_arrangement_jwt REQUIRED. A single signed [JWT] containing the
following parameters:
1. cdr_arrangement_id representing the CDR Sharing Arrangement
Identifier previously provided in the introspection endpoint
responses;
2. iss: Provider ID issued by the Ecosystem Authority
3. sub: Provider ID issued by the Ecosystem Authority
4. aud: URI to the ICARE endpoint
5. jti: A unique identifier for the token
6. exp: Expiration time on or after the JWT must not be accepted
In addition, the client includes an Authorization header parameter
with a Bearer token containing a single signed [JWT] with the
following parameters:
1. iss: Provider ID issued by the Ecosystem Authority
2. sub: Provider ID issued by the Ecosystem Authority
3. aud: URI to the ICARE endpoint
4. jti: A unique identifier for the token
5. exp: Expiration time on or after the JWT must not be accepted
For example, a Provider may request CDR Arrangement revocation with
the following request:
POST https://data.Initiator.com.au/arrangements/revoke HTTP/1.1
Host: data.Initiator.com.au
Content-Type: application/x-www-form-urlencoded
Authorization: Bearer eyJhbGciOiJQUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6IjEyNDU2In0.ey …
cdr_arrangement_jwt=eyJhbGciOiJQUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6IjEyNDU2In0.ey ...&
The Initiator first validates the Provider credentials and then
verifies whether the CDR Sharing Arrangement Identifier exists and
was issued by the Provider making the CDR Arrangement Revocation
request. If this validation fails, the request is refused and the
Provider is informed of the error by the ICARE endpoint as described
below.
In the next step, the Initiator invalidates the CDR Arrangement and
SHOULD discard associated tokens. Data Minimisation events SHOULD
also be triggered on receipt of this event.
Low & Kolera Expires 3 October 2024 [Page 7]
Internet-Draft DataRight+: Sharing Arrangement V1 April 2024
4.2.2. ICARE Response
4.2.2.1. Successful Response
In the event of a successful revocation, the Initiator:
1. if the CDR Sharing Arrangement is revoked, SHALL respond with a
204 HTTP status code containing no content
2. if the CDR Sharing Arrangement was already revoked prior to the
request being received, SHOULD respond with a 204 HTTP status
code containing no content
4.2.2.2. Failure Response
In the event of a failure to validate the CDR Arrangement conditions
the Initiator:
1. SHALL respond with a 422 Unprocessable Entity response containing
a JSON payload structured as as described below and;
2. SHOULD respond with a 503 Service Unavailable if currently
unavailable and MAY supply a Retry-After indicating the earliest
retry time
4.2.2.2.1. Failure Response Body
The failure response body is an object with a single attribute of
errors containing an array of one object with the following fields:
* code with the value of urn:au-cds:error:cds-all:Authorisation/
InvalidArrangement
* title with the value of The arrangement could not be found.
* detail with a value containing the provided cdr_arrangement_id
A non-normative example of the payload is provided below:
{
"errors": [
{
"code": "urn:au-cds:error:cds-all:Authorisation/InvalidArrangement",
"title": "The arrangement could not be found.",
"detail": "b3f0c9d0-457d-4578-b0cd-52e443ae13c5"
}
]
}
Low & Kolera Expires 3 October 2024 [Page 8]
Internet-Draft DataRight+: Sharing Arrangement V1 April 2024
5. Implementation Considerations
Where a Initiator, by way of the [Request Object], requests to update
an existing authorisation grant through the supply of the
cdr_arrangement_id some ecosystems may apply additional expectations
with respect to the authorisation flow. Within the Australian
Consumer Data Right this is summarised within the _CX Standards:
Amending Authorisation_ section of the [CDS].
6. Security Considerations
The CDR Sharing Arrangement Identifier SHALL NOT be guessable,
derivable nor identify the Consumer.
7. Normative References
[CDS] Data Standards Body (Treasury), "Consumer Data Standards
(CDS)", <https://consumerdatastandardsaustralia.github.io/
standards>.
[DATARIGHTPLUS-INFOSEC-BASELINE]
Low, S., "DataRight+ Security Profile: Baseline",
<https://datarightplus.github.io/datarightplus-infosec-
baseline/draft-authors-datarightplus-infosec-
baseline.html>.
[DATARIGHTPLUS-ROSETTA]
Low, S., "DataRight+ Rosetta Stone",
<https://datarightplus.github.io/datarightplus-rosetta/
draft-authors-datarightplus-rosetta.html>.
[JWT] Jones, M., Bradley, J., and N. Sakimura, "JSON Web Token
(JWT)", May 2015,
<https://datatracker.ietf.org/doc/html/rfc7519>.
[OIDC-Discovery]
Sakimura, N., Bradley, J., Jones, M., and E. Jay, "OpenID
Connect Discovery 1.0 incorporating errata set 1", 8
November 2014, <https://openid.net/specs/openid-connect-
discovery-1_0.html>.
[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
Requirement Levels", BCP 14, RFC 2119,
DOI 10.17487/RFC2119, March 1997,
<https://www.rfc-editor.org/info/rfc2119>.
Low & Kolera Expires 3 October 2024 [Page 9]
Internet-Draft DataRight+: Sharing Arrangement V1 April 2024
[RFC7231] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer
Protocol (HTTP/1.1): Semantics and Content", RFC 7231,
DOI 10.17487/RFC7231, June 2014,
<https://www.rfc-editor.org/info/rfc7231>.
[RFC7523] Jones, M., Campbell, B., and C. Mortimore, "JSON Web Token
(JWT) Profile for OAuth 2.0 Client Authentication and
Authorization Grants", RFC 7523, DOI 10.17487/RFC7523, May
2015, <https://www.rfc-editor.org/info/rfc7523>.
[W3C.REC-html5-20141028]
Navara, E. D., Ed., Hickson, I., Ed., Berjon, R., Ed.,
Pfeiffer, S., Ed., Faulkner, S., Ed., O'Connor, T., Ed.,
and T. Leithead, Ed., "HTML5", W3C REC REC-html5-20141028,
W3C REC-html5-20141028, 28 October 2014,
<https://www.w3.org/TR/2014/REC-html5-20141028/>.
Authors' Addresses
Stuart Low
Biza.io
Email: stuart@biza.io
Ben Kolera
Biza.io
Email: bkolera@biza.io
Low & Kolera Expires 3 October 2024 [Page 10]