Documentation update with securitySchemes final agreement

[jpengar]

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

[shilpa-padgaonkar]

@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]

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 (https://github.com/camaraproject/IdentityAndConsentManagement/issues/98) that's pretty much related. We can move this discussion there.

[jpengar]

@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]

@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]

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

[jpengar]

@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?

[murthygorty]

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