Internet-Draft DataRight+: Admission Control Baseline April 2024
Low & Kolera Expires 4 October 2024 [Page]
Workgroup:
datarightplus
Internet-Draft:
draft-authors-datarightplus-admission-control-latest
Published:
Intended Status:
Experimental
Expires:
Authors:
S. Low
Biza.io
B. Kolera
Biza.io

DataRight+: Admission Control Baseline

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.

▲

Table of Contents

1. Scope

This document specifies methods for the following:

2. Terms & Definitions

This specification utilises the various terms outlined within [DATARIGHTPLUS-ROSETTA].

Ecosystem Policy
A policy document specific to the ecosystem 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.

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

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:

Table 1
Resource Server Endpoint x-v
GET /cdr-register/v1/{industry}/data-holders/brands 2
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]:

Table 2
Resource Server Endpoint x-v
GET /cdr-register/v1/{industry}/data-holders/brands/summary 1
GET /cdr-register/v1/{industry}/data-holders/status 1
GET /cdr-register/v1/{industry}/data-recipients/brands/software-products/status 2
GET /cdr-register/v1/{industry}/data-recipients/status 2
GET /cdr-register/v1/{industry}/data-recipients 3

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
  • 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:

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

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];
  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)", <https://consumerdatastandardsaustralia.github.io/standards>.
[DATARIGHTPLUS-REDOCLY-ID1]
Low, S., Kolera, B., and W. Cai, "DataRight+: Redocly (ID1)", <https://datarightplus.github.io/datarightplus-redocly/?v=ID1>.
[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., "CDR: Sharing Arrangement V1 (00)", <https://datarightplus.github.io/datarightplus-sharing-arrangement-v1/draft-authors-datarightplus-sharing-arrangement-v1-00/draft-authors-datarightplus-sharing-arrangement-v1.html>.
[JWS]
Jones, M., Bradley, J., and N. Sakimura, "JSON Web Token (JWT)", , <https://datatracker.ietf.org/doc/html/rfc7515>.
[OIDC-Core]
Sakimura, N., Bradley, J., Jones, M., de Medeiros, B., and C. Mortimore, "OpenID Connect Core 1.0 incorporating errata set 1", , <http://openid.net/specs/openid-connect-core-1_0.html>.
[OIDC-DCR]
Sakimura, N., Bradley, J., and M. Jones, "OpenID Connect Dynamic Client Registration 1.0 incorporating errata set 2", , <https://openid.net/specs/openid-connect-registration-1_0.html>.
[OIDC-Discovery]
Sakimura, N., Bradley, J., Jones, M., and E. Jay, "OpenID Connect Discovery 1.0 incorporating errata set 1", , <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, , <https://www.rfc-editor.org/info/rfc2119>.
[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, , <https://www.rfc-editor.org/info/rfc5280>.
[RFC6749]
Hardt, D., Ed., "The OAuth 2.0 Authorization Framework", RFC 6749, DOI 10.17487/RFC6749, , <https://www.rfc-editor.org/info/rfc6749>.
[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, , <https://www.rfc-editor.org/info/rfc6960>.
[RFC7517]
Jones, M., "JSON Web Key (JWK)", RFC 7517, DOI 10.17487/RFC7517, , <https://www.rfc-editor.org/info/rfc7517>.
[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, , <https://www.rfc-editor.org/info/rfc7592>.

Authors' Addresses

Stuart Low
Biza.io
Ben Kolera
Biza.io