Adapt info.description to Security and Interoperablity Profile

[AxelNennker]

What type of PR is this?

• correction

What this PR does / why we need it:

The issue #154 requests:

Clean up and update the CAMARA-API-access-and-user-consent.md document to reflect the latest profile decisions and/or to include references(*) to the new profile document where appropriate.

This PR updates the info.description section of CAMARA-API-access-and-user-consent.md that the information that API subgroups are requested to put into their OpenAPI yaml file points to the Camara Security and Interoperability Profile.

Which issue(s) this PR fixes:

Related issue: #154

[jpengar]

Could you explain why we need to change the reference pointing to ICM profile instead of CAMARA-API-access-and-user-consent.md? The content of CAMARA-API-access-and-user-consent.md is already aligned with the ICM profile, it provides a friendly description of the CAMARA defined AuthN/AuthZ flows, the technical rule set and it points to the ICM profile when needed. This info.description template is already included in multiple APIs and it would be necessary to change the content again in all of those subprojects. If it is changed, there should be a benefit.

[AxelNennker]

CAMARA-Security-Interoperability.md defines everything an API consumer and especially their developers and maybe SW-architects needs to know about getting an access token.
E.g.

• which optional CIBA parameters are ignored by the Camara AZ.
• how to get offline access
• ...

CAMARA-Security-Interoperability.md is THE document for API consumers and their developers should read.

I agree that CAMARA-API-access-and-user-consent.md is a "friendly description" not only of the flows but about what we want and mandate regarding consent.

But I think that technical documents like the API yaml file should reference technical and normative documents, which means info.description should reference CAMARA-Security-Interoperability.md

[jpengar]

CAMARA-Security-Interoperability.md defines everything an API consumer and especially their developers and maybe SW-architects needs to know about getting an access token. E.g.

• which optional CIBA parameters are ignored by the Camara AZ.
• how to get offline access
• ...

CAMARA-Security-Interoperability.md is THE document for API consumers and their developers should read.

I agree that CAMARA-API-access-and-user-consent.md is a "friendly description" not only of the flows but about what we want and mandate regarding consent.

But I think that technical documents like the API yaml file should reference technical and normative documents, which means info.description should reference CAMARA-Security-Interoperability.md

CAMARA-API-access-and-user-consent.md has been normative so far and now also refers to the ICM profile when needed. So I don't agree, as long as I don't see a real benefit in modifying the template just to change a reference when that guideline is already applied (and/or is being applied) in multiple API subprojects. But of course that's my personal opinion, let's see what other WG participants think.

[AxelNennker]

CAMARA-API-access-and-user-consent.md has been normative so far and now also refers to the ICM profile when needed. So I don't agree, as long as I don't see a real benefit in modifying the template just to change a reference when that guideline is already applied (and/or is being applied) in multiple API subprojects. But of course that's my personal opinion, let's see what other WG participants think.

As stated during the ICM meeting, the change is small and many subprojects did not adapt their documents, so have to touch them anyway e.g. to use the common security scheme. Every subproject knows that changes in guidelines in Commonalities and/or ICM might require them to adapt.

[shilpa-padgaonkar]

Almost all API files will undergo a change before the upcoming meta-release, as the release management group has recommended changes for the info object. The upcoming meta-release is a good opportunity to get the needed changes in across subprojects.

[jpengar]

Fair enough. LGTM.