datarightplus S. Low Internet-Draft Biza.io Intended status: Experimental 14 September 2024 Expires: 18 March 2025 DataRight+: Energy Account Switch V1 draft-authors-datarightplus-energy-switch-v1-latest Abstract This specification outlines the technical requirements related to functionality to enable an Energy Account switching to be initiated under the DataRight+ ecosystem framework. Energy Account Switch V1 is intended to be an account opening specification for Energy sector participants. It incorporates initiation of the switch with the target Provider, tracking of the status of the switch by an Initiator and the optional sharing of energy data from the new Provider to the Initiator. This specification is considered entirely new functionality currently outside the scope of the Australian Consumer Data Right. 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 18 March 2025. 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. Table of Contents 1. Scope 2. Terms & Definitions 3. High Level Process 4. Provider 4.1. Authorisation Server 4.1.1. Request Object 4.1.2. Claims 4.2. Resource Server 5. Initiator 5.1. Authorisation Client 6. Implementation Considerations 7. Security Considerations 8. Normative References Author's Address 1. Scope The scope of this specification is focused on describing the authorisation related components of initiating an energy account switch to a new Provider, tracking the status of this switch and onward sharing to the Initiator of energy account data. 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]. 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 in the initial status 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) 4. Initiator redirects the Consumer user-agent to the Provider authorisation server 5. The Provider authorisation server completes the Consumer onboarding process, using any associated pre-fill supplied to the Initiate Energy Switch endpoint 6. On completion of the authorisation process the Initiator performs authorization_code token exchange with the Provider authorisation server. _Note 1:_ 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. _Note 2:_ It is at the discretion of the Provider what resources, if any, are available utilising the token obtained at the end of the authorisation process. In future versions fo this specification the token may represent an established sharing arrangement as specified in [DATARIGHTPLUS-SHARING-ARRANGEMENT-V2]. 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:action authorisation scope; 2. SHALL include the dio:action authorisation scope within Dynamic Client Registration responses; 4.1.1. Request Object The request object submitted to the authorisation server: 1. SHALL require a string parameter urn:dio:action_id, located within the ID Token claims, referencing a valid _Action Identifier_ previously submitted to the initiateEnergySwitch endpoint and; 2. SHALL be rejected if it contains a urn:dio:action_id parameter that is unknown, expired or not associated with the requesting Initiator; 4.1.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": "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 the urn:dio:action_id claim, containing the assigned _Action Identifier_; 4.2. Resource Server The Provider Resource Server: 1. SHALL support the initiateEnergySwitch and getEnergySwitchStatus endpoints as described in [DATARIGHTPLUS-REDOCLY]; 2. SHALL support [DATARIGHTPLUS-DISCOVERY-V1] and advertise the initiateEnergySwitch and getEnergySwitchStatus endpoints 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 initiateEnergySwitch and getEnergySwitchStatus endpoints; 2. SHALL perform a Dynamic Client Registration update, as described in [DATARIGHTPLUS-ADMISSION-CONTROL-00], to be granted access to the dio:action scope; 6. 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. 7. Security Considerations The Action Identifier SHALL NOT be guessable, derivable nor identify the Consumer. 8. Normative References [DATARIGHTPLUS-ADMISSION-CONTROL-00] Low, S. and B. Kolera, "DataRight+: Admission Control Baseline", . [DATARIGHTPLUS-DISCOVERY-V1] Low, S., "DataRight+: Provider Discovery V1", . [DATARIGHTPLUS-INFOSEC-BASELINE] Low, S., "DataRight+ Security Profile: Baseline", . [DATARIGHTPLUS-REDOCLY] Low, S., Kolera, B., and W. Cai, "DataRight+: Redocly (Draft)", . [DATARIGHTPLUS-ROSETTA] Low, S., "DataRight+ Rosetta Stone", . [DATARIGHTPLUS-SHARING-ARRANGEMENT-V2] Low, S. and B. Kolera, "DataRight+: Sharing Arrangement V2", . [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, DOI 10.17487/RFC2119, March 1997, . Author's Address Stuart Low Biza.io Email: stuart@biza.io