Closed jpengar closed 11 months ago
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:
But of course this is something that can be further discussed.
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 ?
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.
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 ?
@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?
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.
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:
@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:
Out of the 3 stated purposes, two have legal basis as consent and one has legal basis as contract
Out of the 2 stated purposes, and both have legal basis as consent,
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.
@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).
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.
@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.
@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).
#1
:
#1
is accessible by both countries, but with different legal basis.
#2
is standardised:
#1
)#2
is accessible by both countries, with the same legal basis.
Key points:
Authorization/Token request and response
How Authorization and Token request and response would look like?
Auth Server required considerations
Resource Server required considerations
@shilpa-padgaonkar @sebdewet @bigludo7 And, please find below, Telefonica's resolution proposal.
Authorization/Token request and response
How Authorization and Token request and response would look like?
DISCLAIMER: The scopes names provided in the examples, such as ogw:Product1:dpv:FraudPreventionAndDetection
are just for illustrative purposes. The actual scope name and format will be defined by the Open Gateway standardisation process.
OGW Product #1
POST /bc-authorize HTTP/1.1
Authorization: Basic {Credentials}
Content-Type: application/x-www-form-urlencoded
scope=ogw:Product1:dpv:FraudPreventionAndDetection&
login_hint_token=eyJ[…].efg[…].asW[…]&
…
POST /token HTTP/1.1
Authorization: Basic {Credentials}
Content-Type: application/x-www-form-urlencoded
grant_type=urn%3Aopenid%3Aparams%3Agrant-type%3Aciba&
auth_req_id=1c266114-a1be-4252-8ad1-04986c5b9ac1
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
{
"access_token":"2YotnFZFEjr1zCsicMWpAA",
"token_type":" Bearer",
"expires_in":3600,
"scope":"ogw:Product1:dpv:FraudPreventionAndDetection check-sim-swap retrieve-sim-swap-date location-verification-read",
…
}
OGW Product #2
POST /bc-authorize HTTP/1.1
Authorization: Basic {Credentials}
Content-Type: application/x-www-form-urlencoded
scope=ogw:Product2:dpv:TargetedAdvertising&
login_hint_token=eyJ[…].efg[…].asW[…]&
…
POST /token HTTP/1.1
Authorization: Basic {Credentials}
Content-Type: application/x-www-form-urlencoded
grant_type=urn%3Aopenid%3Aparams%3Agrant-type%3Aciba&
auth_req_id=1c266114-a1be-4252-8ad1-04986c5b9ac1
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
{
"access_token":"2YotnFZFEjr1zCsicMWpAA",
"token_type":" Bearer",
"expires_in":3600,
"scope":"ogw:Product2:dpv:TargetedAdvertising location-verification-read",
…
}
Auth Server required considerations
Information required to be defined and stored in Auth Server.
Essentially all the information required for the Auth Server to apply the necessary policies and logic for accessing OGW products.
DISCLAIMER: Each operator can implement this configuration internally on the Auth server side as they wish. As far as access from third party applications is concerned, they only have to worry about requesting access to the standardised OGW product scope.
There are other considerations such as the legal text to be shown to the user, that could also implemented inernally by the operator as they wish. The only requirement is that the legal text must be shown to the user before requesting access to the product when user consent is required.
Auth Server acccess policies.
Resource Server required considerations
The standard openAPI specifications of the CAMARA APIs remain the same no matter which product/purpose is defined or updated during the product lifecycle. The definition of OGW products (and purposes) is decoupled from the API specifications.
Hi, thanks a lot for the diagram and all the explanation.
In your example, is the purpose is send to the /authorize and the AS will then do the correspondance between the scopes "check-sim-swap", "retrieve-sim-swap-date", "location-verification-read" and add it in the token when the client ask for it ? Or the token will contains scope = FraudPreventionandDetection.
Our AS team still insist that we could use the data privacy vocabulary to standardize the scopes value, and Resource Server would know which data they have to share with the scope FraudPreventionandDetection.
Thus, SIM SWAP API, with check-sim-swap scope would only share true or false depending on the confirguration, and would share true or false and a date with a scope FraudPreventionandDetection.
In Orange Ecosystem, as a scope is a set
@sebdewet Please, take your time, but could you please provide Orange's solution proposal for the representative use case proposed above, as we have done from Telefónica in https://github.com/camaraproject/IdentityAndConsentManagement/issues/32#issuecomment-1643664809. In particular, answering the technical checkpoints mentioned, giving examples of what the authorisation and token request/response would look like, what the scopes defined in your solution would be, whether or not these scopes would be the ones to be included in the API specs, etc...
Only in this way we could properly compare Orange's proposal with Telefónica's, see the pros/cons, and all participants could agree on the final solution (one of them or any other compromise solution in between that could be agreed).
In your example, is the purpose is send to the /authorize and the AS will then do the correspondance between the scopes "check-sim-swap", "retrieve-sim-swap-date", "location-verification-read" and add it in the token when the client ask for it ? Or the token will contains scope = FraudPreventionandDetection.
As included in the example above this would be the content of the access_token obtained which includes all required scopes:
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
{
"access_token":"2YotnFZFEjr1zCsicMWpAA",
"token_type":" Bearer",
"expires_in":3600,
"scope":"ogw:Product1:dpv:FraudPreventionAndDetection check-sim-swap retrieve-sim-swap-date location-verification-read",
…
}
@jpengar : Hi Jesus, Thanks for adding your proposal to this issue. There seems to be some difference in the early explanation about purpose ( https://github.com/camaraproject/IdentityAndConsentManagement/issues/32#issuecomment-1600686112) and the latest one.
In the earlier comment, purpose was simply for eg "FraudPreventionAndDetection". Is product-name + Purpose ("ogw:Product1:dpv:FraudPreventionAndDetection") now supposed to be the purpose format?
Initially, purpose was not added to the scope. Is this now changed as a part of the latest proposal?
In the proposal, can one product have multiple purposes? Or does the proposal intend to create one unique product per purpose?
Thanks in advance for your response.
@shilpa-padgaonkar
There seems to be some difference in the early explanation about purpose ( https://github.com/camaraproject/IdentityAndConsentManagement/issues/32#issuecomment-1600686112) and the latest one.
Yes, we've tweaked the proposal a little as the discussion progressed, with the aim of bringing the positions as close as possible to those of our Orange colleagues and finding a compromise solution that makes sense for everyone.
In the earlier comment, purpose was simply for eg "FraudPreventionAndDetection". Is product-name + Purpose ("ogw:Product1:dpv:FraudPreventionAndDetection") now supposed to be the purpose format?
Initially, purpose was not added to the scope. Is this now changed as a part of the latest proposal?
Not necessarily. I included the disclaimer(+) to point out that the format of the OGW product scope is something to be agreed upon. I used this example because I thought it was quite illustrative and might actually make sense.
(+)DISCLAIMER: The scopes names provided in the examples, such as ogw:Product1:dpv:FraudPreventionAndDetection
are just for illustrative purposes. The actual scope name and format will be defined by the Open Gateway standardisation process.
In the proposal, can one product have multiple purposes? Or does the proposal intend to create one unique product per purpose?
We are not proposing how to define OGW products, that is done in other forums. We are proposing a technical solution that will hopefully be flexible enough to support whatever OGW product model is decided at business level. But as far as I know, each OGW product would have one purpose. That's what I've seen in the OGW product definitions so far.
@jpengar : Though initially the word used as example ogw:Product1 was a bit misleading, thanks to your clarification, we have now understood that it does not map to a commercial product. We are now fine with the proposal.
As discussed previously, here is our perspective from Orange (prepared with @sebdewet ).
We took same UC assumption than the one provided by Telefonica team above. As raised during our last discussion I got the feeling that we're not far from the technical perspective but not aligned on the initial assumption of the product definition. Happy to discuss this.
Catalog view : In the Use Case provided by Telefonica we have 2 APIs:
We have also 2 purposes:
We agreed that depending on the country regulation, the data provided by the API for a given purposes dictates a legal base, which can be LegitimateInterest or Consent for this UC.
The purpose list & legal base must be standardized within Open Gateway(OPGW) & CAMARA. The link between them is managed by Telco upon country regulations.
From Orange perspective we should not have a dedicated OPGW product per API/Purpose (as a reminder, the OPGW product describe the functional behavior of a CAMARA API, this is not the CAMARA API itself) . This model will create a multiplication of OPGW that will be confusing for all partners: application developer, aggregator, hyperscaler and the telco themselves. 12 APIs with 5 purposes makes 60 simple OPGW products and can get exponential for combined APIs…
Instead in our model we push for a unique OPGW product describing a CAMARA API. Then in the commercial layer (not in the scope of this discussion), the Telco is able to craft product offering at will as long as these product offering are strong type to OPGW product. Telco can craft product offering restrained on purpose for example.
Our catalog representation:
In this example:
Application onboarding view
Then, once an application developer wants to uses a telco API (directly or indirectly thru an aggregator/hyperscaler) we mandate that for an application the purpose(s) must be specified and part of the agreement. There are a hard link between application and purpose(s). The application developer mays directly browse Telco OPGW product (or via a marketplace), retrieve associated product offering, check commercial terms & conditions and then contractually agree (directly) or thru the aggregator to Telco product offering.
Our 'agreement' & 'ordering' representation:
In our example, the app 'owner' onboards to telco API with mandatory purpose. The app owner picks the offering based on required OPGW product depending on the Telco API availability.
Usage view
When the application triggers the API, the app request must provide both the purpose and the 'technical scope' (as defined in the standard CAMARA API), in the /authorize
request. For example in SimSwap we have 2 technical scopes: check-sim-swap & retrieve-sim-swap (both associated to an operation).
Note: The standard CAMARA API did not provide in securitySchemes a list of scopes with purpose but only ‘technical’ scope (scope relevant to data & action).
In our proposal, the application developer (or the aggregator/hyperscaler) will value the scope in the /authorize
operation with a concatenation of the <FraudPrevention:check-sim-swap-date
). From our perspective it will be easy for our consumers to provide this 'enhanced scope' as contractually the app ‘knows’ the purpose(s) and in the CAMARA swagger the technical scope are defined.
Example for application A (purpose FraudPreventionandDetection) making an authorization request for performing a SimSwap data check:
POST /authorize?response_type=code
&client_id={client_id}
&scope= FraudPreventionandDetection:check-sim-swap-date
&redirect_uri={your_application_callback}
&state={your_state}
The Authorization Server has to: • Manage this 'enhanced scope' to check it is allowed for this application given the agreement on-boarding, • Trigger required legal base process accordingly to country regulation, • Answer the request to the application.
With this proposal this is up to the Telco to manage this enhanced scope vs the technical scope defined in each CAMARA swagger and keep thing simple for our API Consumer that have to only concatenate purpose + technical scope.
Thanks @bigludo7. Here's the analysis of your proposal from Telefónica.
From Orange perspective we should not have a dedicated OPGW product per API/Purpose (as a reminder, the OPGW product describe the functional behavior of a CAMARA API, this is not the CAMARA API itself) .
An OPGW product does not necessarily have to be just one API. It could be just one API operation and one scope, a whole API with multiple scopes (like QoD), it could be N APIs, or even individual API operations of different APIs. The Telefónica proposal is 100% flexible in this sense and removes this dependency with the product definition.
This model will create a multiplication of OPGW that will be confusing for all partners: application developer, aggregator, hyperscaler and the telco themselves. 12 APIs with 5 purposes makes 60 simple OPGW products and can get exponential for combined APIs…
The number of products will be according to the OGW product catalogue, irrespectively of the tech solution we adopt to manage the purpose bound to the product. Of course, you won't need to have every possible combination of purpose and API. It doesn't work that way.
Then, once an application developer wants to uses a telco API (directly or indirectly thru an aggregator/hyperscaler) we mandate that for an application the purpose(s) must be specified and part of the agreement. There are a hard link between application and purpose(s).
This is outside the scope of the technical discussion, but according to the playbook and what is agreed in the business track, there will be a hard link between product and purpose in the model (not quite between application and purpose).
When the application triggers the API, the app request must provide both the purpose and the 'technical scope' (as defined in the standard CAMARA API), in the /authorize request. For example in SimSwap we have 2 technical scopes: check-sim-swap & retrieve-sim-swap (both associated to an operation). Note: The standard CAMARA API did not provide in securitySchemes a list of scopes with purpose but only ‘technical’ scope (scope relevant to data & action).
In our proposal, the application developer (or the aggregator/hyperscaler) will value the scope in the /authorize operation with a concatenation of the <>:<> (for example: FraudPrevention:check-sim-swap-date ). From our perspective it will be easy for our consumers to provide this 'enhanced scope' as contractually the app ‘knows’ the purpose(s) and in the CAMARA swagger the technical scope are defined.
From Telefónica's point of view, we don't see this as a simpler approach. You give an example of requesting just one scope, but for example for Carrier Billing you have 5 scopes and to fully access that API the developer would have to send a request like this:
POST /authorize?response_type=code
&client_id={client_id}
&scope= VendorPayment:carrier-billing-payments-create VendorPayment:carrier-billing-payments-prepare VendorPayment:carrier-billing-payments-confirm VendorPayment:carrier-billing-payments-cancel VendorPayment:carrier-billing-payments-read
&redirect_uri={your_application_callback}
&state={your_state}
The developer would need to know all the required scopes, concatenate them with the W3C purpose, and send them in the request. This is not simpler than sending the OGW standardised product scope in the request and letting the operator decide which scopes are required for that product according to the product definition, and applying the appropriate logic to what relates to consent management depending on the associated purpose and legal basis.
We understand the granularity provided by Orange's proposal, but this granularity actually creates complexity for developers and also for the operator logic. OGW products have to be "atomic", if a product needs to access, let's say, 2 APIs with 5 operations with 5 different scopes. You need user consent for all of them, otherwise the product won't work if, for example, the user only gives consent for one of the scopes and not for the other 4. So Telefónica's proposal would take care of this by handling consents and legal text at the product level. OGW products can NOT work for a subset of scopes.
Thanks @diegogonmar for your review
In order to move forward, I would like to fully understand your proposal and in particular following sentence:
An OPGW product does not necessarily have to be just one API. It could be just one API operation and one scope, a whole API with multiple scopes (like QoD), it could be N APIs, or even individual API operations of different APIs.
I would like to take a real simple example with our APIs . We have
If I follow your thinking, selling these 2 APIs for FraudPreventionAndDetection purpose potentially we will define:
4 OPGW products at API resource level (let's call them P1 for retrieve-date , P2 for check, P3 for device-phone-number, P4 for verify) + 2 OPGW products at API level (P10, P11) +9 OPGW products for possible combinations of both API resources (check and Verify, Check and device-phone-number , etc... - let's call them P20, P21, P22, P23, P24, ..P28)
That make 15 OPGW Products for FraudPreventionAndDetection purpose (and only with 2 APIs)
If I want to sell these same features for EnforceAccessControl purpose then additional 15 other OPGW products could be defined.
Question: I understood this is theoretical but could you confirm me this correct ?
Let's continue the thinking - with this model nothing prevents that:
From the API customer perspective, she/he as to understand that buying (P1+P2+P3+P4) is equivalent to buy (P10+P11) is equivalent to buy P24 (thing can get messier as P1+P3 = P20, P2+P4= P21, etc...).
Question: Still theoretical but could you confirm me this correct ? I see a lot of complexity here but perhaps I missed something.
Hi @bigludo7, In short, theoretically what you say is possible, every combination.
Notice we don't know what product will be successful and profitable, so maybe SIM Swap isolated has no value and has to be offered as a product focused on 'sim integrity' together with number verification or any other future API. But we cannot define APIs and API endpoints taking that into account because we don't know what will succeed.
On the other hand, legal departments may tell us that sim swap retrieve-date has a different legal basis than check, so a single product cannot have the two of them as purpose will be different due to different legal basis. So having 1 product - 1 API will not be met in these cases.
Regarding the API customer perspective, I think that should be solved with UX, meaning that the API Customer will not have the full matrix of combinations of API-scopes, but a set of products to be purchased, each of them for a certain purpose (with a certain legal-basis i.e.: consent, legitimate-interest, etc). Fore example, UX may offer a product catalogue with an experience of 'select the API features you're interested in', and upon selection, valid products will be filtered. This needs some level of agreement/standardization of the products that are sold, on top of API or API endpoints.
Notice that allowing a product with a set of scopes of different APIs, will also enable different business models. I.e.: charge based on queries for a given MSISDN, not individual API calls, so if e.g.: you query SIM Swap and also Device Status for a given MSISDN, thats 1 query in terms of charging for the product purchased.
Finally, from the opposite point of view, which is the end user. This will allow a purpose per product, even if the product has access to different pieces of end user data. So end user will have to opt-in or opt-out for a single purpose per product. Notice that the end user does not know about APIs, but about personal info being accessed; end user does not know if this is one API, half API or two APIs.
Let's continue with discussion in this afternoon meeting
From TMO-us.
my concern with purpose, is it gives an impression of control over an aspect we don't control.
ie.... if a user has granted access to location apis for the purpose of anti fraud, but not for the purpose of advertising.
when a token is issued.. i can definitively state that a scope has been granted. and at the time of an api call i can definitely allow or deny the access to that scope controlled resource. BUT. i have no control or even visibility to the purpose. Is this partner calling this location data for purpose 1 or purpose 2 right now? the partner can tell me what purpose it's being used for but that is an illusion of control...
Another example is what operating systems have exposed in a mobile environment. An App can Ask for access to my camera or my location, or access to my phone storage... but the google/apple os does not pretend to block one type of access vs another. The user has or has not granted access.. that's all the controls monitor. While the app "should" explain to the user why the access is requested. it's not part of the api interaction when access is executed.
Hi @mengan , Thanks for your comments. What you say it's possible, and it's actually what happens in non technological scenarios. E.g.: I provide my opt-in in a paper when I run a race giving my consent that photos taken can be used to promote the race in social networks. Then the photos may be used for anything else, thus breaking the law as I didn't consent such usage. But if that wrong use is discovered, I can report it and there'll be no proof that I gave consent to that usage (purpose)
In this case (API Consumption) by identifying the purpose, sending it and checking it when Access Token is to be issued, we ensure that we provide an Access Token to access a given resource with a given purpose. When that resource is accessed, operation is audited: the endpoint/resource was accessed by client X, to retrieve information Y of user Z, for a given purpose (the one granted) Then effectively API Client may break the agreement, and use data for other things. But there is no way to (online) control that. If discovered, end user and/or legal departments will act and thanks to the built process of token retrieval and usage; there will be no doubt of who was allowed to access what with what purpose.
As agreed in last working group call conference (20/09), a deadline will be set to try to find an agreement or an intermediate solution between the proposal of Telefónica and Orange. Hopefully we manage to do so, this is the desired way. But if there is no final agreement, it would be necessary to vote it according to CAMARA governance rules (https://github.com/camaraproject/Governance).
New PR #64 opened by @bigludo7 including a table to compare both solutions. Telefonica will complete it by Friday (22/09), then DT will review and add comments, maybe add new columns. @shilpa-padgaonkar
Deadline will be the end of next week: 29/09. If no agreement is reached, the voting process would be organized for the week of 02/10.
@jpengar I'm not comfortable with your proposition and not sure about the agreement you mention in the 20/9 meeting.
My point is that some critical point like the API Product granularity is a major point in the discussion and are discussed in other group (like GSMA Open Gateway product stream) . But our technical decision relies on this and our technical disagreement derives directly from this granularity (the table is very explicit on this - see line 1).
Instead of a vote, that for me is not relevant because the topic goes beyond the WG, I will suggest to
@bigludo7 I was just explaining what was mentioned in the last conference call about setting a 1 week deadline and voting if there's no agreement by then. But I could be reconsidered if other participants feel the same way.
Hi @bigludo7 , first row it's indeed very explicit, but we in TEF raise also very explicitly that tech solution should be valid for OGW product model but not completely tied to it, not only valid for such model. As we say in the table The technical solution should not be tied to the current OpenGateway business model, as it could change in the future and because CAMARA APIs could be used outside the context of OpenGateway.
So, unless there is an argument that for OGW business model the TEF solution does not work, I don't agree with setting this as a blocker for moving forward and go for a decision.
@bigludo7 @diegogonmar @jpengar Could we add another row to the table at the end to address the above point?
It could go in the line of "Is the proposed solution tightly coupled to any particular product model". Each of the 3 proposals can then state if there is any such dependency/coupling. From DT perspective, there is no such tight coupling between OGW product and the solution.
@diegogonmar
first row it's indeed very explicit, but we in TEF raise also very explicitly that tech solution should be valid for OGW product model but not completely tied to it, not only valid for such model.
So, if we take this as assumption trying to clarify the points and see where we need decision:
authorize
we value scope
attribute with a concatenation of a purpose
+ something
(I tend to think we're ok)purpose
is defined in W3C (I tend to think we're ok)something
is purpose-agnostic (I tend to think we're ok)something
is in CAMARA yaml and defined there in security/three-legged
, - Let's call it as technicalScope
(I tend to think we're ok)Now 2 questions before to go on the divergence:
technicalScope
granularity, or at this stage is it enough?technicalScope
granularity ?....given that we have following disagreement
technicalScope
potentially spanning over several APItechnicalScope
not spanning on several API (one api or a subset of one api)Sorry, for jumping in late. I asked OIDF working groups about consent and purpose and George Fletcher george.fletcher@capitalone.com proposed taking a look at OAuth 2.0 Rich Authorization Requests https://datatracker.ietf.org/doc/html/rfc9396
We could put all the required data into the authorization_details parameter https://datatracker.ietf.org/doc/html/rfc9396#name-request-parameter-authoriza
Hi!
I prefer to use "context" query parameter inside authorization request to pass purpose.
Context has been defined inside GSMA Mobile Connect spec as:
A transaction / action based message displayed on the Authentication Device
GSMA Mobile Connect spec => see 4.1
It is flexible (Usage Category: OPTIONAL) and capable of carrying various information from developer to CSP and/or customer/subscriber.
The contributors (TEF, Orange, DT) of the PR https://github.com/camaraproject/IdentityAndConsentManagement/pull/64 have discussed and come to an alignment. The outcome of this alignment is provided below:
We agreed to strongly recommend that scope attribute in the /authorize will be valued with “<dpvValue>:<technicalParameter>”
• <dpvValue>
is coming from W3C
• < technicalParameter>
must be either:
The examples are provided below:
Strong recommendation for format samples:
Strongly discourage the below formats and they do not guarantee interoperability:
Purpose(dpv) to be added as custom claim and other such options for purpose will be discussed with OIDF after they have finalized the formal liaison with Camara. They will be asked to provide recommendation as a neutral and OIDF expert party here for this topic. (Can be opened as an issue later)
Hi all, thank you so much for the detailed description and the agreement achieved between TEF, Orange and DT. I have 3 questions
Question 1: for format 3, it is up to the authorization server to expand the data scopes from the api name - correct ? The resulting access token will have to contain the detailed data scopes, having the purpose prefixed. Then it is up to the gateway tor the API to validate the data scopes conveyed in the access token. If the scope list is in the resulting access token, then we end up with format listed in item 4. None of the gateways or services supports bundled scopes, so you have to give a list or have the need to adjust each of them. Or do you want to change the API Specs in Camara and introduce a "catch-all" scope per API (indicated by the API name) ?
Question 2 related to the items 4 and 5: Why do you see a problem in listing multiple scopes after the purpose pre-fix ? Is this because the scopes might span different APIs ? Is this an issue, if an access token spans multiple APIs (as long as there is one purpose) ?
Question 3 Why do you see a problem in having multiple scopes with different legal basis? According to our analysis, this shouldn't harm. The legal basis will be retrieved per purpose & scope combination. The consent check will be executed for "consent" and "contract" only. If you go for a catch-all scope per API, this will end up in the most "limiting" legal basis, Is this the intention ?
Hi all, a big CAVEAT: if the answer to question 1 is that there is not intention to introduce a "catch-all" scope in the API spec file, this means that EACH Authorization server must build custom logic to expand the API name to a list of scopes and have this list in the resulting access token. This will introduce a huge effort for each CSP to build such a custom logic.
Therefore we need to have an alternative option added to the list of recommended options 1-3 for those who do not or cannot implement the custom logic and allow to send in a list of data scopes. This can be a full list (or even a partial list in the future).
I think that it is not a good idea to offer only a custom solution for Camara APIs and do not allow to have the default oauth approach supported as alternative.
@Elisabeth-Ericsson Eli, thank you very much for your comments and contribution. It would be great if you could open a new issue in the repository to consider this valuable feedback for the mid-term solution together with the other suggestions from Axel and/or from Dawid.
But as you may understand, a short-term solution has already been agreed by the active CAMARA participants in the issue (DT @shilpa-padgaonkar , Orange @bigludo7 and Telefónica), once all the deadlines we all set have been met. This agreement has to be understood as a compromise solution that meets the short term schedule (this topic had already become a stopper) and meets the current Open Gateway requirements described above (like "1 product = 1 API" and so on)... Of course, the discussion about the best technical solution is still open, as mentioned before, and the proposal, as mentioned in the last call, is to continue the technical discussions about the "purpose" also with the help and expertise of the OpenID Foundation, which would also participate in CAMARA.
So, as agreed in the last working group call, a PR has been created (#75) to document the current agreement in documentation/CAMARA-API-access-and-user-consent.md
. And once merged, issue #32 will be closed. So, I encourage you to open a new issue with this feedback and/or any potential proposal you may have for the best technical solution to declare the purpose when accessing CAMARA APIs in the future.
Hi Jesus, I understand that an agreement was reached between DT, Orange and Telefonica and that this is a short term compromise. This agreement is going to be documented in (#75) . Also it is good that the protocol discussion has been kept open. However, I think that I found an ERROR/GAP in the short term agreement, which makes it very difficult to implement it on the server side in the AuthZ servers deployed at the operators.
In the examples given in the issue 32 thread, the examples document on the value to be used for the scp
It must be possible for an authZ server to generate access tokens for API calls - and this will not only be Camara APIS - but also operate APIs and proprietary APIs for example. So it is very important to fix this aspect in the short term agreement, such that the server side can implement it.
In addition, the new issue #75 must document, on how the access token generated by the authZ server has to look like. I will open a new issue for the mid term solution and protocol aspects, but this is independent of the gap/error, we have to fix to get the short term solution going.
Hello @Elisabeth-Ericsson
From my perspective with this proposal we did not introduce a specific pattern in the Authorization server. We use the scope
attribute and provide only a common way to value it. We do not expect any specific behavior from the authorization server and I do not get why adding prefix.
With this proposal we will manage the scope
like any other and the Authorization server will not 'de-concatenate' the scope value or trying to understand it. It will just applies the authorization/consent configuration associated with this scope considered as a one value.
For value: fraud-preventiondetection:retrieve-sim-swap-date
the authorization server will be configure to trigger consent as legal base and have an associated text to be presented to the user.
For value: fraud-preventiondetection:check-sim-swap
the authorization server will be configure to trigger legitimate interest as legal base
For value: fraud-preventiondetectio:nsim-swap
the authorization server will be configure to trigger consent as legal base and have an associated textto be presented to the user.
Hi bigludo7, the proposal is using the scope claim, and a proprietary format of populating the scope claim. Other projects are proposing such approaches as well, so it is not a problem of conveying different information in the scope claim. the problem comes from 2 facts:
@Elisabeth-Ericsson @bigludo7 From Telefónica's point of view, we are open to discuss the most appropriate format within the already agreed proposal. As an example, we could think of a format like dpv:<w3c_dpv_value>#<tech-scope or api-name>
, since :
is already proposed as the separator in the names of the technical scopes. If that helps.
Hi Jesus, thank you so much for your comment. This approach will definitively help.
The authorization server has to understand the format in order to generate the access token - and the APIs will have to understand the scopes included in the access token as well.
@Elisabeth-Ericsson Thanks for the extra information !
Same than @jpengar, we (Orange) are also ok to add one extra prefix information in the scope to identify clearly that this a CAMARA scope.
Elisabeth-Ericsson @bigludo7 @shilpa-padgaonkar Sorry for the late reply, it was a bank holiday in Spain last week. Are you okay with the `dpv:
@jpengar To be sure to get it.
In order to get the authorization for endpoint retrieving the latest sim swap date for a fraud prevention and detection purpose the scope
should be valued as:
dpv:FraudPreventionAndDetection#retrieve-sim-swap-date
@jpengar To be sure to get it. In order to get the authorization for endpoint retrieving the latest sim swap date for a fraud prevention and detection purpose the scope should be valued as: dpv:FraudPreventionAndDetection#retrieve-sim-swap-date
@bigludo7 Yes, using the same examples as PR #75, it would be:
dpv:FraudPreventionAndDetection#retrieve-sim-swap-date dpv:FraudPreventionAndDetection#check-sim-swap dpv:FraudPreventionAndDetection#sim-swap
Also considering that :
is already proposed as the separator in the names of the technical scopes instead of -
See https://github.com/camaraproject/Commonalities/issues/53
Fine for me
Hi all, dpv name space is very good for the purpose strings. But it would be better in my view if we could use:
CAMARA#dpv:FraudPreventionAndDetection#retrieve-sim-swap-date CAMARA#dpv:FraudPreventionAndDetection#check-sim-swap CAMARA#dpv:FraudPreventionAndDetection#sim-swap
Then we can indicate the CAMARA format and clearly state: CAMARA#dpv:\<purpose>#techincal_scope1 technical_scope2 (in future).
This will also allow a consent evaluation function and a consent capture function to properly decompose.
@Elisabeth-Ericsson Eli, we already suggested using dpv:
as a prefix (standard W3C DPV). Basically to mark when the scope value declares a "purpose" and as a way of identifying the format of the scope value following that prefix. I don't see why adding an extra CAMARA#
prefix would provide any additional information and would generate longer strings for the scope values. The dpv:
prefix itself still allows for future use cases like the one you mention "dpv:
From our side we prefer dpv:FraudPreventionAndDetection#sim-swap
approach. Is that acceptable for you guys? Are you ok to close the format discussion just using dpv:
prefix?
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.