search

camaraproject / IdentityAndConsentManagement

Repository to describe, develop, document and test the Identity And Consent Management for CAMARA APIs
Apache License 2.0
18 stars 30 forks source link

Adapt info.description to Security and Interoperablity Profile #168

Closed AxelNennker closed 3 weeks ago

AxelNennker commented 1 month ago

What type of PR is this?

What this PR does / why we need it:

The issue https://github.com/camaraproject/IdentityAndConsentManagement/issues/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: https://github.com/camaraproject/IdentityAndConsentManagement/issues/154

jpengar commented 1 month ago

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 commented 1 month ago

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.

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 commented 1 month ago

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.

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 commented 3 weeks ago

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 commented 3 weeks ago

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.