Update SSA specification

[nils-work]

Description

This issue is being raised by the DSB at the request of the ACCC.

---

To participate in CDR, Data Recipients (ADRs) must register their Software Product as a client of a Data Holder by presenting a Software Statement Assertion (SSA) provided to them by the Registrar.

The CDR SSA specification provided in the Standards defines some fields as either optional or mandatory/required and whether they are "Modifiable" post-registration.

Some of these details are unclear and are currently preventing changes where they should be expected and possible.

Intention and Value of Change

To align the specifications of the SSA with ecosystem expectations and allow ADRs to update certain elements of their Client Registration where permitted by the Registrar.

Area Affected

• Software Statement Assertion (SSA)
• RegistrationProperties

Change Proposed

1. Specify the legal_entity_id and legal_entity_name fields as mandatory in the SSA as they will always be provided by the Register Get Software Statement Assertion (SSA) endpoint.
2. In the SSA Definition table, either:
   1. remove the "Modifiable" column, implying that all fields presented in an SSA are modifiable, or
   2. retain it and specify the following fields as being "Modifiable" to support registration updates:
      • iat
      • exp
      • jti
      • legal_entity_id
      • legal_entity_name
3. Remove the obsolete revocation_uri field, as this is now at a fixed location based on recipient_base_uri (<RecipientBaseUri>/arrangements/revoke).
4. Consider whether versioning of the SSA is required for Data Holders to support these changes, and an appropriate FDO to accommodate them (whether versioning is required or not).

For consideration

In conjunction with the above changes, the DSB also invites participants to provide feedback on the fields that are currently specified in the SSA Definition table as "to be presented" or for "display" during authorisation/approval:

• org_name
• client_name
• client_description
• logo_uri

Questions:

• Data Holders - Which fields are currently being displayed?
• Data Recipients - Which fields are expected to be shown?
• Should Data Holders be 'allowed' or 'required' to show certain values, noting that the rules state "a data holder must give... the name of the accredited person" (the legal_entity_name), and that client_description may be a long text string which may not be appropriate to display to a consumer during the authorisation flow due to limited screen sizes or cognitive load.

[perlboy]

I think there's a more fundamental question here, what is the actual purpose of non technical fields being in the SSA in the first place? In the beginning it was thought the SSA would be the only authoritative source of data and metadata sync would be status driven only. Then Get Recipients endpoint was implemented as optional... then the ACCC CTS required it to be accessed in order to pass.

I question whether essentially all metadata that is available at Get Recipients shouldn't be stripped from the SSA entirely on the basis Holders are already expecting it to be stored and sync'd every 5 minutes. That would reduce the SSA to only a technical registration process resulting in the following being the total list:

1. iss
2. iat
3. exp
4. jti
5. software_id
6. scope
7. sector_identifier_uri Optional
8. redirect_uris
9. jwks_uri
10. recipient_base_uri

That would implicitly mean the following fields would be moved to live with the rest of the metadata probably under RegisterDataRecipient.dataRecipientBrands.softwareProducts:

1. client_uri
2. tos_uri
3. policy_uri

That would mean the following fields are dropped:

1. legal_entity_id, available in RegisterDataRecipient.legalEntityId
2. legal_entity_name available in RegisterDataRecipient.legalEntityName
3. org_id available in RegisterDataRecipient.dataRecipientBrands.dataRecipientBrandId
4. org_name available in RegisterDataRecipient.dataRecipientBrands.brandName
5. client_name available in RegisterDataRecipient.dataRecipientBrands.softwareProducts[].softwareProductName
6. client_description available in RegisterDataRecipient.dataRecipientBrands.softwareProducts[].softwareProductDescription
7. logo_uri available in RegisterDataRecipient.dataRecipientBrands.softwareProducts[].logoUri
8. revocation_uri deprecated
9. software_roles currently pointless, even with future roles these would align with scopes, if they didn't we would be internationally broken

[ACCC-CDR]

The intent of this proposal is to rectify an issue that has been observed in the CDR ecosystem where an ADR that had undergone a business name change via the Australian Business Register, which has then been reviewed and reflected into the CDR Register by the Registrar had their Update Data Recipient Registration request rejected by some Data Holder Brands. The SSA definition has largely remained unchanged since 2021 after the introduction of version 2 of the getSoftwareStatementAssertion (SSA). Since then, a number of issues related to changes of the SSA like the Deprecation of revocation_uri in GitHub Register #188 and the legal_entity_id and legal_entity_name mutability in GitHub Register #178 have been discussed but have not yet been taken into the standard.

With the growth of the CDR ecosystem since 2021, we have observed some possible scenarios that were not a high priority back in 2021 but have since materialised in 2024. This proposed change is to address the concerns that ADRs which have undergone a legal entity name change or a merger with another ADR would be prevented from carrying out an Update Data Recipient Registration request with a number of Data Holder Brands due to said Brands implementing their CDR solution to enforce legal_entity_name and possibly legal_entity_id to be not modifiable after it is presented in an SSA.

We recognize that the suggestions provided in this ticket are valuable, however, implementing the proposal would necessitate substantial modifications to the SSA definition. If approved, this change would need to be designated as a Future Dated Obligation and require significant coordination to manage the resulting breaking change. Therefore, we aim to focus the discussion on identifying the best approach to enable Update Data Recipient Registration requests for ADRs that have undergone a name change while ensuring ecosystem compatibility is maintained. This was one of the factors considered with this proposal and we welcome feedback along this line. ACCC had raised Incidents against those Data Holder Brands that are blocking Update Data Recipient Registration request for the ADR rename scenario in the CDR Service Management Portal and we ask the relevant Data Holders to engage with ACCC and the impacted ADR in a constructive manner to resolve the issue while this GitHub is being discussed and considered.