Allow ADRs to specify scopes for a Software Statement Assertion (SSA) to support cross industry software products

[AdatreeCDR]

Description

A common ADR use case may be personalised comparisons of products. This use case could span all supported industries in CDR. There are many comparison sites that exist today which help consumers find a better deal across a range of industries. In our view this would constitute a single software product for an ADR.

If the SSA for this product contains both banking and energy scopes then the energy scopes will not be in the list of supported scopes that is advertised via a banking data holder's authorization server metadata. It is expected that banking data holders will reject DCR attempts from ADRs whose software products contain unsupported energy scopes. Conversely we expect energy data holders to reject any SSA that contains banking scopes as they will not be advertised as supported.

Area Affected

Register APIs - Get Software Statement Assertion (SSA)

Change Proposed

Allow ADRs to specify the list of optional scopes they wish the SSA to contain through a scopes query parameter on the SSA endpoint. This will allow ADRs to tailor the SSA to match the supported scopes of data holders within an industry while allowing software products to span industries. This should also have no impact to data holder implementations. We would ask that this be considered a potentially urgent change.

[CDR-API-Stream]

@Adatree thanks for raising this change request.

This topic was discussed in the last Maintenance Iteration 10 session.

We'd like to handle this as two pieces of work.

1. What is the behaviour of a data holder when they receive registration requests containing authorisation scopes they do not support? #488 has been raised to cover this.
2. What are the use cases where data recipients require control over the authorisation scopes contained within their register issued SSAs? We can cover this topic in this change request.

During MI 10 we can plan resolution of these pieces of work.

[CDR-API-Stream]

The DSB proposes a mechanism to give additional control to the data recipient, describing how the industry path parameter applies to filtering authorisation scopes.   Data Recipients and their software product’s participation across industries can be derived from their CDR Register assigned authorisation scopes. This list of authorisation scopes is a proxy for what industries the data recipient can participate in, not necessarily what the software product has been built for.   The Get SoftwareStatementAssertion call can apply the industry path parameter as a filter to the authorisation scopes allowing the data recipient to register their software product's with a sub-set of authorisation scopes, categorised by industry.   Current authorisation scopes are categorised as follows:

Authorisation Scope ID	Category
profile	OIDC
openid	OIDC
bank:accounts.basic:read	Banking
bank:accounts.detail:read	Banking
bank:transactions:read	Banking
bank:payees:read	Banking
bank:regular_payments:read	Banking
energy:electricity.servicepoints.basic:read	Energy
energy:electricity.servicepoints.detail:read	Energy
energy:electricity.usage:read	Energy
energy:electricity.der:read	Energy
energy:accounts.basic:read	Energy
energy:accounts.detail:read	Energy
energy:accounts.paymentschedule:read	Energy
energy:accounts.concessions:read	Energy
energy:billing:read	Energy
common:customer.basic:read	Common
common:customer.detail:read	Common
cdr:registration	Registration

Banking and Energy are the only categories that align to industry; therefore, filtering needs to apply to only industry-specific scopes.  

The examples below assume all authorisation scopes for a particular category are assigned to the software product where the SSA is being retrieved. Authorisation scopes in the SSA will then apply as follows:

Industry Filter	Categories returned	Authorisation Scopes returned in SSA
Banking	OIDC Banking Common  Registration	profile openid bank:accounts.basic:read bank:accounts.detail:read bank:transactions:read bank:payees:read bank:regular_payments:read   common:customer.basic:read common:customer.detail:read   cdr:registration
Energy	OIDC Energy Common  Registration	profile openid   energy:electricity.servicepoints.basic:read energy:electricity.servicepoints.detail:read energy:electricity.usage:read energy:electricity.der:read energy:accounts.basic:read energy:accounts.detail:read energy:accounts.paymentschedule:read energy:accounts.concessions:read energy:billing:read   common:customer.basic:read common:customer.detail:read   cdr:registration
Telco   (There are no telco scopes assigned, therefore only industry sector agnostic scopes are returned)	OIDC Common  Registration	profile openid   common:customer.basic:read common:customer.detail:read   cdr:registration
All	OIDC Banking Energy Common  Registration	profile openid   bank:accounts.basic:read bank:accounts.detail:read bank:transactions:read bank:payees:read bank:regular_payments:read   energy:electricity.servicepoints.basic:read energy:electricity.servicepoints.detail:read energy:electricity.usage:read energy:electricity.der:read energy:accounts.basic:read energy:accounts.detail:read energy:accounts.paymentschedule:read energy:accounts.concessions:read energy:billing:read   common:customer.basic:read common:customer.detail:read   cdr:registration

This functionality will allow for the following:

1. Added flexibility giving data recipients control over which industry sectors apply to which software products.
2. Greater flexibility in the transition to a multi-sector CDR

Therefore, to have the most meaningful impact, a future dated obligation aligned to the Energy rollout of 15th November 2022 is recommended

[ACCC-CDR]

The ACCC has not been given enough time to review the above proposed change, noting that it was posted around 3 hours before the MI call. Our understanding of the Maintenance cycle is that we are now outside of the 4 week consultation phase and as such should not be introducing new scope.

The proposed change also does not seem to address the original issue and as such points to needing additional time to assess the use cases.

At this time we are unable to consider additional scope for the 15th of November timeline.

[AdatreeCDR]

Hi @CDR-API-Stream. Thanks for your work on this.

Banking and Energy are the only categories that align to industry; therefore, filtering needs to apply to only industry-specific scopes.

Can we ever see this changing? With Open Finance the assumption would be that some data holder brands will be banks and superannuation companies and will participate in the banking and finance industries, but not all industries. Correct me if I've misunderstood, but doesn't the above proposed solution only support an SSA that is suitable for one industry, or all industries, but not a subset of industries which is likely the norm?

[CDR-API-Stream]

The ACCC has not been given enough time to review the above proposed change, noting that it was posted around 3 hours before the MI call. Our understanding of the Maintenance cycle is that we are now outside of the 4 week consultation phase and as such should not be introducing new scope.

This feedback may indicate a misunderstanding of the maintenance process. The process is deliberately agile in nature and we seek to be adaptive to the needs of the community as much as possible. In this case the issue is related to others already in scope and has, in effect, been raised due to other work already in the iteration.

The fact that a solution was proposed 3 hours before the MI call is not an indication that a decision will be rushed. Any issue in the maintenance process may result in any of the following outcomes:

• No change
• A change incorporating feedback
• Deferral to a future iteration
• Escalation to a dedicated Decision Proposal

In this case, the last two outcomes are both possibilities if it ends up being contentious.

The proposed change also does not seem to address the original issue and as such points to needing additional time to assess the use cases.

This is a serious matter, but we can't actually action this feedback as we need to know why the proposed solution doesn't address the issue. It is not obvious that this is the case and more detail would help. Also, feedback indicating how the solution could be amended so that it does address the issue would be very valuable.

At this time we are unable to consider additional scope for the 15th of November timeline.

This is helpful feedback on implementation considerations. The reason for stating the 15th of November is due to the fact that this is the date that this will become an issue for participants. If capacity is a problem then guidance on a solution that can be provided would be helpful.

In any case, if this issue is to be resolved at some time after the 15th of November continued consultation on the best solution would still need to occur.

[CDR-API-Stream]

The proposed change also does not seem to address the original issue and as such points to needing additional time to assess the use cases.

There is an obvious gap in the understanding of the transitional friction when the Energy sector enters the CDR and lack of insight on the impacts to use cases where a data recipient seeks to create a new registration, or update a current registration, with a data holder brand.   During maintenance iteration 10, we have devoted analysis time to discuss anecdotal evidence that there will data holders who currently do not comply and determine what technical mechanisms may be used to help address this issue raised by @Adatree. However, the ACCC is uniquely positioned to provide insight into any impact this issue presents on the operational needs of the CDR. Issue #488 already sets the expectation that Data Holders should not reject registration creations and updates based on the presence of unsupported authorisation scopes, however, visibility of data holder support is opaque at best. If the ACCC does not see this technical solution as relevant for the Energy rollout scheduled for 15th November 2022, it would be beneficial to have some insight into this position.   Does this issue present a significant risk with the transition to Energy and if so, do ACCC’s operational and testing processes act as a sufficient control? ACCC’s insights are key to help determine the effectiveness of this solution and/or what other considerations should be made.

[CDR-API-Stream]

@AdaTree, thanks for your continued input on this issue.

This proposed solution only caters to single industries and all industries, not sub-sets. This is a known limitation and has been discussed in Maintenance Iteration 10.   DP 245 seeks to identify the problem space to help define how data recipient participation across sectors and features will be negotiated as the CDR requirements grow. This is where we are seeking to analyse a more complete picture. Your example of Open Finance is a good scenario to consider in DP 245 and we’d appreciate your contributions to feedback on that DP.   For now, this proposed solution would only be incremental in moving towards an end-state

[CDR-API-Stream]

Discussions in MI 11 have highlighted the following:

1. Based on the feedback from ACCC, https://github.com/ConsumerDataStandardsAustralia/standards-maintenance/issues/486#issuecomment-1091181317, a technical solution is not viable to address this issue in the energy go-live timeframe.
2. An operational rather than technical control to mitigate data holders who are non-compliant, is proposed by the ACCC.

Therefore, the following questions remain.

Is this functionality still required in the energy go-live timeframe? If an operational control addresses this issue (#507), there is currently little motivation to provide this functionality by energy go-live

What are the future requirements for data recipients specifying authorisation scopes? As highlighted in https://github.com/ConsumerDataStandardsAustralia/standards-maintenance/issues/486#issuecomment-1097472505, DP245 outcomes will contribute to defining how authorisation scopes will apply in the future state of the CDS.

[perlboy]

Isn't the quick solve here for the Register to use the optional x-v on the SSA endpoint to support issuing an older SSA without the new scopes? There isn't currently any cross sector Holders so as a fall back mechanism it's relatively easy for ADRs?

By way of example:

• GET /cdr-register/[...]/ssa with no x-v: Provide V3 SSA (Banking & Energy scopes)
• GET /cdr-register/[...]/ssa with x-v=2: Provide V2 SSA (Banking only scopes)
• GET /cdr-register/[...]/ssa with x-v=3: Provide V3 SSA (Banking & Energy scopes)

This way a Data Recipient can use their normal SSA retrieval mechanisms and if that doesn't work out specifically request an old SSA and try that with a Data Holder?

Seems to me the work effort required from the ACCC would be minimal and would get out things out of a bind from #507.

Edit: In fact the ACCC's own mock register seems to have this exact functionality so maybe V2 SSA retirement date is just extended?

Going forward the versioning mechanism could be used to add additional scopes but at least the sector introduction is relatively rare (ie. plenty of time for Holders).

[CDR-API-Stream]

@perlboy thanks for your input.

I'd like to adjust your example.

• GET /cdr-register/[...]/ssa with no x-v: Provide ~V3~ V2 SSA (Banking ~& Energy~ scopes)
• GET /cdr-register/[...]/ssa with x-v=2: Provide V2 SSA (Banking only scopes)
• GET /cdr-register/[...]/ssa with x-v=3: Provide V3 SSA (Banking & Energy scopes)

the optional x-v header defaulting to V2 will force participants to explicitly specify the x-v header if they wish to use V3, which will pave the way to move it to mandatory.

Implementing GET /cdr-register/[...]/ssa with x-v=2: Provide V2 SSA (Banking only scopes) logically aligns to the proposal in the above comment where the industry parameter filters the authorisation scopes. This begs the question as to whether filtering or configuring the scopes per API version is the more viable solution given the delivery constraints.

ACCC, Is there significant difference in implementation effort to explicitly specify the authorisation scopes per API version vs implementing the industry path parameter filter?

[ACCC-CDR]

The ACCC’s preference is to implement filtering of scopes via the API versions (i.e. the solution described in the above comment).

The ACCC requests that the following be specified in the Consumer Data Standards:

• v2 of GetSSA will only return Banking scopes.
• v3 of GetSSA will return all scopes independent of the industry parameter in the request.
• this design is strictly a workaround for the issue raised in #488 and should not be understood to set a precedent, either for the behaviour of this endpoint or more generally.

The Standards have not historically defined the behaviour of GetSSA with respect to scopes. The Register has returned all valid scopes at all material times. The very specific issue that arises here is providing the community with a workaround to suboptimal data holder behaviour with respect to unknown scopes. This behaviour is being addressed by a Standards change (see #507 and #488). What is therefore under discussion here is a workaround for a specific issue (additional scopes in an SSA causing certain data holders to throw errors) intended to apply for a limited time. The impugned data holder behaviour will become non-compliant and this workaround will be redundant once this issue is addressed.

Lastly, while x-v interpretation and the best mechanism to facilitate scope filtering have been discussed in the above comments it would be ideal to treat these as separate issues. While valid, they are extraneous to the matter at hand and the problem as described in @Adatree's change request:

If the SSA for this product contains both banking and energy scopes then the energy scopes will not be in the list of supported scopes that is advertised via a banking data holder's authorization server metadata. It is expected that banking data holders will reject DCR attempts from ADRs whose software products contain unsupported energy scopes.

[CDR-API-Stream]

Thanks all for your input.

Based on the feedback provided by the @ACCC-CDR and @perlboy, the DSB proposes the following

Proposal

The authorisation scopes returned in V1 and V2 of the Get Software Statement Assertion (GetSSA) endpoint will be explicitly defined as follows:

GetSSA Version	Categories returned	Authorisation Scopes returned in SSA
V1 & V2	OIDC Banking Common Registration	profile openid bank:accounts.basic:read bank:accounts.detail:read bank:transactions:read bank:payees:read bank:regular_payments:read common:customer.basic:read common:customer.detail:read cdr:registration

V1 & V2 of the GetSSA endpoint have the authorisation scopes specified and will NOT include authorisation scopes from the energy sector. This aligns to current behaviour and allows data recipients to retrieve SSAs without energy scopes if required

V3 of the GetSSA endpoint, sector-specific authorisation scopes will not be specified as all authorisation scopes will be returned.

---

Therefore, for the 15th November release of the Energy sector, the authorisation scopes to be returned from the GetSSA endpoint will be the following:

GetSSA Version	Categories returned	Authorisation Scopes returned in SSA
V1 & V2	OIDC Banking Common Registration	profile openid bank:accounts.basic:read bank:accounts.detail:read bank:transactions:read bank:payees:read bank:regular_payments:read common:customer.basic:read common:customer.detail:read cdr:registration
V3	OIDC Banking Energy Common Registration	profile openid bank:accounts.basic:read bank:accounts.detail:read bank:transactions:read bank:payees:read bank:regular_payments:read energy:electricity.servicepoints.basic:read energy:electricity.servicepoints.detail:read energy:electricity.usage:read energy:electricity.der:read energy:accounts.basic:read energy:accounts.detail:read energy:accounts.paymentschedule:read energy:accounts.concessions:read energy:billing:read common:customer.basic:read common:customer.detail:read cdr:registration

[CDR-API-Stream]

Changes have been staged at: https://github.com/ConsumerDataStandardsAustralia/standards-staging/pull/203

[perlboy]

This doesn't appear to outline what the default behaviour of the non-mandatory x-v is?

[CDR-API-Stream]

A default value of 1 is in the OAS but you are correct, we should have an explicit statement somewhere outlining this