Unify specification of securitySchemes, security and scopes

[jlurien]

Problem description

Currently, there is no consistency across WG regarding definition of the securitySchemes types, and about providing and naming scopes to protect operations.

This table summarizes the situation, listing which securitySchemes are considered per WG, and which scopes are defined for that type (linked by means of security property):

WG	oauth2/ clientcredentials	oauth2/ authorizationCode	openIdConnect
AnonymisedSubscriberIdentifier	Without scopes	-	-
BlockChainPublicAddress (PR)	-	blockchain-public-address-read blockchain-public-address-create blockchain-public-address-delete	-
CarrierBillingCheckOut	Without scopes	carrier-billing-payments-create carrier-billing-payments-prepare carrier-billing-payments-confirm carrier-billing-payments-cancel carrier-billing-payments-read	-
DeviceIdentifier	Without scopes	-	-
DeviceLocation	Without scopes	location-verification:verify	-
DeviceStatus	Without scopes	device-status-roaming-read device-status-roaming-event	-
EdgeCloud	nbi-mgmt edge:discovery:read edge:serviceprofile:read edge:serviceprofile:write edge:serviceregistry:read edge:serviceregistry:write edge:traffic-influences:read edge:traffic-influences:write	-	-
HomeDevicesQoD	-	-	home-devices-qod-qos-write
NumberVerification (CAMARA)	-	-	number-verification-verify-read number-verification-share-read
OTPValidationAPI	one-time-password-sms:send-validate	-	-
SimSwap (CAMARA)	Without scopes	retrieve-sim-swap-date check-sim-swap	-
QualityOnDemand	Without scopes	qod-sessions-read qod-sessions-write qod-sessions-delete qod-profiles-read	-

Possible evolution

Unify specification of securitySchemes, security and scopes across all WGs with common guidelines. Exceptions to the guidelines should be avoided and justified.

Use of openIdConnect for securitySchemes

Generally, OpenID Connect is the protocol to be used for securitization. Each API spec will define the following entry in securitySchemes, as shown in CAMARA-AuthN-AuthZ-Concept.md document:

components:
  securitySchemes:
    openId:
      type: openIdConnect
      openIdConnectUrl: https://example.com/.well-known/openid-configuration

The value for openIdConnectUrl in the CAMARA spec is an example, that must be substituted by the specific discovery endpoint for OIDC protocol of the API provider, when the API is exposed in one of its environments.

Use of security property

Generally, each operation will be protected by a scope and it will include a security property with a single element in the array:

paths:
  {path}:
    {method}:
      ...
      security:
        - openId:
            - {scope}

The key is arbitrary in OAS, but convention in CAMARA is to name it openId. This key must be same defined in the components.securitySchemes section.
The {scope} is the specific scope defined to protect this operation. It must follow the syntax specify below.

Scope naming

Define a scope per API operation with the structure:

api-name:[resource:]action

where

• api-name is the API name specified as the base path, prior to the API version, in the servers[*].url property. For example, from /location-verification/v0, it would be location-verification.

• resource is optional. For APIs with several paths, it may include the resource in the path. For example, from /qod/v0/sessions/{sessionId}, it would be sessions.

• action: There are two cases:

  • For POST operations with a verb, it will be the verb. For example, from POST /location-verification/v0/verify, it would be verify.
  • For CRUD operations on a resource in paths, it will be one of:
    • create: For operations creating the resource, typically POST.
    • read: For operations accessing to details of the resource, typically GET.
    • update: For operations modifying the resource, typically PUT or PATCH.
    • delete: For operations removing the resource, typically DELETE.
    • write : For operations creating or modifying the resource, when differentiation between create and update is not neeed.

Examples

API	path	method	scope
location-verification	/verify	POST	location-verification:verify
qod	/sessions	POST	qod:sessions:create, or qod:sessions:write
qod	/qos-profiles	GET	qod:qos-profiles:read

[patrice-conil]

Hi @jlurien,
Nice work, I totally agree with you.

[PedroDiez]

Gathering main comments so far, raised during Commonalities 24/AGO meeting:

• Commented by @bigludo7:

How to deal with scenarios where a POST method is designed but really underlying API Logic is a "read" information process, Example: https://github.com/camaraproject/DeviceStatus/blob/main/code/API_definitions/device-status.yaml#L86

• Commented by @eric-murray

How to deal with scenarios where there is a fine-grained level rather than action. That is when within response resource information only a set of parameters/information has to be allowed to be returned.
Example: https://github.com/camaraproject/DeviceStatus/blob/main/code/API_definitions/device-status.yaml#L86, to allow the return only of the countryCode but not the countryName

Please, @bigludo7, @eric-murray do not hesitate to add/clarify any topic you may consider of relevance

[jlurien]

Gathering main comments so far, raised during Commonalities 24/AGO meeting:

• Commented by @bigludo7:

How to deal with scenarios where a POST method is designed but really underlying API Logic is a "read" information process, Example: https://github.com/camaraproject/DeviceStatus/blob/main/code/API_definitions/device-status.yaml#L86

If the endpoint represents a resource with several CRUD operations, I would add the CRUD action, but if it is a path with single operation and it is not expected to have more operations on it, I think that the CRUD action is not necessary.

For the example, POST /device-status/v0/roaming, probably device-status:roaming is enough, but if it is expected to have other operations for the same path, we may use device-status:roaming:read as conceptually it is an operation to read information.

• Commented by @eric-murray

How to deal with scenarios where there is a fine-grained level rather than action. That is when within response resource information only a set of parameters/information has to be allowed to be returned.
Example: https://github.com/camaraproject/DeviceStatus/blob/main/code/API_definitions/device-status.yaml#L86, to allow the return only of the countryCode but not the countryName

Please, @bigludo7, @eric-murray do not hesitate to add/clarify any topic you may consider of relevance

I think we don't still have those use cases. but if needed we may apply a further level to the scope, such as api-name:[resource:]action[:detail].

For the example, POST /device-status/v0/roaming, we may have as many scopes as individual parameters we may have: device-status:roaming[:read]:countryCode, device-status:roaming[:read]:countryName.

But this is something to discuss separately if needed. We may also think in the use of wildcards or other syntax.

[bigludo7]

Thanks @jlurien - I'm fine with this 2 added supplement.

[jlurien]

About the use of openIdConnect for securitySchemes, is there any concern?

[jlurien]

I will create a new PR to modify guidelines with this new proposal

[shilpa-padgaonkar]

To all participants in commonalities call:

In addition to this issue please provide your feedback on the below issue as well camaraproject/IdentityAndConsentManagement#57 as it would impact the PR

#57

[eric-murray]

How are CIBA flows specified within .well-known/openid-configuration? Can you give an example.

[jpengar]

How are CIBA flows specified within .well-known/openid-configuration? Can you give an example.

Please see camaraproject/IdentityAndConsentManagement#57 (comment), the example provided includes CIBA.

Further info: https://openid.net/specs/openid-client-initiated-backchannel-authentication-core-1_0.html#registration

[eric-murray]

Thanks @jpengar, so it is specified by including an extension grant in grant_types_supported.

Extension grant types are not specified by OAuth2, so this has both advantages (e.g. any grant type could be included there, even ones not invented yet) and a disadvantages (e.g. how would an API client know what might need to be supported without first calling the well-known endpoint? And if multiple grant types are specified, which of those applies to that API?).

When introducing the .well-known/openid-configuration requirement into the API specifications, these questions cannot be left hanging. The proposed schema should at least include a description of where the developer should look to answer these specific questions.

[chrishowell]

Please bear in mind with the .well-known that the caller may not know which CSP's .well-known to call to retrieve configuration at the time that the call is created.

[jlurien]

I copy here also my comment in camaraproject/IdentityAndConsentManagement#57 (comment)

In reality I doubt developers will go to any .well-known URL to discover anything. Before making any call to an API there will be an on-boarding process for developers where they have to register their applications, to consume certain APIs under certain purposes, accept T&Cs, exchange credentials, and as part of this procedure, the required grant_type and authn flows needed to consume the API have to be communicated, taking into account the purposes and regulation. This process is being designed in parallel, using TMForum APIs.

Here we are designing the APIs and as part of the OAS spec we have to complete security sections with something that is compliant to the spec but at the same time flexible enough to accommodate all possibilities. Scopes have to be standardized as a minimum, and openIdConnect as securityScheme allows to express this flexibilty. At the same time, we have to document all of this, and probably add some guidance or references in the APIs to let developers understand the whole process. This is what was agreed in the last TSC.

[eric-murray]

At the same time, we have to document all of this, and probably add some guidance or references in the APIs to let developers understand the whole process.

My suggestion was to make such guidance part of the boilerplate to be included in the API design guidelines by adding a template description to the definition of the security scheme. Otherwise sub-projects will just include minimal definition (this is already happening), which only tells the developer "this API will have security, but you won't find any details here".

If the details will be in a separate document, this document should exist before this security scheme formulation is adopted by APIs.

[jlurien]

At the same time, we have to document all of this, and probably add some guidance or references in the APIs to let developers understand the whole process.

My suggestion was to make such guidance part of the boilerplate to be included in the API design guidelines by adding a template description to the definition of the security scheme. Otherwise sub-projects will just include minimal definition (this is already happening), which only tells the developer "this API will have security, but you won't find any details here".

If the details will be in a separate document, this document should exist before this security scheme formulation is adopted by APIs.

I agree. It would be good to have something templated to be included as a section in every info.description, and leave the long explanations to a separate document that may be referenced if needed. Let's work on the details for that.

[ECORMAC]

In Number Verification (as Dawid pointed out in #61 above) we have adhered to the use of OIDC security scheme as per communalities guidelines. However OIDC as per standard would also entail the use / delivery of identity tokens. In our case (Number Verification) we don't see the need for identity tokens (but see the need for Authorization code grant). Is there some recommendation / principle from commonalities that we could use to both adhere to OIDC but not use / implement identity tokens?

[eric-murray]

@ECORMAC
Indeed there is no need for the identity token, but this is an issue for the Identity & Consent working group where such decisions are made. Commonalities are only codifying what is decided there within the API design guidelines.

[ECORMAC]

Thanks Eric, I'll join the discussion in the Identity & Consent working group.