Documentation update with securitySchemes final agreement #93

jpengar · 2023-12-05T13:46:52Z

What type of PR is this?

Add one of the following kinds:

documentation

What this PR does / why we need it:

This PR is intended to include in the WG documentation the final agreement reached by the TSC and the WG participants on the securitySchemes and security of the CAMARA API specification, and the mandatory template for info.description, explaining to API customers why the API specification does not list specific grant types, and how to find out what authorization flows they can use.

Which issue(s) this PR fixes:

Fixes #57

Special notes for reviewers:

Changelog input

 CAMARA API Specification - Authorization and authentication common guidelines

Additional documentation

N/A

bigludo7

LGTM

diegogonmar

LGTM

eric-murray · 2023-12-06T11:44:55Z

documentation/CAMARA-API-access-and-user-consent.md

+```
+### Authorization and authentication
+
+CAMARA guidelines defines a set of authorization flows which can grant API clients access to the API functionality, as outlined in the document [CAMARA-API-access-and-user-consent.md](https://github.com/camaraproject/IdentityAndConsentManagement/blob/main/documentation/CAMARA-API-access-and-user-consent.md). Which specific authorization flows are to be used will be determined during onboarding process, happening between the API Client and the Telco Operator exposing the API, taking into account the declared purpose for accessing the API, while also being subject to the prevailing legal framework dictated by local legislation.


Document "CAMARA-API-access-and-user-consent.md" says nothing about client credentials, and yet that remains a valid authorisation scheme for some CAMARA API endpoints. When it was proposed that CAMARA adopt type: openIdConnect as the ONLY valid security scheme, this was justified on the basis that .well-known/openid-configuration allows client_credentials in the list of grant_types_supported. And yet here we have a reference to a document that does not "outline" this as a possibility.

So for the proposed text to be applicable, "CAMARA-API-access-and-user-consent.md" must be updated to list client credentials as a valid authorisation scheme for some scenarios.

Agree. This is a fair point. We will commit an update to clarify that client credentials is a valid authorization scheme for some scenarios.

Done in commit 4f09ec6

…narios

murthygorty

In terms and concepts, can you consider changing "User" term to "Subscriber" please? If approved and changed, we will have

End User -> human participant using the application (can be a parent or alternate delegate of the carrier-resource)
Subscriber -> subscriber of the telco operator, owner of the carrier-resource at hand. (eg., parent)

shilpa-padgaonkar · 2023-12-20T07:57:41Z

@jpengar: Instead of replicating all info from AuthN-AuthZ doc again in this document, may be it is easier to simply say that

CAMARA guidelines defines a set of authorization flows which can grant API clients access to the API functionality, as outlined in the document CAMARA-AuthN-AuthZ-Concept.md.

All possible grant types are already documented in this doc.

jpengar · 2023-12-20T09:19:10Z

In terms and concepts, can you consider changing "User" term to "Subscriber" please? If approved and changed, we will have

End User -> human participant using the application (can be a parent or alternate delegate of the carrier-resource)
Subscriber -> subscriber of the telco operator, owner of the carrier-resource at hand. (eg., parent)

@murthygorty This specific topic is not related to the original issue #57 or the content included in this PR. Would you kindly open a new issue to discuss this specific topic? thank you so much in advance.
I always encourage WG participants to keep the original scope of the discussion to avoid creating unnecessary dependencies, to keep the discussion focused on the topic, and to prevent the discussion from becoming deadlocked.

UPDATE: I just saw a new issue of OIDF (#98) that's pretty much related. We can move this discussion there.

jpengar · 2023-12-20T09:22:01Z

@jpengar: Instead of replicating all info from AuthN-AuthZ doc again in this document, may be it is easier to simply say that

CAMARA guidelines defines a set of authorization flows which can grant API clients access to the API functionality, as outlined in the document CAMARA-AuthN-AuthZ-Concept.md.

All possible grant types are already documented in this doc.

@shilpa-padgaonkar That document actually mentions additional grant types/flows to those considered and defined so far as a valid option to access CAMARA APIs: Auth Code Flow, CIBA, and Client Credentials.

shilpa-padgaonkar · 2023-12-20T10:52:56Z

@jpengar : That is indeed correct. My main concern is that we will soon get requests to cover more options here if not explicitly specified for eg. there might be a request to add details about PKCE or other possible extensions.

Another option would be that we keep the link as is, in your PR, but mention that details about possible extensions etc. can be found in the AuthN-AuthZ doc.

Also, for recommended flows under oauth2, just like client credentials we should also specify auth code flow.

jpengar · 2023-12-20T11:02:31Z

Another option would be that we keep the link as is, in your PR, but mention that details about possible extensions etc. can be found in the AuthN-AuthZ doc.

Also, for recommended flows under oauth2, just like client credentials we should also specify auth code flow.

@shilpa-padgaonkar Could you use the github.com change suggestion feature to add your suggestion to the current status of the PR? That way we avoid a trail and error process in case I don't fully understand your point. :S

shilpa-padgaonkar · 2023-12-20T11:48:11Z

documentation/CAMARA-API-access-and-user-consent.md

@@ -18,6 +18,11 @@ This document defines guidelines for telco operator exposure platforms to manage
    - [Authorization flows / grant types](#authorization-flows--grant-types)
      - [Authorization code flow (Frontend flow)](#authorization-code-flow-frontend-flow)


Suggested change

- [Authorization code flow (Frontend flow)](#authorization-code-flow-frontend-flow)

Detailed information on the below specified grant types (for eg. extensions to some of the grant types, links to original RFC documents etc.) is available in [CAMARA-AuthN-AuthZ-Concept.md](https://github.com/camaraproject/IdentityAndConsentManagement/blob/main/documentation/CAMARA-AuthN-AuthZ-Concept.md)

- [Authorization code flow (Frontend flow)](#authorization-code-flow-frontend-flow)

We cannot just put this paragraph there. You have to put it in the middle of the auto-generated index. When the document is saved, the index is regenerated and this change is lost.

If you want to include it, it might fit as a NOTE at the beginning of the Authorization Flows / Grant Types section.

Fixed in d20fe33

jpengar · 2023-12-21T13:26:29Z

@shilpa-padgaonkar @rartych @bigludo7 @eric-murray As agreed in the 20/12 WG meeting call, now that the PR has already addressed your change suggestions, could you do a final review to merge the PR and close the issue?

shilpa-padgaonkar

/LGTM

rartych

LGTM

AxelNennker

LGTM

murthygorty · 2024-01-02T17:43:12Z

@jpengar
about this, you are 100% right, PR comments should only be about the issue at hand. Thanks, will follow #98

Documentation update with securitySchemes final agreement

04267cc

jpengar requested review from diegogonmar, AxelNennker, bigludo7, hdamker and shilpa-padgaonkar December 5, 2023 13:46

jpengar requested a review from rartych as a code owner December 5, 2023 13:46

jpengar requested a review from sebdewet December 5, 2023 13:51

jpengar mentioned this pull request Dec 5, 2023

Align securitySchemes and security of CAMARA API specs with IdentityAndConsentManagement WG #57

Closed

bigludo7 approved these changes Dec 5, 2023

View reviewed changes

diegogonmar approved these changes Dec 5, 2023

View reviewed changes

eric-murray reviewed Dec 6, 2023

View reviewed changes

hdamker mentioned this pull request Dec 14, 2023

Align securitySchemes and security of QOD API spec with IdentityAndConsentManagement camaraproject/QualityOnDemand#244

Open

added client credentials as a valid authorisation scheme for some sce…

4f09ec6

…narios

murthygorty suggested changes Dec 19, 2023

View reviewed changes

jpengar mentioned this pull request Dec 20, 2023

Terms used in User Identity section in CAMARA-API-access-and-user-consent.md #98

Open

shilpa-padgaonkar reviewed Dec 20, 2023

View reviewed changes

added Shilpa's suggested text

d20fe33

shilpa-padgaonkar approved these changes Dec 21, 2023

View reviewed changes

hdamker approved these changes Dec 22, 2023

View reviewed changes

rartych approved these changes Dec 27, 2023

View reviewed changes

AxelNennker approved these changes Dec 27, 2023

View reviewed changes

jpengar merged commit 4741eaf into main Jan 8, 2024

Elisabeth-Ericsson mentioned this pull request Jan 9, 2024

Question to documentation update for security schemes #108

Closed

jpengar deleted the jpengar/issue-57-doc-update-securityschemes-agreement branch January 26, 2024 10:25

This was referenced May 22, 2024

Define a CIBA OpenAPI security scheme #157

Open

Resolution on where the documentation of ICM AuthN/AuthZ common guidelines for API specs must be located #160

Open

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Documentation update with securitySchemes final agreement #93

Documentation update with securitySchemes final agreement #93

jpengar commented Dec 5, 2023

bigludo7 left a comment

diegogonmar left a comment

eric-murray Dec 6, 2023

jpengar Dec 12, 2023

jpengar Dec 19, 2023

murthygorty left a comment

shilpa-padgaonkar commented Dec 20, 2023

jpengar commented Dec 20, 2023 •

edited

jpengar commented Dec 20, 2023 •

edited

shilpa-padgaonkar commented Dec 20, 2023

jpengar commented Dec 20, 2023 •

edited

shilpa-padgaonkar Dec 20, 2023

jpengar Dec 20, 2023

jpengar Dec 21, 2023

jpengar commented Dec 21, 2023

shilpa-padgaonkar left a comment

rartych left a comment

AxelNennker left a comment

murthygorty commented Jan 2, 2024

		@@ -18,6 +18,11 @@ This document defines guidelines for telco operator exposure platforms to manage
		- [Authorization flows / grant types](#authorization-flows--grant-types)
		- [Authorization code flow (Frontend flow)](#authorization-code-flow-frontend-flow)

	- [Authorization code flow (Frontend flow)](#authorization-code-flow-frontend-flow)
	Detailed information on the below specified grant types (for eg. extensions to some of the grant types, links to original RFC documents etc.) is available in [CAMARA-AuthN-AuthZ-Concept.md](https://github.com/camaraproject/IdentityAndConsentManagement/blob/main/documentation/CAMARA-AuthN-AuthZ-Concept.md)
	- [Authorization code flow (Frontend flow)](#authorization-code-flow-frontend-flow)

Documentation update with securitySchemes final agreement #93

Documentation update with securitySchemes final agreement #93

Conversation

jpengar commented Dec 5, 2023

What type of PR is this?

What this PR does / why we need it:

Which issue(s) this PR fixes:

Special notes for reviewers:

Changelog input

Additional documentation

bigludo7 left a comment

Choose a reason for hiding this comment

diegogonmar left a comment

Choose a reason for hiding this comment

eric-murray Dec 6, 2023

Choose a reason for hiding this comment

jpengar Dec 12, 2023

Choose a reason for hiding this comment

jpengar Dec 19, 2023

Choose a reason for hiding this comment

murthygorty left a comment

Choose a reason for hiding this comment

shilpa-padgaonkar commented Dec 20, 2023

jpengar commented Dec 20, 2023 • edited

jpengar commented Dec 20, 2023 • edited

shilpa-padgaonkar commented Dec 20, 2023

jpengar commented Dec 20, 2023 • edited

shilpa-padgaonkar Dec 20, 2023

Choose a reason for hiding this comment

jpengar Dec 20, 2023

Choose a reason for hiding this comment

jpengar Dec 21, 2023

Choose a reason for hiding this comment

jpengar commented Dec 21, 2023

shilpa-padgaonkar left a comment

Choose a reason for hiding this comment

rartych left a comment

Choose a reason for hiding this comment

AxelNennker left a comment

Choose a reason for hiding this comment

murthygorty commented Jan 2, 2024

jpengar commented Dec 20, 2023 •

edited

jpengar commented Dec 20, 2023 •

edited

jpengar commented Dec 20, 2023 •

edited