Add a "wildcard" scope to simplify authorization request for the complete API

[bigludo7]

Pushing this question on behalf of my colleague @GianlucaSS77

For Quality on Demand API, no scope at api level has been included in the swagger, section security; it appears just one specific for each endpoint. The API should be used under a unique scope too, as we think that all the endpoints can be used under the same legal basis. Having this "wildcard" scope is defined in our API design guideline here.

What about include this scope “quality-on-demand” for each endpoint & of course maintaining those defined at endpoint level?

Thanks

[jlurien]

Having a scope like this would allow clients to reduce the length of the the OIDC request: ...&scope=dpv:purpose quality-on-demand... instead of ...&scope=dpv:purpose quality-on-demand:sessions:create quality-on-demand:sessions:read quality-on-demand:sessions:delete quality-on-demand:sessions:update quality-on-demand:sessions:retrieve-by-device....

Nevertheless, operators must have the logic to support that an app allowed to request the global api scope may also request only certain granular scopes

[GianlucaSS77]

Hello,
just to add an additional comment: others CAMARA APIS like sim swap and device swap accept both options, api level scope and endpoint specific scopes, so the idea is to follow a common rule for all.

Thanks

[hdamker]

@GianlucaSS77 The common rule is currently defined within section 6.6.2 of the API Design Guide:

6.6.2. API-level Scopes (Sometimes Referred to as Wildcard Scopes in CAMARA)

The decision on the API-level scopes was made within the Identity and Consent Management Working Group and is documented in the design guidelines to ensure the completeness of this document. The scopes will always be those defined in the API specification YAML files. Thus, a scope would only provide access to all endpoints and resources of an API if it is explicitly defined in the API specification YAML file and agreed in the corresponding API Subproject.

This possibility was introduced in context of the first Identity and Consent Management guideline iteration which has enabled only one scope per authorization request. As this restriction no longer exists, there is also no general need for a coarse-grained "wildcard" scope anymore. And in particular not as a "wildcard" all endpoints of an API with the api-name as scope name as originally proposed and currently defined in sim-swap and device-swap. Especially for these APIs I personally don't like the coarse-grained scopes, as already the existing endpoints have different functionalities and an API consumer should only request an access token for the needed functionality (principle of least privilege).

Extensibility: API wide "wildcard" scopes will hinder the extension of APIs which additional endpoints which represent higher privileges and shouldn't be accessible with the existing scope(s).

Use in production: Wildcard permissions may be acceptable in isolated development environments where they enable rapid prototyping. However, these should never be promoted to production environments without proper refinement.

Interoperability: Some API providers have already indicated that they won't support wildcard scopes and grant access tokens for them. Therefore it is for interoperability reasons better not to define them in the first place.

[GianlucaSS77]

Hello @hdamker
Thank you very much for your answer

A couple of issues that I think must be taken into account to understand my position, which is not only guided by purely technical aspects or the needs of the data consumer (channel partner) but how the data owner (which in the end is the telco customer) perceives these accesses and how easy or complex is the management of acceptance or refusal (right of opposition both prior to consumption and later). The proliferation of multiple scopes within the same api and the impossibility of being able to alternatively manage a single scope per api, complicates access management and above all the end customer's understanding of the purpose of these accesses, as the combinations of purpose (more than 90 dpv options right now) +scope grow exponentially; the complexity of authorization management (the more granular the scopes, the more granular will be the affirmative or negative authorizations for each purpose) leads an end telco customer usually either to accept all purpose + scope or perhaps in most cases to deny them, making all efforts to maintain granularity useless.
To get the point across, a similarity is when for example you access a web page where cookies are displayed, the purpose of these and the providers of each one for their acceptance or denial. The more “scopes” are defined, the more likely it is that the end customer will perceive this management as complex and either accept all cookies or deny them all, making that granularity in the choice again not useful. It is a similarity, it is not the same context, but from an end customer point of view, the experience is the same.
There should be a balance between the consumer of the data and the management that the data owner should follow, it is a balance that I think should be met.

Reviewing some other CAMARA apis we also see a difference in criteria when defining scopes:

• For example in KyC 2 different swaggers (and API…) have been defined, each one with its own scope at endpoint level, which in the end is a scope at api level because there is only one endpoint. I am referring to kyc match and kyc fill in. In this case it has been preferred to split the swagger instead of keeping both endpoints in the same , each with its own scope. Here we understand that it is due to the differentiated regulatory legal basis, but it is a choice that differentiates this api from the others.
• In device swap and sim swap is what we said, there are both options, even in the latest versions (1.0.0.0 at least).
• In QoS profiling for example we see that the 2 endpoints of the same API have the same scope value, that is to say, although it is defined as scope at endpoint level, in reality it is a scope at api level, because it is the same for all the swagger endpoints.

Our need is based on fulfilling a balance between the consumer and the data owner: therefore in the case of QoD we see a lack of balance with respect to the telco customer. We see no problem for an aggregator/channel partner to configure the scope that the operator decides to use within the 2 options, at API level or at endpoint level... but we also defend the position that it is a telco's choice to use either the scope at API level or the scope at endpoint level, never both at the same time. In the preliminary phases of integrations with the aggregator there is always an exchange of technical information to enable the integration, and what we say is that in these conversations the choice of scope should be communicated.

Thanks!

[eric-murray]

Hi @GianlucaSS77

I think you are mixing the roles of "API consumer" and "end user" for CAMARA APIs.

If a scope request involves a "purpose", then consent from the end user to process their personal data usually must be obtained (i.e. if opt-in consent is required). That consent must be "freely given, specific, informed, and unambiguous". Whether that consent is for a set of individual scopes or a single "super" scope makes absolutely no difference to that process. The language used by the API provider to obtain that consent is up to them, but I doubt they will even mention the scope names in the text of consent request.

In a production environment, the API consumer is a bit of software written by an application developer, who must understand which scopes are required for each API endpoint they want to call. If only a single scope is defined per endpoint, the OAS syntax makes it really easy to determine which scope is required. The software itself does not care if the "scope" parameter is a single "super" scope, or a list of the individual scopes required for the access token.

Only in a non-production "sandbox" (as is usually made available by API providers in their developer portals) is the "API consumer" a real person, and the "end user" not a real person. In such an environment, I can see that wildcard scopes make it easier to try out such sandbox environments. There is nothing to stop the API providers defining wildcard scopes for a non-production environment as a courtesy to application developers trying out the APIs.

But for a production environment, wild card scopes make no sense at all.

[GianlucaSS77]

Thanks for your comment @eric-murray!
I'm afraid I disagree with you, especially with this sentence
"Whether that consent is for a set of individual scopes or a single "super" scope makes absolutely no difference to that process."

When you mention “ process” I think you are only taking into account the authorization flow and the service CAMARA API call, but there is also another important process, the management of the acceptance or denial access to a dataset that an end user (telco operator customer and I put this because I need to let understand all the people the perspective) can require prior to any authorization flow. In European countries where the GDPR must be covered, the end user must be able to execute his right of opposition to the access to his data also before an authorization flow, and even in cases where the legal basis is legitimate interest (i.e. accepted by default unless the end user expresses otherwise). This means that the operator must also offer to their customers (end users) a place where this right can be managed, outside the authorization and service API consumption flows as I mentioned.
So here it is not a matter of whether to include in a text the name of the scope or not (which is obviously not necessary), here the point is not overkilling the operator customer experience (end user) with complexities related to unnecessary multiple granular scopes. As I said before, it is a balance on both sides, the api consumer needs and the end user needs ( a good customer experience in this case)
I include one additional point to my reasoning, to support the fact that a scope at api level does make sense, in many cases I would say:
The legal basis that determines the way in which the access to the data is managed (its default value or the actions necessary for its collection), generally depends on 4 variables:

• the data set to which access is required
• the operation required over the data set,
• the purpose of the access and
• the recipient, the destination
  The first 2 variables usually correspond to the value that is defined for the scope at endpoint level (since the action is included in that scope), the third is the dpv purpose. When the action (variable 2) on the target dataset of the API is not determinant for the identification of the legal basis, it is when the scope at API level makes sense. Why? Because the action is not determinant and it does not make sense to complexify the access management in both the authorization flow and the process I mentioned at the beginning. This is the case of QoD: the action on the dataset we believe is not determinant in identifying the legal basis.
  Just to conclude, if it would not make sense to have scopes at API level, why we can find stable APIs where scopes at API level are accepted and others where they are not? The fact that they could be used for sandbox purposes should not been reflected in the specification from my point of view, this is a standard that has to be covered in all environment, and including in sandbox. If it only would make sense to have a scope at the endpoint level, why rules that avoid the use of the same scope for every endpoint in an API have not been defined and followed? We have examples that confirm this, in QoS profiling , we have the same scope for each endpoint of the APIs, even if the action over the data is different.
  Thanks!

[hdamker]

@GianlucaSS77 While not being a privacy legal expert nor an UX expert, but from an end user perspective I agree here as well with @eric-murray:

If you translate the two options

• ...&scope=dpv:purpose quality-on-demand... and
• ...&scope=dpv:purpose quality-on-demand:sessions:create quality-on-demand:sessions:read quality-on-demand:sessions:delete quality-on-demand:sessions:update quality-on-demand:sessions:retrieve-by-device...

into a text for end user they both end up in something like "xxx requests the permission to create, read, delete and update QoS sessions for your mobile connection to improve your service experience" (1). Something like "xxx requests permission for QoS sessions to improve your service experience" does not make sense, as it leaves out the "operation required over the data set" as you rightfully listed above. If the AP consumer does not request "update" the sentence will be easier, but the wildcard would still include this operation and you need to present it to allow the end user an "informed decision" if I'm not mistaken.

In short: the two options to express the "wildcard" scope are technically absolutely identical, as the wildcard scope would include all the operations. If you are allowed to present the wildcard scope in a certain form to the end user you should be allowed to present the set of all scopes in the same form to inform the user about the data set and requested (not necessarily: required) operations.

Regarding your other arguments:

• if it would not make sense to have scopes at API level, why we can find stable APIs where scopes at API level are accepted and others where they are not

That you have to ask in the API repositories who have introduces wildcard scopes, my opinion is that this has legacy reasons, see my comment above. In case of SimSwap it makes IMHO a difference if the requested scope is sim-swap:check or sim-swap:retrieve-date and I would actually discourage to request or grant both scopes at the same time (I suppose you need also two different sentences to explain the operations towards the end user).

• If it only would make sense to have a scope at the endpoint level, why rules that avoid the use of the same scope for every endpoint in an API have not been defined and followed? We have examples that confirm this, in QoS profiling , we have the same scope for each endpoint of the APIs, even if the action over the data is different.

I don't agree that the action is different in this example, both are "read" operations, in line with the guidelines regarding "Scope Naming" in combination with guideline to use POST instead of GET to be able to transport the query parameters within the request body (c.f. "POST or GET for Transferring Sensitive or Complex Data").

One final comment: for improvements of the overall CAMARA Guidelines you can open a discussion or issue within Commonalities or for the topic at hand better in Identify & Consent Management.

(1) as said, I'm neither a legal privacy expert nor an UX expert, so bear with me if this is to technically and can be presented more user friendly but still legally ok. Would be interested how you would present an API wildcard scope vs the same set of detailed scopes to an user differently.

[hdamker]

Closing the discussion as there were no further comments or questions.