The concept of purpose

[jpengar]

Problem description

CC @sebdewet

Hi,

regarding the concept of purpose, we (Orange) would like to correctly understand the benefits to add the purposes to the OIDC standard. We already have a group component using the standard and there will be impacts in this case.
Our understanding is that if purpose is studied/proposed, it means that the standard with scopes isn't sufficient for all the use case needed in the camara perimeter.
However, we currently don't know which use case won't be covered by the standard. Or is it just in order to "provides a human-friendly description" ?
We also wonder if adding the purpose would complicate the standard with another layer to define, administer, manage changes, agree on vocabulary etc.

thank you in advance for the clarifications

Additional context
This is a technical challenge open to discussion.

[jpengar]

From our perspective, the OAuth `scope' is not defined to specify "how the resource/data will be used", but actually to "identify the resource to be accessed" (by using a given scope value when requesting access, you are actually requesting access to the set of resources + operations identified by that scope). That's why we see the concept of "purpose" (the reason why the resource/data is being accessed) as an independent concept.

But this issue is really important, because more than one purpose can be mapped to the same API resources/operations, as users may give consent to access those API resources for a functional motive, but not for a commercial/advertising motive, for example. By specifying the purpose in the authorization request, the Auth Server can only issue the appropriate access token if the user's consent has been previously registered for the application client and for the requested purpose.

We proposed to use a technical solution which must be indeed based on OIDC standard. But actually, OIDC does not go into detail about how the user consent should be handled and leaves it quite open. Introducing purpose concept on top of OIDC provides a technical solution which maps with "purpose" concept in GDPR law and allow applications to request an access token providing the reason why the corresponding API resources will be accessed. This is actually a very general concept, not only tied to GDPR and applicable to any country.

We are open to defining a new 'purpose' query parameter in the authorization request, as we originally suggested in a discussion held in Commonalities a few months ago, or we could agree on a technical solution to provide the name of the purpose in the existing standard 'scope' parameter (e.g. scope="purpose:xyz").

A purpose would be first provisioned in Operator side and configured to map to some specific OIDC scopes. Using this approach will allow to decouple the API definition from the user consent management or at least from the different usages that an application can make of an API/operation. Every time a new purpose is defined, you don't need to change the API definition, just provision that new purpose including the mapping for the allowed resources (allowed OIDC scopes) for that purpose. Using just OIDC scopes in the Auth request and defining N scopes for the same API/resource/operation would require to change API definition to add new scopes every time a new usage (with a new purpose) is defined for the applications. And the matrix would become increasingly complex.

Each API operation could be protected with a different scope (if required). This way you can actually control which scopes are allowed for a particular purpose, and eventually have enough granularity to control access for each API operation.

We do see benefits on the purpose approach proposed:

• Purposes can be easily defined with a JSON model and provisioned on Operator side. If new requirements arise you can just update the purpose definition to update resource mapping for example, or define new purposes and everything done by configuration without changing APIs definitions.
• As part of the purpose JSON model, you could also include other information, such as precise, user-friendly text to be displayed to the user during consent collection i.e. a human-friendly description of the purpose that the user can understand and agree to during consent collection (if required by the legal basis).
• You could easily control for example if the same API can be accessed or not depending on the usage the a same application want to do of that API by means of the purpose indicated by the application when requesting the access token.
• And purposes can map multiples scopes corresponding also to multiple APIs, so you could actually group all accessible resources under the same purpose definition.

But of course this is something that can be further discussed.

[sebdewet]

Hi,

as users may give consent to access those API resources for a functional motive, but not for a commercial/advertising motive, for example

the fact that the End-User will be given the option to have the OpenID Provider decline to provide some or all information requested by RPs is already in the standard, to share only phone and email and not address for example. The benefits would be to give consent to share email for commercial motive, and email and phone for another motive ? What would be the use cases associated to this functionnality ?

We are open to defining a new 'purpose' query parameter in the authorization request, as we originally suggested in a discussion held in Commonalities a few months ago, or we could agree on a technical solution to provide the name of the purpose in the existing standard 'scope' parameter (e.g. scope="purpose:xyz").

Could we already define the impact of each scenario ? pros and cons ?

Using just OIDC scopes in the Auth request and defining N scopes for the same API/resource/operation would require to change API definition to add new scopes every time a new usage (with a new purpose) is defined for the applications.

a new purpose will still be dependant of the existing scopes, thus I don't see the benefits.

You could easily control for example if the same API can be accessed or not depending on the usage the a same application want to do of that API by means of the purpose indicated by the application when requesting the access token.

same behaviour withs scopes ?

And purposes can map multiples scopes corresponding also to multiple APIs, so you could actually group all accessible resources under the same purpose definition.

I think i like this benefit, but could you detailed it ?

is the purpose is finally an equivalent of several endpoint as userinfo for example, which is a also multiple scope values ?

[jpengar]

the fact that the End-User will be given the option to have the OpenID Provider decline to provide some or all information requested by RPs is already in the standard, to share only phone and email and not address for example. The benefits would be to give consent to share email for commercial motive, and email and phone for another motive ?

As mentioned above, the `purpose' declares the reason why the application needs to process the personal data.
The OAuth scope(s) identifies the personal information resource to be accessed. Thus, it is not a matter of the Auth server simply granting or denying access to the requested scope(s) (or a subset of them) in the application's authorisation request, but doing so depending on the application's use of those resources. Thus, access would only be granted for a valid purpose that should be declared in advance.
Depending on the legal basis associated with that purpose, users may not need to give their explicit consent, but if so, access would be granted for a specific application under a specific purpose.

What would be the use cases associated to this functionnality?

It would apply to all use cases involving the processing of personal data.

Could we already define the impact of each scenario ? pros and cons ?

There is not much difference. They are simply two alternatives for declaring the purpose in the authorisation request. Using the "purpose" query param is something on top of the OAuth standard. Using the "scope="purpose:xyz" approach would simply avoid having to define a new query param on top of the current standard.

a new purpose will still be dependant of the existing scopes, thus I don't see the benefits.

The advantage is that you don't have to change the scope definition or affect the API definition. You can simply control it through configuration, declaring the new purpose and the scopes that will be accessible under that purpose.

same behaviour withs scopes?

As mentioned before, using scopes alone, you can only grant or deny access to the corresponding resources according to the policies defined by the Auth Server. But the purpose concept would allow you to do the same, but also take into account the specific use that the application will make of those resources. The access token would be associated with that purpose so that it could be audited and access granted only for valid purposes.

I think i like this benefit, but could you detailed it ?
is the purpose is finally an equivalent of several endpoint as userinfo for example, which is a also multiple scope values ?

A purpose is mapped to a scope or set of scopes. So, for applications that are allowed to request access under this purpose, if the authZ/authN process is completed successfully, they will receive an access token that grants access to the scopes that correspond to the declared purpose. And those scopes could correspond to more than one API operation and/or more than one API. This mapping is controlled by configuration.

[sebdewet]

Hi,

thank you for the answers.

I have two points.

First, I think that we currently use a way to define scopes in Orange which would correspond to the purpose, as precised in the model with the form_filling example below :

{
"scope_id : "form_filling"
"label":{
"fr": informations de mon compte"
"en": Your Orange account informations"
},
"description": {
"fr": "j'autorise Orange à transmettre mes données pour créer un compote ou remplir un formulaire.",
"en": "This data can be used to create an account or fill a form."
}
}

This way, we show the User why he shared his informations and with which purpose.
This scope correspond to claim(s) which are known on the Resource server side.
It allows us to get the label and description of each scopes for several langages.
Thus, when a user visit a partner who ask for consent, for each scope we show the description of why the user have to share informations with the partner.
That's why on Orange side, we don't see the benefits of purpose as we already use a way to add the "why" and "what data will be used for"

The other point, is that for a Partner, several scopes can be asked. If we add purpose, how can we know on which scope the purpose correspond ? or do we have to call the API with one scope and several purpose ?

[jpengar]

@sebdewet We have had this same discussion in the past in Commonalities: Orange feedback from @bigludo7) and the response from Telefonica. And there we explained the benefits we see in our proposal, which are in line with what we've already mentioned above in this issue discussion.

It looks like you (Orange) agree with us (Telefónica) on the need to declare not only "what data" but also "why this data is processed" (a.k.a. the purpose). And as for the technical implementation, it would be great if you could provide more details about it (maybe with an API call flow example and how it works in Orange or similar), because I think that our technical proposals are not that far away from each other, but we see benefits of having the purpose as an independent entity decoupling it from API definitions and scope definition, and having a simple JSON purpose model also allowing us to standardize it in an easy way...

This way, we show the User why he shared his informations and with which purpose.
This scope correspond to claim(s) which are known on the Resource server side.
It allows us to get the label and description of each scopes for several langages.
Thus, when a user visit a partner who ask for consent, for each scope we show the description of why the user have to share informations with the partner.

How do you do the mapping between the scope_id (e.g. "form_filling" and usage "This data can be used to create an account or fill a form.") and the data that can be accessed with that scope_id? Could you provide further details?

[sebdewet]

Hi,

I also think that we converge on the fact to get the reason why the consent is given, and how data are used. That's why we said that scope is enough from our side, because it gives all the informations to the customer with the description and label of the scope. What we have to define is what the purpose would add.

If I come back to the benefits you listed before :

Purposes can be easily defined with a JSON model and provisioned on Operator side. If new requirements arise you can just update the purpose definition to update resource mapping for example, or define new purposes and everything done by configuration without changing APIs definitions.

scope (with label and description) are defined on the Authorization Server. Mapping between scope and claims (resource shared by the customer) is done on the Resource Server. If new requirements, RS can change the mapping with the new claims, and change the description of the scope on AS side. It seems to be the same impacts.

As part of the purpose JSON model, you could also include other information, such as precise, user-friendly text to be displayed to the user during consent collection i.e. a human-friendly description of the purpose that the user can understand and agree to during consent collection (if required by the legal basis).

On Orange side, these informations are defined on the label and description corresponding to a scope, as shown in my previous message.

You could easily control for example if the same API can be accessed or not depending on the usage the a same application want to do of that API by means of the purpose indicated by the application when requesting the access token.

We never seen this use case, would you have an example ? It means that with a purpose you can access to the resources, and with another purpose, you won't be allowed to access ?

And purposes can map multiples scopes corresponding also to multiple APIs, so you could actually group all accessible resources under the same purpose definition.

With your explanation, I understand that the access-token would get a purpose which is a group of scope, and would access to several API with the same token. It's just cosmetic, we also could have an access token with several scope embedded ?

From your last answer :

How do you do the mapping between the scope_id (e.g. "form_filling" and usage "This data can be used to create an account or fill a form.") and the data that can be accessed with that scope_id? Could you provide further details?

Mapping is done on the RS, claims correspond to the scope. If there is the scope form_filling, the resource Server will know that the json will contains the corresponding claims :

{
"sub": "USFPGN-200-i6jmJ/GFYJhkINg...Y/X7yA="
"updated_at" : "1457075253",
"name": "Sébastien Dewet",
"given_name": "Sébastien",
"family_name" : "Dewet",
"birthdate" : "1980-01-01",
"gender" : "male",
"address" : {
"formatted" : "55 rue Faubourg St Honoré\r\n75008 Paris",
"street_address" : "55 rue Faubourg St Honoré",
"locality" : "Paris",
"postal_code" : "75008",
"country" : "France"
},
"email" : "seb.dewet@orange.fr",
"subscriber_msisdn" : "+33(0)601020304",
"phone_nuber" : "+33(0)144332211",
"locale" : "fr-FR"
}

This is our pattern :
• Partner subscribe to an offer (ex: Form ID) and add a Button on his app tu use the API.
• Customer choose to fill the form with Orange data with the button. Partner call /authorize, a webpage opens to allow the customer to authenticate, the a webpage is shown to ask if user consent that the partner uses his information with label and description of the scope FormID.
• If several scopes are asked by the partner, several labels (if differents) and several description are shown
• If consent is given, AS stored the consent with all information about this consent. (incompatible with the flow 4 on the consent.md : https://github.com/camaraproject/WorkingGroups/blob/8a288dcd26c88496ced8a7dbf9321dd0aae2b8b0/Commonalities/documentation/Working/user-consent.md)
• authorization code is sent back to the partner who call /token endpoint
• Partner then use the access token to get resources from the RS, form_filling scope corresponding to claims which are sent back in the json and will be used to fill the form

I hope it's clear and helps to understand our way to use scope, how we define it, and get consent.

[jpengar]

I would like to add the following diagram, which summarises our proposal and hopefully helps you to better understand it and the benefits we have highlighted:

[shilpa-padgaonkar]

@jpengar Some questions from my side:

If each purpose has a legal basis and we are allowed to request multiple purposes, how are the following scenarios handled:

1. Out of the 3 stated purposes, two have legal basis as consent and one has legal basis as contract

2. Out of the 2 stated purposes, and both have legal basis as consent,

• is user asked for providing 2 different consents?
• what is when he agrees to one and denies the other?

[sebdewet]

Hi,

we discussed internally and conclude that we don't see enough benefits for adding the concept of purpose which is in our opinion included in our way to use scopes as detailed in the message above. There are several aspects leading to this conclusion :

Telefonica Benefits for Purpose :

• "Easy to define and provision on operator side"
o Already in use with label and description defined for a scope on orange side, which respects the GDPR
o Scope is an offer corresponding to one or several resources, a purpose (description of scope) and a verb (rights)
o For a resource and a verb, there is a scope : a finality correspond to the purpose notion specified by w3c. Telco marketing team has to define the finality

• "Add information as user friendly text to display during capture"
o Corresponding to description and as to be detailed to the resource granularity

• "Purpose is map to N scopes"
o On Orange side, for one scope, it refers to resources (claims) actions (read, write) and purpose/finality (why)

• "Consent can be catch on each Purpose"
o Same on Orange side with descriptions of scopes

• "Purpose can evolve easily"
o See use case with socialmedia and evolution of resources + consent already given on a previous purpose

Disadvantage to add purpose to the existing standard :

• Standardization of purpose equal to standardization of Scope definition. The scope’s purpose need to correspond to GDPR.
o GSMA should defined a reference of the description of each scope to explain why you give consent for each offer (misdnverify etc.)
o There would be no technical impact, and scopes’ purpose would be manage with description and label. Each scope would have resources (claims) actions (read, write) and purpose/finality (why)

• Where to store link between scope and purpose/finality.
o Link between description (finality) and scopes are defined on AS side (as already in place in Orange AS)
o Description can be defined by the marketing over the GSMA reference for the scopes’ purpose

• Link n-n between scopes and purpose
o Example : fraud prevention and geolocalised ad can be purposed for the scope device-location but also for simswap, device status etc.
o Add a scope to a purpose need to create a new Purpose or a new version of the existing Purpose

• Standard modification to adjust add of purpose in header or body
o Why do we keep the scope if there is only one value (openid) ? scope attribute become useless and replaced by purposed. And thus purpose can be named scope

• Linked a purpose to a scope is inefficient, scopes will evolve (see socialmedia example below)

• Risk : if a consent has already been given on a Purpose, and scopes linked to purpose are added, token has to be revoked for this Purpose as User gave his consent on the legal basis defined previously

• IETF will need better benefits to evolve the OIDC standard.

• Consent has do be given on the shared resource and not only on the purpose/finality. We have to display which resources the user consent to share (ie : an e-mail address, a location of his device…) and not only why the user consent and what the partner will do with these resources.

Example on Purpose (w3c) Socialmediamarketing :
RS has a socialmedia id, User consents to share it for a purpose/finality to a partner.
If there is a new socialmedia (mastodon to replace twitter for example), a new claim is defined on RS side. A new scope has to be declared, and if there is a purpose, have to be added to the purpose.
Thus Purpose has to evolve to specify that this resources will also have to be shared, and ask consent for. There is no benefits given that Purpose will be as related to the shared resource as the scope is.

I hope it's clear and helps to understand our opinion.

[jpengar]

@shilpa-padgaonkar

Some questions from my side:
If each purpose has a legal basis and we are allowed to request multiple purposes, how are the following scenarios handled:

In fact, there are several possibilities for this type of scenarios, and eventually a common policy could be agreed in CAMARA to control them.

Of the 3 purposes mentioned, two have a legal basis of consent and one has a legal basis of contract.

In this case, you would have to record both consents. And there may be other factors such as user experience to decide what to do, for example it may not be convenient from a user experience point of view to see a very long text or a lot of information to consent to. So one way to control this, for a scenario like you ask, might be to only accept one purpose in the auth request when user consent is required. But that is just an example, something that could be discussed. I think this is a general challenge, not specific to Telefónica's proposal.

Of the 2 stated purposes, both have a legal basis as consent,
What if he agrees to one and refuses the other?

Again, there may be different policies that could be agreed upon. But in this case, the Auth server can issue an access token that is only associated with the allowed purpose. The application could inspect the token to see what purposes have been granted. Or the Auth server could have an "all or nothing" policy, such as not issuing a token if not all purposes can be granted. Or we could all decide to simplify this kind of scenarios by allowing only one purpose to be requested at a time.

But I think these are common challenges, whatever the final agreed solution is, and we can decide to specify the Auth Server policy that is best suited to control these use cases if they are potentially needed. Limiting a purpose for access_token seems like a reasonable policy (also considering consent revocation scenarios for a given purpose).

[chrishowell]

Where this topic starts to not make sense to me is as part of the two+legged OAuth approach when we start talking about gaining consent for multiple purposes. Even if only one of the purposes is accepted by the end-user and included in the access token, as far as I'm aware, there's no way of the ASP telling the Resource Server which purpose they're intending to use that token for for it to be accepted/rejected; the limited scope is usually defined on each Resource endpoint (e.g. a create scope on a create endpoint).

Ignoring my concerns for a second around how Purpose works in OAuth/OIDC flows; if it does move forward, personally I'd favour just extending the scope field with the w3c purpose e.g., qod:IncreaseServiceRobustness, this would fit nicely into the existing standard and implementations, and allow CSPs to choose all the purposes that they support per-API without having to agree with each other.

[shilpa-padgaonkar]

@chrishowell : Not sure what you mean by 2-legged oauth approach for consent. As soon as user is in the picture, it's always 3-legged.

[jpengar]

@shilpa-padgaonkar @sebdewet @bigludo7

As agreed in the last bi-weekly call, please find below the proposed representative CAMARA APIs scenario regarding the definition and declaration of "purpose".

The agreed way forward is to get input on how to solve this practical scenario, using Orange's proposal and using Telefonica's proposal. In this way, the two solutions could be compared more easily and all participants could agree on the final solution (one of them or any other compromise solution in between that could be agreed).

---

CAMARA APIs access use case example - "purpose" Management

Use case description

• Two different countries (A and B) with different regulations
• Open Gateway (OGW) standardised product #1:
  • Defined purpose: FraudPreventionAndDetection
  • Defined accesible APIs:
    • SIM Swap API
    • Device Location Verification API
• OGW product #1 is accessible by both countries, but with different legal basis.
  • Country A: LegitimateInterest
  • Country B: Consent
• One year later, a new OGW product #2 is standardised:
  • Defined purpose: TargetedAdvertising
  • Defined accessible APIs:
    • Device Location Verification API (which is already specified and released and being used by OGW product #1)
• OGW product #2 is accessible by both countries, with the same legal basis.
  • Country A: Consent
  • Country B: Consent

Key points:

1. OGW products are standardised and have a defined purpose and API/s (and other things like the charging model, etc...).
2. Different countries may have different legal basis for the same purpose.
3. Use case where two different OGW products with two different purposes have access to the same API.
4. Use case where a product has access to multiple APIs.

Technical solution checkpoints

1. Authorization/Token request and response

   How Authorization and Token request and response would look like?

2. Auth Server required considerations

   • Information required to be defined and stored in Auth Server.
   • Auth Server acccess policies.

3. Resource Server required considerations

   • Information required to be defined and stored in Resource Server.
   • API specification scopes definition.