Scope definition for Client Credentials

[eric-murray]

Problem description I raised this as a discussion, but got no responses. So I am raising it as an issue.

The current CAMARA APIs Access and User Consent Management Guidelines say how to declare a purpose within a scope definition:

Applying purpose concept in the authorization request

In order to declare a purpose when accessing the CAMARA APIs, it is strongly recommended that the 'scope' parameter is set to: dpv:<dpvValue>#<technicalParameter>

but are not clear about when a purpose needs to be declared. In particular, there is no explicit definition of how scopes are constructed for authorisation using client credentials. It may seem obvious that the scope in this case should be the technicalParameter alone, but that does not appear to be defined anywhere.

Expected action It should be clarified that a purpose only needs to be defined when using the one of the OpenId Connect authentication schemes (grant_type equals authorization_code or urn:openid:params:grant-type:ciba) and not when grant_type equals client_credentials.

Additional context

[jpengar]

The CAMARA community agreement on 2-legged vs. 3-legged access can be summarised (as documented) as "Every time personal user data is processed by an API and the user can exercise his rights either via opt-in and/or opt-out, 3-legged access tokens must be used."

However, this is an independent debate on whether the purpose for which personal data is consumed should be declared when using client credentials (2-legged access).

From Telefónica's point of view, when personal data is processed, the purpose must always be declared (this is what the GDPR requires), regardless of the legal basis and whether it requires opt-in or the user can opt-out according to the local regulation that applies. And consequently, regardless of whether the use of "client credentials" is allowed.

[eric-murray]

However, this is an independent debate on whether the purpose for which personal data is consumed should be declared when using client credentials (2-legged access).

Indeed, the agreement on purpose for "3-legged access" does not apply to "2-legged access", hence my question.

My understanding is that 2-legged access tokens (i.e. client credentials) should only be used when no personal data is being "consumed". In which case, no purpose should be declared, and only the technicalParameter (as defined in the API definition) should be included in the requested scope.

But this rule for scope construction is not specified anywhere, and others may have different opinions, hence my question.

[jpengar]

@eric-murray And what about the scenario where Client Credentials (2-legged access) is used to access an API that processes the user's personal data, but under a legal basis where the user cannot exercise his rights either by opt-in or opt-out? For example, legal obligation or contract.

[eric-murray]

@eric-murray And what about the scenario where Client Credentials (2-legged access) is used to access an API that processes the user's personal data, but under a legal basis where the user cannot exercise his rights either by opt-in or opt-out? For example, legal obligation or contract.

I had understood that "3-legged-access" must always be used in such scenarios, and hence client credentials was not applicable. From Authentication and Authorization Concept for Service APIs:

Out of the grants defined under OAuth2 we recommend:

• Client Credentials grant: (when user resource is NOT involved & the client belongs to confidential category)
• Authorization Code grant: (when user resource is involved)

Besides, changing the authorisation scheme between "3-legged" and "2-legged" dependent on whether or not the end user has "opt-in / opt-out" options for a particular purpose is a recipe for confusion. Regulations do change between countries, and can change over time. Developers will want a single authorisation scheme for a given API endpoint, valid for all purposes and applicable to all markets in which their code will be used.

However, even if client credentials are used for scenarios where an end user can be identified, that does not answer the question as to how scopes should be constructed for scenarios using client credentials where no end user can be identified. We can separate the "client credentials involving personal data" and "client credentials not involving personal data" scenarios if necessary.

[shilpa-padgaonkar]

I am not sure why purpose should be appended to scope when using client credentials and agree with @eric-murray that this is not explicitly mentioned in any of our documents.

[jpengar]

My understanding is that 2-legged access tokens (i.e. client credentials) should only be used when no personal data is being "consumed". In which case, no purpose should be declared, and only the technicalParameter (as defined in the API definition) should be included in the requested scope.

@eric-murray As stated before, from Telefónica's point of view, when personal data is processed the purpose must always be declared as required by GDPR. But we are ok with your comments above, i.e. Client Credentials grant type can be used only when no personal user data is processed, and then, in this case, we are ok with not declaring the purpose, and only the technicalParameter (as defined in the API definition) in the requested scope.

I am not sure why purpose should be appended to scope when using client credentials and agree with @eric-murray that this is not explicitly mentioned in any of our documents.

@shilpa-padgaonkar A PR can be created to explicitly mention this in the documentation in Applying purpose concept in the authorization request

[HuubAppelboom]

Hi @eric-murray , @jpengar I think that what is meant by user resource in "Client Credentials grant: (when user resource is NOT involved & the client belongs to confidential category)" is that the user resource refers to whether the end user device is involved in the flow or not, not whether personal information is used in the flow.

In all cases where Legitimate Interest is used as a legal basis, there is often no interaction with the user device, so then you can use the Client Credentials grant. For example in the Netherlands (and I believe also in the UK), we accept most SIM Swap cases Legitimate Interest of the RP as a legal basis, and there is no user interaction in the flow. This may depend on you local market however, what the view of the regulator is on this.

In the contracts we make with customers we always define the purpose for which the data can be used, and both the RP and the MNO need to agree on this. It wouldn't hurt to add the purpose as an extra check parameter when Client Credentials grant is being used. In case the submitted purpose doesn't correspond to what has contractually been agreed, the requested can be denied.

[eric-murray]

@HuubAppelboom

I think that what is meant by user resource in "Client Credentials grant: (when user resource is NOT involved & the client belongs to confidential category)" is that the user >resource refers to whether the end user device is involved in the flow or not, not whether personal information is used in the flow.

No. It is not very well defined in CAMARA documents, but "resource" essentially means "data", and hence "user resource" means "data considered to be personal information of an end user". Generally, if an end user can be identified in the API request, then a 3-legged authorisation token must be obtained.

The end user device does not need to be involved directly, hence the CIBA option. Many CAMARA use cases involve obtaining information about an end user without the end user interacting with their device at all, and in those cases CIBA must be used, and a purpose must be specified in the scope.

@jpengar, @shilpa-padgaonkar As I opened this issue, I will create a PR to add a statement as to how scopes are constructed when using client credentials.

[HuubAppelboom]

@eric-murray But with all Camara API's there is user identifiable data (there is always an IP address or phone number used as an identifier), so that would imply that CIBA is required for all CAMARA api's ? Are there examples where Client Credentials can be used ??

[eric-murray]

@HuubAppelboom An example would be the QoD API GET /qos-profiles endpoint. No end user is identified, and so client credentials can be used to access this endpoint. There will be others, but it will not be common.

[HuubAppelboom]

@eric-murray Have you considered the performance impact this may have when you require 3 legged mandatory for API's like SIM Swap, Match and Scam Signal ? Often these need to be executed when timing is critical, and I suspect the CIBA flow will have quite some impact on this.

[eric-murray]

@HuubAppelboom Telefonica presented some latency performance estimates at a GSMA OGW meeting. Their estimates were:

• Client Credentials: 286 ms + API processing time
• CIBA: 321 ms + API processing time

So the conclusion was that the 3-legged approach only increased latency by one round trip delay. On this basis, the decision to mandate 3-legged flows for APIs involving end user data was made. I don't know if any description of their methodology or assumptions was made available to the GSMA for publication.

[HuubAppelboom]

@eric-murray For our current MC implementation we have about 300 ms for a client credential flow including API processing time for SIM Swap. Please note that the token call you only need to do once in a while, that saves quite some time.

For a front end flow for Number Verify we currently have about 700 ms. I expect that the CIBA flow has a similar if not more complexity, hence my concern.

Would be good to see whether anyone has implemented CIBA yet, and what their results are.

[eric-murray]

CIBA flow should be faster than front end flow because:

• There is no redirect request via the end user device
• Because all 3 legs originate from the same server, the same TLS session can be re-used

But yes, some "real world" performance results would be useful

[HuubAppelboom]

@eric-murray Please keepin mind there is also this polling mechanism in the CIBA flow, which adds to the processing time...