Scope at "API level" feedback from country market implementation

[bigludo7]

Problem description

The CAMARA-API-access-and-user-consent document defined purpose and scope. scope could be an API level.
First implementation feedback raised that scope at API level is an problem if some operations within this API, with same dpv, required distinct legal base type execution (for example one operation is under legitimate Interest whilst the other is under Consent legal base). In this case, for this market country implementation, for this situation, the rule is to work (only) at operation level.

Probably interesting to check if in other market country same rule applied.

Possible evolution
If this is a shared concern - We may specify this recommendation in the document ("if several legal base, for a same dpv, apply within an api, then the recommendation is to use scope only at operation level").

Alternative solution
Change nothing in the document and let the topic open for each market.

Additional context
Adopting this recommendation could have an impact on API evolution. Indeed, if an API is in production in a market, and scope is managed at api level, then we should refrain extension on this API (by adding a new operation for example or adding attributes) that required a distinct legal base that the current used. As such, this point is impacting all APIs so probably TSC consultation is required.

[eric-murray]

Hi @bigludo7

CAMARA should define the valid range of "purpose" values, scope values and the technical mechanism for the API consumer to signal their required scope to the API provider, all of which have been done or are in progress. The question is whether we need to say anything about which combinations are valid, or leave that to implementors and regulators (or maybe Open Gateway).

If I, as an API provider, receive a request for scope dpv:FraudPreventionAndDetection#sim-swap then I would currently interpret this as "give me (as defined by my client-id) access to all endpoints in API sim-swap for which FraudPreventionAndDetection is an approved purpose". This may be all, none or only some of the defined endpoints, and it is up to my implementation to restrict access to endpoints for which FraudPreventionAndDetection is not a valid purpose.

That increases implementation complexity, of course, so we could have a rule along the lines that "wildcard scopes can only be requested when the specified purpose is valid for all API endpoints". That would allow API implementors to reject wildcard scopes when they are not valid for all the defined endpoints, which is much simpler.

One final comment. For some APIs, such as device-status, the endpoints give completely different types of information, so we cannot make the assumption that an end-user must have consented to either all or no endpoints. If we ask an end user to agree to share their roaming status with a bank for FraudDetectionAndPrevention purposes, I think it unreasonable to also ask them to share their connectivity status as part of a common consent agreement. So they may have only consented to a subset of the APIs endpoints. This also increases the complexity of implementing wildcard scopes.

[Elisabeth-Ericsson]

Hi @eric-murray,
my view is that CAMARA should (actually must) define the valid range of scope values per API.
May be we can do this also for purpose ranges, but we have the complication that the purpose values are use case dependent - and the use cases come with the applications...
However we have the need to configure the applicable legal basis on the pair of {purpose and scope} - this is jurisdiction dependent and might differ from Service Provider to Service Provider. The configuration of the legal basis might even be application or application type dependent.

This is also the reason why "wildcard scopes" actually complicate the handling instead of simplifying. I fully agree to your view that in general API endpoints give access to completely different types of information, and consequently a user might not have given consent for all of them. We have opened issue #87 to allow using a list of scopes instead of the wildcard one. Then a selective handling is possible.

From discussions on issue #32, there is an agreement between Telefonica, Orange and DT to go with wildcard scopes. Maybe we should allow a scope list (as documented in #87) right from the start and not use the wildcard option to avoid these inconsistencies ?

[eric-murray]

Hi Elisabeth

my view is that CAMARA should (actually must) define the valid range of scope values per API.

Yes, and that is the agreement. All defined endpoints in an API must have an associated scope (the technicalParameter). But the API definition should say nothing about purposes, as we cannot predict all the purposes for which an API might eventually be used. In principal, any scope could be requested for any purpose, and it is for the API provider to agree whether the requested combination is acceptable. Many factors will affect this decision, with local regulation being the major one.

When an API consumer requires access to multiple API endpoints, then the current choices are (i) to request the scopes separately (with separate tokens) or (ii) request a wildcard scope so as to get a token with super-powers. This issue is just attempting to clarify the interpretation of wildcard scopes by the API provider.

I don't like the complexity of wild card scopes, but I also don't like making the API consumer request scopes separately. Allowing scope lists appears to be a reasonable solution, and I will comment in #87.

[eric-murray]

@Elisabeth-Ericsson

However we have the need to configure the applicable legal basis on the pair of {purpose and scope}

Can you define "we" and "configure" in this statement? If "we" is CAMARA and "configure" means "allow different API providers to use different authorisation flows for a given (purpose, scope) pair", then I disagree with that. That would make life very difficult for both aggregators and application developers.

If there is any possibility of opt-in or opt-out consent being required (which will be true for the majority of API endpoints in most jurisdictions), then a 3-legged flow should be used. The flow can be processed by the API provider according to their own interpretation of the legal basis for the provided purpose and scope - for example, one may require to check opt-in consent, another need to check opt-out consent and yet another (probably erroneously) might decide that they do not need to check either.

But this does not change the authorisation flow itself (only the internal execution) and the API consumer and, indeed, CAMARA, need know nothing about the legal basis under which the API provider is actually processing the end user data is being processed.

[murthygorty]

Great discussion. My view-points:

1. API family (subproject) vs API: Today, CAMARA has multiple APIs in the same subproject. API-Family --> [1..N]APIs --> [1..M] API end-points.
   Distinguishing this is important as each provider can slice and dice the APIs when they offer to developers to buy. A given developer who built an application X with a few APIs can still go to each operator, buy the appropriate APIs and get their app X to work.

2. scope at API vs scope at API end-point vs scope at attribute level.
   IMO, we should not expect Providers (Resource Providers) to support scope at attribute-level, this would make the ecosystem (configuration of app, runtime resource-mgmt experience for Providers and auditing in the future) VERY complicated. Cant imagine having a non-buggy system that checks a variety of attributes in the API call for scope along with appropriate auditability.
   On the other hand, if we are saying that "operation" == "end-point" or 'set of end-points', it may work. I also believe that the developer should simply be able to pass the 'api' (not family) in scope and authZ can simply reject if the developer is not authorized for the entire app. This may be the best of both worlds as developers can have simplicity for certain APIs as opposed to needing scopes for every API endpoint.
   Can we simply say either 'name of the api' or detailed 'end-point list' to start with? we can evolve in the future as necessary.

3. Purpose: 100% agree with the comments that Purpose cannot be pre-defined in CAMARA - it varies from Carrier to Carrier and should be flexible.
   In my opinon,

• Application defines the purpose(s) in confiiguration type, per API
• it can pass one of the purposes that have been configured, during runtime.

hope this helps.
cc: @gmuratk @shilpa-padgaonkar

[jpengar]

@bigludo7 I think we can close this issue now with the purpose management solution defined in ICM profile (https://github.com/camaraproject/IdentityAndConsentManagement/blob/main/documentation/CAMARA-Security-Interoperability.md#purpose), right? There will be no "API level" scope unless explicitly defined in the API Spec YAML file.

CC @AxelNennker @sebdewet

[bigludo7]

HI @jpengar - Yes we can close it as we have solved that. Thanks.

[jpengar]

Thank you @bigludo7.
@AxelNennker May I close it?

[murthygorty]

@bigludo7 I think we can close this issue now with the purpose management solution defined in ICM profile (https://github.com/camaraproject/IdentityAndConsentManagement/blob/main/documentation/CAMARA-Security-Interoperability.md#purpose), right? There will be no "API level" scope unless explicitly defined in the API Spec YAML file.

CC @AxelNennker @sebdewet

thank you @jpengar - just catching up to this. Which PR# will I see the latest changes you refer to above? is that on main or a particular tag? wanted to understand more when you say we wont have 'api level' scope.
I need to check our commonalities project to see if we are requiring/recommending scopes in yamls..

cc: @gmuratk @shilpa-padgaonkar @AxelNennker

[shilpa-padgaonkar]

@jpengar and @AxelNennker : I will open a PR in comms against the issue camaraproject/Commonalities#184 and document the agreement in design guidelines --

There will be no "API level" scope unless explicitly defined in the API Spec YAML file.

as specified here #95 (comment)

Hope this is fine.

[jpengar]

@bigludo7 I think we can close this issue now with the purpose management solution defined in ICM profile (https://github.com/camaraproject/IdentityAndConsentManagement/blob/main/documentation/CAMARA-Security-Interoperability.md#purpose), right? There will be no "API level" scope unless explicitly defined in the API Spec YAML file.
CC @AxelNennker @sebdewet

thank you @jpengar - just catching up to this. Which PR# will I see the latest changes you refer to above? is that on main or a particular tag? wanted to understand more when you say we wont have 'api level' scope. I need to check our commonalities project to see if we are requiring/recommending scopes in yamls..

cc: @gmuratk @shilpa-padgaonkar @AxelNennker

There is a purpose management solution agreed for ICM release v0.1.0 Applying purpose concept in the authorization request which defines a technicalParameter that could be the API name to cover the whole API (and this API name is not described in the API spec YAML file as technical scope). The scope at "API level" (a.k.a "wildcard" scope) that @bigludo7 refers in this issue is that API name not defined in API Specs YAMLs files.

Now, for v0.2.0 (current release) the ICM working group has agreed a new solution for the purpose management which is documented in the new ICM Security and Interoperability profile. In this new solution, it is not defined any "API level" scope (say as "wildcard"). The scopes will always be those defined in the API Specs 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 Spec YAML file and agreed in the corresponding API subproject if it makes sense.

Therefore, the new purpose management solution addresses the issue raised by @bigludo7. So, I think we can close the issue.

[AxelNennker]

I also think we can/should close this issue.

@sebdewet @bigludo7 objections?

[murthygorty]

There is a purpose management solution agreed for ICM release v0.1.0 Applying purpose concept in the authorization request which defines a technicalParameter that could be the API name to cover the whole API (and this API name is not described in the API spec YAML file as technical scope). The scope at "API level" (a.k.a "wildcard" scope) that @bigludo7 refers in this issue is that API name not defined in API Specs YAMLs files.

Now, for v0.2.0 (current release) the ICM working group has agreed a new solution for the purpose management which is documented in the new ICM Security and Interoperability profile. In this new solution, it is not defined any "API level" scope (say as "wildcard"). The scopes will always be those defined in the API Specs 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 Spec YAML file and agreed in the corresponding API subproject if it makes sense.

Therefore, the new purpose management solution addresses the issue raised by @bigludo7. So, I think we can close the issue.

Thank you so much for the wonderful explanation @jpengar! For logistics purposes, while I know I dont get a vote, it certainly makes sense to close this particular issue. :-) :-)

I have some Qs to get clarity on the API scoping for 0.2.0 (whether we are requiring all apis to define this, is there a naming convention etc, etc.) What's the best way, should I open a new issue once I review the link from @jpengar (https://github.com/camaraproject/IdentityAndConsentManagement/blob/main/documentation/CAMARA-Security-Interoperability.md#purpose)