Decision Proposal 158 - Participant capability discovery

[CDR-API-Stream]

This decision proposal pertains to the consultation for a functional discovery mechanism pertaining to the DSB's Future Plan roadmap item published here: ConsumerDataStandardsAustralia/future-plan#5.

In the development of recent versions of the standards the ongoing need for the management of change across a multitude of participants at different velocities has become clear.

Specifically, this decision proposal is seeking to address how participants may discover the available functional implementation of another participant to improve interoperability and integration between two parties without reliance on whole-of-ecosystem release dates or inferring available capability by the presence of a response or endpoint version.

Having mechanisms that allow ADRs and DHs to advertise the features that they support at a granular level enables different participants to implement support for changes to the standards at different rates

The consultation draft Decision Proposal has been attached below:
Decision Proposal 158 - Participant capability discovery.pdf

Feedback is now open for this proposal. Feedback is planned to be closed on 5th March 2021.

[WestpacOpenBanking]

Westpac recommends Option B for metadata discovery, consistent with the existing approach for discovery of Base URIs. There are a number of advantages to this approach:

• There are low barriers to implementation, especially if APIs are available to make updates as a part of deployment processes.
• Participants can’t provide metadata consistent with accreditation conditions – this is a security benefit.
• The registry can apply consistent input validation and formatting between data holders.
• The API is authenticated. We do not recommend publicising certain types of data. For example:
  • Publicising developer support information may increase the risk of phishing attacks
  • Information about voluntary extensions may be commercially sensitive.
  • Previously we have also recommended that base uris are stored in the registry to avoid a risk of base path manipulation.
• Participants can use filtration functionality to identify relevant data holders for their software product before needing to perform client registration or other activity. For example they could search for banking or energy data holders only or for data holders that support a particular API version or above only.

Relative to Option B, option A introduces significant implementation effort for participants and greater likelihood of consistency issues. For the reasons stated above we do not recommend that an endpoint of this type is unauthenticated. We recommend against the use of ‘well-known’ as this may cause confusion with the OIDC configuration endpoint.

We do not recommend option A2 – frequent requirements to update SSA and client registrations introduces significant maintenance overhead.

Extension of OpenID discovery (Option C) is not recommended for two reasons:

1. Customization of standardized IAM products would be required. This may be technically infeasible for some data holders.
2. The endpoint is public (see our recommendations above on avoiding publicising certain types of data).

We recommend against support for advertising future capability as the option adds additional complexity and failed deployments or other issues mean that advertisements for future capability are unlikely to be reliable.

[mnot]

Hello,

Author of IETF's RFC8820/BCP190, 'URI Design and Ownership' and RFC8615, 'Well-Known Uniform Resource Identifiers (URIs)' here.

My understanding is that Option A proposes that the API establish structure in URIs such as /discovery/.well-known/cdr-configuration.

This is not sanctioned by RFC8615; well-known URIs are a carve out explicitly at the root, not in arbitrary parts of the path:

Well-known URIs are rooted in the top of the path's hierarchy; they are not well-known by definition in other parts of the path. For example, "/.well-known/example" is a well-known URI, whereas "/foo/.well-known/example" is not.

As such, this option would violate BCP190, in that it's a standard attempting to impose structure on other people's URIs. I grant that the damage incurred would be small, in that these are specialised services that are likely purpose-specific, and not widely deployed, but it's bad precedent for the CSIRO, and by extension the Australian government, to be violating Internet Best Current Practice.

As such, I'd recommend against Option A. If you do choose to go down that path, I'd ask that you remove the string .well-known, as it isn't serving any function, and will confuse (because this use by definition is not well-known, in the sense that it's globally registered), thereby diluting RFC8615.

[NationalAustraliaBank]

Mechanism of discovery:

NAB supports the approach described in Option A, but with the below changes

1. We recommend the removal of well-known from this URI.
2. We recommend this API is implemented as an authenticated endpoint. As such, we recommend this API to be restricted to participants within the regime inline with good security practices by following "deny by default".
3. We believe it is useful for ADRs to discover the metadata for another ADR. Is DSB intending to define standards for ADR-ADR interactions for this functionality only?
4. We believe the method of publishing metadata should be same for ADRs and DHs. Therefore, we do not support option A2. Instead, we recommend the approach mentioned in option A even for ADRs, where ADR hosts the discovery endpoint as they already host the revocation endpoint today.
5. We strongly oppose Option C.

Categories of discoverable metadata

We are supportive of having a metadata category but we are not sure whether all the categories listed in the paper are relevant or useful. Therefore, we recommend deciding on the minimum required dataset to begin with based on known use-cases and expand the categories later as required.

Timeliness of Metadata Availability

We recommend Option B: Publish new capability only when it is available as it provides greater flexibility to the participants and less change overheads as described in the paper. We are supportive of non-mandatory advertising of future capabilities.

[CDR-API-Stream]

Thanks @mnot, that's a good call out. The main differentiator with Option A is that it is an endpoint hosted by the Data Recipient / Data Holder that they can manage. It doesn't need to be under the /.well-known/ path to achieve this. The primary point is whether it is better for the participant to have the metadata hosted at a location they publish themselves.

[CDR-API-Stream]

Hi @NationalAustraliaBank thanks for the feedback.

We are supportive of having a metadata category but we are not sure whether all the categories listed in the paper are relevant or useful. Therefore, we recommend deciding on the minimum required dataset to begin with based on known use-cases and expand the categories later as required.

On the point related to what metadata participants provide, the table was presented as a starting point. We would welcome feedback on the content of the metadata that participants would see as useful or necessary to provide and a subsequent DP will then be used to consult on the schema for the metadata. If you have any views that can be expressed now with respect to metadata parameters and which categories are not applicable that would be useful.

[CDR-API-Stream]

Thanks for the feedback @WestpacOpenBanking, can you please clarify which option you are supportive of for the "Mechanism of discovery" and "Timeliness of metadata availability"? If the feedback is understood correctly, you are supportive of Option A for "Mechanism of discovery" provided it is not on the /.well-known/ path and you are supportive of Option B for "Timeliness of metadata availability" where metadata describes available capability, not planned/future capability.

[anzbankau]

Mechanism of discovery: Both options A and B offer some advantages, we do not support option C. Our preference is “Option B: CDR Register Participant Metadata API” as this builds on existing capability of the register without adding extra requirements on ADRs and ADHs. However further clarity would be needed on the mechanism for communicating this data from participants to the ACCC. This information could be provided and updated by participants to the registry through an expanded version of the existing CDR portal.

Timeliness of metadata availability: Our preference is “Option B: Publish new capability only when it is available”. This simplifies the approach for participants, which won’t have to worry about a variety of future dated items. Instead the discovery mechanism should be used by participant’s solutions dynamically to use functionality as it becomes available. This approach also gives more flexibility to participants to set the data at the appropriate time as part of release processes.

[commbankoss]

Commonwealth Bank has the following feedback on Decision Proposal 158:
Mechanism of discovery
We recommend using a combination of modified Option A: Data Holder hosted Resource Server Discovery Document for non-standard features only, and Option B: CDR Register Participant Metadata APIs is currently already used and should continue to be.
Categories of discoverable data
We recommend the number of categories be kept minimal, and only to data not already covered by the standards.
Timeliness of metadata availability
We support Option B: Publish new capability only when it is available. This is simpler for programmatic discovery.

[CDR-API-Stream]

Thank you to everyone who's put forward feedback. Consultation has been closed and feedback will now be reviewed and considered.