datarightplus S. Low Internet-Draft B. Kolera Intended status: Experimental Biza.io Expires: 4 October 2024 2 April 2024 DataRight+: Admission Control Baseline draft-authors-datarightplus-admission-control-00 Abstract The establishment of a shared model of trust is critical to any functioning technology ecosystem, particularly when it relates to the sharing of data and the execution of Consumer specific actions. Traditional models of trust have typically revolved around implicit trust established through bi-lateral arrangements (i.e. legal contracts) between participants. The issue with this approach is that, at scale, it is not possible for all participants to efficiently establish communication with all other participants. This leads to the requirement for a mechanism to establish trust across participants in a way that the business layer of an organisation has confidence in ensuring participant interaction is validated. 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 4 October 2024. Low & Kolera Expires 4 October 2024 [Page 1] Internet-Draft DataRight+: Admission Control Baseline April 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. Table of Contents 1. Scope . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2 2. Terms & Definitions . . . . . . . . . . . . . . . . . . . . . 2 3. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 4. Ecosystem Authority . . . . . . . . . . . . . . . . . . . . . 3 4.1. General Topology . . . . . . . . . . . . . . . . . . . . 3 4.2. Ecosystem CA . . . . . . . . . . . . . . . . . . . . . . 4 4.3. Directory . . . . . . . . . . . . . . . . . . . . . . . . 4 4.3.1. Authorisation Server . . . . . . . . . . . . . . . . 5 4.3.2. Resource Endpoints . . . . . . . . . . . . . . . . . 5 4.4. SSA Authority . . . . . . . . . . . . . . . . . . . . . . 6 4.4.1. SSA Attributes . . . . . . . . . . . . . . . . . . . 6 4.4.2. Authorisation Server . . . . . . . . . . . . . . . . 8 4.4.3. Resource Endpoints . . . . . . . . . . . . . . . . . 8 5. Provider . . . . . . . . . . . . . . . . . . . . . . . . . . 9 5.1. Authorisation Server . . . . . . . . . . . . . . . . . . 9 5.1.1. Dynamic Client Registration (DCR) . . . . . . . . . . 9 6. Initiator . . . . . . . . . . . . . . . . . . . . . . . . . . 10 7. Implementation Considerations . . . . . . . . . . . . . . . . 10 8. Normative References . . . . . . . . . . . . . . . . . . . . 10 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 12 1. Scope This document specifies methods for the following: * Participant management * Dynamic Client Registration * Transport level security 2. Terms & Definitions This specification utilises the various terms outlined within [DATARIGHTPLUS-ROSETTA]. Ecosystem Policy A policy document specific to the ecosystem Low & Kolera Expires 4 October 2024 [Page 2] Internet-Draft DataRight+: Admission Control Baseline April 2024 presented by the Initiator. Within the Australian CDR this is referred to as a data recipients CDR Policy Initiator Brand Identifier A unique identifier for the brand name which is presented as the owner of the Initiator. Initiator Entity Identifier A unique identifier for the legal entity related to the Initiator. Initiator Identifier A unique identifier for the specific Initiator. SHALL NOT change throughout the life cycle of the Initiator. Provider Registration Scope A string value as defined by the relevant ecosystem profile. SSA Relates to a Software Statement Assertion 3. Introduction Describes the operation of an ecosystem and other mechanisms for controlling admission of participants. This specification describes a technical mechanism for a group of cooperating participants to establish a central source of truth of the permitted participants. In addition, it describes means and methods for participants to discover the existence of others, track the status of these participants and provide metadata of how to describe them to other participants. _Note:_ This specification is heavily influenced by the original definition in the [CDS] but avoids ecosystem specific statements in favour of relying on the respective ecosystem and [DATARIGHTPLUS-ROSETTA] to provide elaboration. 4. Ecosystem Authority The Ecosystem Authority is considered the primary arbiter of trust within the established ecosystem. In order to provide multiple layers of trust the Ecosystem Authority SHALL operate a combination of: 1. Ecosystem Certificate Authority ("Ecosystem CA"): An X.509 Public Key Infrastructure (PKI) compliant certificate authority 2. Ecosystem Directory ("Directory"): A set of APIs delivering metadata of participants 3. Ecosystem Signing Authority ("SSA Authority"): An X.509 JSON Web Signature ([JWS]) based signing authority 4.1. General Topology This specification outlines the requirements for the various components of a data sharing ecosystem. Low & Kolera Expires 4 October 2024 [Page 3] Internet-Draft DataRight+: Admission Control Baseline April 2024 +-------------------------+ +--------------------->| Ecosystem CA <---------------------------+ |Verify +-------------------------+ Verify| | +-------------------------+ | | | Directory |-----------------+ | | +---------->+-------------------------<-------+ | | | | +-------------------------+ | | | | | +---------| SSA Authority |<---+ | | | | | | +-------------------------+ | | | | | Provider | | Software SSA JWKS | |Initiator|Trigger | | Metadata | | Statement Retrieval| |Metadata |Directory| | | | Assertion (SSA) | | |Refresh | | | | | | | | | | | | | | | | | | | | | | | | v | | v | +-----------------------+ +------------------------+ | | O------------------------O | | | Initiator | | Mutual TLS Channel | | Provider | | | incl SSA registration | | | | |<--O------------------------O->| | +-----------------------+ +------------------------+ The components provided in this diagram are further stipulated in the sections that follow. 4.2. Ecosystem CA The Ecosystem Certificate Authority: 1. SHALL issue certificates of at least 2048 bits 2. SHALL issue certificates using the RSA encryption suite 3. SHALL enforce the certificate profile as specified for each participant 4. SHALL NOT issue certificates exceeding 365 days 5. SHALL issue participant certificates via an Intermediate CA 6. SHALL manage, maintain and publish a [RFC5280] Certificate Revocation List 7. SHALL support [RFC6960] OCSP endpoints 8. SHALL manage and maintain a suitable Certificate Practice Statement 4.3. Directory The Directory is a combination of protected and generally available endpoints. Low & Kolera Expires 4 October 2024 [Page 4] Internet-Draft DataRight+: Admission Control Baseline April 2024 4.3.1. Authorisation Server The Ecosystem Directory: 1. SHALL make available an OAuth 2.0 [RFC6749] authorisation server 2. SHALL authenticate the confidential client using private_key_jwt specified in section 9 of [OIDC-Core] 3. SHALL support discovery, as defined in [OIDC-Discovery]; The means by which participants acquires their relevant client_id is outside the scope of this document. 4.3.2. Resource Endpoints 4.3.2.1. Authenticated Directory Endpoints The Ecosystem Directory SHALL make available MTLS and Bearer token authenticated endpoint secured with a scope value of cdr:register (or other value specified by the Ecosystem Authority). As described further in [DATARIGHTPLUS-REDOCLY-ID1] the following authenticated endpoints SHALL be made available: +=====================================================+=====+ | Resource Server Endpoint | x-v | +=====================================================+=====+ | GET /cdr-register/v1/{industry}/data-holders/brands | 2 | +-----------------------------------------------------+-----+ Table 1 4.3.2.2. Public Directory Endpoints The Ecosystem Directory SHALL deliver the following unauthenticated and generally available endpoints, in accordance with [DATARIGHTPLUS-REDOCLY-ID1]: Low & Kolera Expires 4 October 2024 [Page 5] Internet-Draft DataRight+: Admission Control Baseline April 2024 +=============================================================+=====+ | Resource Server Endpoint | x-v | +=============================================================+=====+ | GET /cdr-register/v1/{industry}/data- | 1 | | holders/brands/summary | | +-------------------------------------------------------------+-----+ | GET /cdr-register/v1/{industry}/data- | 1 | | holders/status | | +-------------------------------------------------------------+-----+ | GET /cdr-register/v1/{industry}/data- | 2 | | recipients/brands/software-products/status | | +-------------------------------------------------------------+-----+ | GET /cdr-register/v1/{industry}/data- | 2 | | recipients/status | | +-------------------------------------------------------------+-----+ | GET /cdr-register/v1/{industry}/data- | 3 | | recipients | | +-------------------------------------------------------------+-----+ Table 2 4.4. SSA Authority The SSA Authority issues JSON documents, signed using JWS, containing verified metadata sourced from the Ecosystem Authority. In addition to scope values defined within relevant resource sets the SSA Authority shall also include the Provider Registration Scope. 4.4.1. SSA Attributes The unsigned SSA is a JSON document containing the following attributes: * iss: REQUIRED Contains the iss (issuer) value of the SSA Authority. Unless specified otherwise this is set to cdr-register * iat: REQUIRED The time at which the request was issued by the SSA Authority, expressed as seconds since 1970-01-01T00:00:00Z * jti: REQUIRED A unique identifier for the document * legal_entity_id: OPTIONAL The Initiator Entity Identifier * legal_entity_name: OPTIONAL Human-readable name of the Initiator Entity * org_id: REQUIRED The Initiator Brand Identifier * org_name: REQUIRED Human-readable name of the Initiator Brand * client_name: REQUIRED Human-readable name of the Initiator * client_description: REQUIRED Human-readable description of the Initiator * client_uri: REQUIRED Website address of the Initiator Low & Kolera Expires 4 October 2024 [Page 6] Internet-Draft DataRight+: Admission Control Baseline April 2024 * redirect_uris: REQUIRED List of URI for use as redirect_uri values in [OIDC-Core] authorisation establishments * sector_identifier_uri: OPTIONAL URI to be used as an input to the production of Pseudonymous Identifiers as described in section 8 of [OIDC-DCR] * logo_uri: REQUIRED URI referencing a logo of the Initiator * tos_uri: OPTIONAL URI referencing the Terms of Service of the Initiator * policy_uri: OPTIONAL URI referencing the Ecosystem Policy of the Initiator * jwks_uri: REQUIRED URI referencing the JSON Web Key Set [RFC7517] used by the Initiator for authentication purposes * revocation_uri: REQUIRED URI referencing the ICARE endpoint as specified within [DATARIGHTPLUS-SHARING-ARRANGEMENT-V1-00], if [DATARIGHTPLUS-SHARING-ARRANGEMENT-V1-00] is supported by the Ecosystem * recipient_base_uri: REQUIRED Base URI to use for Initiator provider endpoints * software_id: REQUIRED The Initiator Identifier * software_roles: REQUIRED Role identifier of the Ecosystem. The only permitted value is currently data-recipient-software-product * scope: REQUIRED A space-separated list of scope values permitted to be accessed by the Initiator 4.4.1.1. Example A non-normative example of an unsigned SSA: Low & Kolera Expires 4 October 2024 [Page 7] Internet-Draft DataRight+: Admission Control Baseline April 2024 { "iss": "cdr-register", "iat": 1571808111, "exp": 2147483646, "jti": "3bc205a1ebc943fbb624b14fcb241196", "client_name": "Mock Software", "client_description": "A mock software product", "client_uri": "https://www.mockcompany.com.au", "legal_entity_id": "3B0B0A7B-3E7B-4A2C-9497-E357A71D07C7", "legal_entity_name": "Mock Company Pty Ltd.", "org_id": "3B0B0A7B-3E7B-4A2C-9497-E357A71D07C8", "org_name": "Mock Company Brand", "redirect_uris": [ "https://www.mockcompany.com.au/redirects/redirect1", "https://www.mockcompany.com.au/redirects/redirect2" ], "sector_identifier_uri": "https://www.mockcompany.com.au/sector_identifier.json", "logo_uri": "https://www.mockcompany.com.au/logos/logo1.png", "tos_uri": "https://www.mockcompany.com.au/tos.html", "policy_uri": "https://www.mockcompany.com.au/policy.html", "jwks_uri": "https://www.mockcompany.com.au/jwks", "revocation_uri": "https://www.mockcompany.com.au/revocation", "recipient_base_uri": "https://www.mockcompany.com.au", "software_id": "740C368F-ECF9-4D29-A2EA-0514A66B0CDE", "software_roles": "data-recipient-software-product", "scope": "openid profile bank:accounts.basic:read bank:accounts.detail:read bank:transactions:read bank:payees:read bank:regular_payments:read datarightplus:registration" } 4.4.2. Authorisation Server The SSA Authority: 1. SHALL make available an OAuth 2.0 [RFC6749] authorisation server 2. SHALL authenticate the confidential client using private_key_jwt specified in section 9 of [OIDC-Core] 3. SHALL support discovery, as defined in OpenID Connect Discovery 1.0 [OIDC-Discovery]; The means by which participants acquires their relevant client_id is outside the scope of this document. 4.4.3. Resource Endpoints Low & Kolera Expires 4 October 2024 [Page 8] Internet-Draft DataRight+: Admission Control Baseline April 2024 4.4.3.1. SSA Retrieval Endpoint The SSA Authority SHALL make available an endpoint for Initiators to download a compliant, time limited and cryptographically signed SSA which describes the Initiator themselves while asserting the authority of the SSA Authority. This endpoint will be available through an authenticated GET request to the path /cdr-register/v1/{industry}/data-recipients/ brands/{initiatorBrandId}/software-products/{initiatorId}/ssa and SHALL return a JWS signed string of the document. Once provided to any participant, the Initiator ID contained within the software_id attribute, SHALL NOT change for the lifetime of the Initiator. 4.4.3.2. SSA Authority JWKS The SSA Authority SHALL make available the public signing keys, in JSON Web Key Set [RFC7517] format, used for signing the SSA at the unauthenticated and generally available endpoint of GET /cdr- register/v1/jwks. 5. Provider In order to provide streamlined registration of Initiators the Provider must make available a service to facilitate registration of new OAuth 2.0 clients. 5.1. Authorisation Server The Provider authorisation server is required to perform a number of prescribed functions. 5.1.1. Dynamic Client Registration (DCR) The Provider authorisation server SHALL support [OIDC-DCR]. In addition, the Provider authorisation server: 1. SHALL require SSA documents as part of the Client Registration Request outlined in Section 3.1 of [OIDC-DCR] and; 2. SHALL validate provided SSA documents as per [SSA Attributes] and; 3. SHALL verify the signature of the SSA using the [SSA Authority JWKS] endpoint; 4. SHALL support client management endpoints described in Section 2 of [RFC7592]; Low & Kolera Expires 4 October 2024 [Page 9] Internet-Draft DataRight+: Admission Control Baseline April 2024 5. SHALL authenticate Initiators using private_key_jwt and an Ecosystem Authority defined scope value (typically cdr:registration); 6. SHALL require MTLS for all DCR related endpoints; 7. SHALL NOT permit multiple client registrations per Initiator Identifier; 8. SHALL supply client_id_issued_at in addition to the other REQUIRED fields outlined in section 3.2 [OIDC-DCR]; 9. SHALL update Initiator statuses, at least every 5 minutes, by polling the GET /cdr-register/v1/{industry}/data- recipients/brands/software-products/status endpoint outlined in [Resource Endpoints] Where there are overlapping attributes between the dynamic registration request and the provided SSA, the content of the SSA SHALL take precedence. 6. Initiator Initiators participating in the ecosystem: 1. SHALL support endpoint discovery as specified in [OIDC-Discovery] 2. SHALL support dynamic registration in accordance with [OIDC-DCR] 3. SHALL retrieve a time-limited SSA, from the [SSA Retrieval Endpoint] and use it as the software_statement attribute for dynamic registration requests 4. SHALL support the client management provisions contained in Section 2 [RFC7592] 7. Implementation Considerations The use of OCSP Stapling within the CDR ecosystem is NOT RECOMMENDED. For MTLS endpoints, all participants MUST verify certificates used (client) and presented (server) are current and valid. This implicitly means all parties are required to utilise CRL or OCSP endpoints to maintain confidence in revocation status. 8. Normative References [CDS] Data Standards Body (Treasury), "Consumer Data Standards (CDS)", . [DATARIGHTPLUS-REDOCLY-ID1] Low, S., Kolera, B., and W. Cai, "DataRight+: Redocly (ID1)", . Low & Kolera Expires 4 October 2024 [Page 10] Internet-Draft DataRight+: Admission Control Baseline April 2024 [DATARIGHTPLUS-ROSETTA] Low, S., "DataRight+ Rosetta Stone", . [DATARIGHTPLUS-SHARING-ARRANGEMENT-V1-00] Low, S., "CDR: Sharing Arrangement V1 (00)", . [JWS] Jones, M., Bradley, J., and N. Sakimura, "JSON Web Token (JWT)", May 2015, . [OIDC-Core] Sakimura, N., Bradley, J., Jones, M., de Medeiros, B., and C. Mortimore, "OpenID Connect Core 1.0 incorporating errata set 1", 8 November 2014, . [OIDC-DCR] Sakimura, N., Bradley, J., and M. Jones, "OpenID Connect Dynamic Client Registration 1.0 incorporating errata set 2", 15 December 2023, . [OIDC-Discovery] Sakimura, N., Bradley, J., Jones, M., and E. Jay, "OpenID Connect Discovery 1.0 incorporating errata set 1", 8 November 2014, . [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, DOI 10.17487/RFC2119, March 1997, . [RFC5280] Cooper, D., Santesson, S., Farrell, S., Boeyen, S., Housley, R., and W. Polk, "Internet X.509 Public Key Infrastructure Certificate and Certificate Revocation List (CRL) Profile", RFC 5280, DOI 10.17487/RFC5280, May 2008, . [RFC6749] Hardt, D., Ed., "The OAuth 2.0 Authorization Framework", RFC 6749, DOI 10.17487/RFC6749, October 2012, . Low & Kolera Expires 4 October 2024 [Page 11] Internet-Draft DataRight+: Admission Control Baseline April 2024 [RFC6960] Santesson, S., Myers, M., Ankney, R., Malpani, A., Galperin, S., and C. Adams, "X.509 Internet Public Key Infrastructure Online Certificate Status Protocol - OCSP", RFC 6960, DOI 10.17487/RFC6960, June 2013, . [RFC7517] Jones, M., "JSON Web Key (JWK)", RFC 7517, DOI 10.17487/RFC7517, May 2015, . [RFC7592] Richer, J., Ed., Jones, M., Bradley, J., and M. Machulak, "OAuth 2.0 Dynamic Client Registration Management Protocol", RFC 7592, DOI 10.17487/RFC7592, July 2015, . Authors' Addresses Stuart Low Biza.io Email: stuart@biza.io Ben Kolera Biza.io Email: bkolera@biza.io Low & Kolera Expires 4 October 2024 [Page 12]