DataRight+: Sharing Arrangement V1

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 .

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 .

Provider The following provisions apply to services delivered by Providers.

Authorisation Server In addition to the provisions outlined in the authorisation server:

SHALL NOT issue a refresh token unless the duration of the CDR Arrangement is greater than 0 (see [Request Object])
SHALL, where the supplied cdr_arrangement_id, if provided, does not match the authenticated Consumer and as soon as practicable, return an OAuth2 Error
SHALL modify the existing authorisation grant referenced by the cdr_arrangement_id, if provided, while maintaining the cdr_arrangement_id between such authorisations
SHALL revoke previously issued Access and refresh tokens when modifying existing authorisation grants;
SHALL support the Provider CDR Arrangement Revocation Endpoint (PCARE);
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 endpoint response;

Request Object The request object submitted to the authorisation server:

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.
SHALL support an optional string parameter cdr_arrangement_id referencing an existing CDR Arrangement (see CDR Sharing Arrangement Identifier);
SHALL reject requests containing a cdr_arrangement_id parameter that is unknown, expired or not associated with the requesting Initiator

Claims The authorisation server:

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]
SHALL ensure the cdr_arrangement_id claim is persistent and does not change between token interactions;

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.

PCARE Discovery The PCARE endpoint SHALL be advertised using the cdr_arrangement_revocation_endpoint attribute at the OpenID Connect Discovery 1.0 endpoint.

PCARE Request The PCARE endpoint receives requests using the HTTP POST method with parameters sent as application/x-www-form-urlencoded data as defined in . In addition to authentication credentials described in Section 2.2 of 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: On receipt of a valid request the Provider authorisation server:

SHALL validate the client credentials as per Section 2.2 of and;
SHALL validate the cdr_arrangement_id relates to a valid CDR Sharing Arrangement and;
SHALL verify the CDR Sharing Arrangement referenced by specified cdr_arrangement_id belongs to validated client
If all of the above conditions are met the authorisation server:
- 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

PCARE Response

Successful Response In the event of a successful revocation, the authorisation server:

If the CDR Sharing Arrangement is revoked, SHALL respond with a 204 HTTP status code containing no content
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

Failure Response In the event of a failure to validate the CDR Arrangement conditions the authorisation server:

SHALL respond with a 422 Unprocessable Entity response containing a JSON payload structured as as described below and;
SHOULD respond with a 503 Service Unavailable if currently unavailable and MAY supply a Retry-After indicating the earliest retry time

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:

Initiator The following provisions apply to participants operating individual Initiators.

Authorisation Client An Initiators authorisation client:

SHALL support the provisions specified in Section 4 of
SHALL support the submission of Request Object parameters outlined in [Request Object]
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
SHALL support the [Initiator CDR Arrangement Revocation Endpoint (ICARE)]
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.

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.

ICARE Request The protected resource calls the ICARE endpoint using an HTTP POST request with parameters sent as application/x-www-form-urlencoded data as defined in . cdr_arrangement_jwt REQUIRED. A single signed containing the following parameters:

cdr_arrangement_id representing the CDR Sharing Arrangement Identifier previously provided in the introspection endpoint responses;
iss: Provider ID issued by the Ecosystem Authority
sub: Provider ID issued by the Ecosystem Authority
aud: URI to the ICARE endpoint
jti: A unique identifier for the token
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 with the following parameters:

iss: Provider ID issued by the Ecosystem Authority
sub: Provider ID issued by the Ecosystem Authority
aud: URI to the ICARE endpoint
jti: A unique identifier for the token
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: 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.

ICARE Response

Successful Response In the event of a successful revocation, the Initiator:

if the CDR Sharing Arrangement is revoked, SHALL respond with a 204 HTTP status code containing no content
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

Failure Response In the event of a failure to validate the CDR Arrangement conditions the Initiator:

SHALL respond with a 422 Unprocessable Entity response containing a JSON payload structured as as described below and;
SHOULD respond with a 503 Service Unavailable if currently unavailable and MAY supply a Retry-After indicating the earliest retry time

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:

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 .

Security Considerations The CDR Sharing Arrangement Identifier SHALL NOT be guessable, derivable nor identify the Consumer.