New API Proposal - Consent URL API #67
Conversation
jgarciahospital
requested review from
TEF-RicardoSerr,
NoelWirzius and
caubut-charter
as code owners
Co-authored-by: Axel Nennker <[email protected]>
|
Apologies - didn't mean to approve just yet. Still reviewing. |
|
Why isnt't the developer starting the authorization code flow or CIBA flow with the needed scopes and purpose at user-onboarding time? There is no need to actually use the the access token to call the API during end-user onboarding time. Why do we need this proposed API, when developers can use the above procedure? |
|
Hi @AxelNennker, In fact, the proposal is focused on solving that gap, that current auth mechanisms do not allow a developer to launch a consent with the user (unless in a front-end flow, which relies on the proper OGW device been involved). The issue with that approach is that you always need to count on a flow where the user's terminal is involved, it is, front-end flow (authcode), while CIBA "only" triggers a mechanism in which the telco is in charge of reaching the user with its own channels, no so adaptative to the developer's use cases. This is a proposal for standardizing a mechanism that solves the gap in CIBA, for cases where the developer is the one who knows where and when to show the consent capture process (while operator gets still in charge of the how and the control). So there is no other standard approach to provide a webview to the developer that can be shown to a final user, and it doesn't cover scenarios like:
|
|
Maybe... I don't read what you wrote in your comment from the API summary. Also, I, personally would never enter my login credentials into some device when there is no user-device. Maybe add use cases? I do not see it. For consent the telco has to authenticate the user and then collect consent. How can the authentication work if there is no device with user interaction? I think I am missing something. Please explain |
|
Hi Axel, Maybe I didn't explain properly in the last comment, since I think I cannot disagree with what you are saying. Those scenarios that I mentioned before are those that this API is intended to solve, by enabling the developer to request for a consent capture API from a backend that then can be shown to the end user in a valid channel, of course the OGW device may not be valid in those cases. If the device is not accessible or do not accept human interaction (as you said, a gas pump or a smart tag), or the device is not able to be used in the moment when the consent wants to be captured, or there is no app to be executed in the device... or simply because the developer identifies a better experience to capture the consent, the API allows the developer to ask for a URL that later can be exposed in a webview in any device, computer, other smartphone... where the user can indeed authenticate with the carrier credentials and provide a clear consent acceptance. The API is to be triggered from the backend of the developer, and the result (the URL) will be then shared to the user in the channel that developer considers as the best one to reach the user. Let me know if it's clear now and we'll rephrase the API template if required. |
|
I assume this is then a client credentials based only API? Does the URL depend on the API's input parameters? client_id, technical-scopes, purpose |
|
Some openid providers split the user-authentication and consent collection from the "core" openid/oauth2 token handling.
The connect2id documentation is written from the POV of the server tenant, but maybe the consent-url you propose here is "similar" but from the POV of the client?! |
Yes, it should be.
This URL must be a temporary and non-predictable URL. It is NOT fixed and will depend on the client_id, the scopes, the purpose (W3C DPV value), and the target user whose consent is required for the requested scopes under the specified purpose for the corresponding client_id. |
|
Should the API make sure that it can't be used as a telco-finder? If the client posts the same parameters, is the returned URL the same, or every time different? |
|
The “consent” gap identified in this document is accurate. This gap is referenced in the “Consent and Measurement” API proposal submitted last November. |
|
@jgarciahospital The consent string serves as an identity bridge between online and offline identities meeting global regulations dynamiclly. @AxelNennker the The existing identity and consent APIs do not meet the legal requirements for client/brand adoption. Brands can not adopt Camara until addressed. |
|
Including some slides to complement the high-level API descriptor: |
|
@AxelNennker The current propsosal can be moused as a way to log the subscriber’s usage of the device, such as websites visited. Please note that if data leakage occurs downstream due to the developer’s mishandling of data via weak endpoints (e.g., CrowdStrike), the liability for leakage according to GDPR flows upstream. Regulators will fine the data source. @jgarciahospital what service or enhancement is this providing? |
Hi @AxelNennker, For the first 3 questions the response is a simple and absolute YES, and just in the same kind of approach as for the endpoints in CIBA or Authcode where same considerations shall be established. So, we don't expect different risks or considerations to be applied in this Out Of Band approach. For the URL question, not sure whether the API specification need to enter in that kind of details that may be more dependant on the implementation of each operator, since it is directly bound to the operator-to-subscriber relationship. In fact, operators can just follow similar strategy as with the Authcode Flow consent capture process, for the creation of this webapage where user will be redirected. |
Hi @nickvenezia, None of the current consent capture mechanisms, neither this out of band approach, are targeted to log the subscriber's usage of the device. Quite the opposite, the objective is to ensure a proper privacy management by leveraging the operator's control and ownership on the privacy management of our subscribers. I don't see how a consent capture, controlled by the operator with its proper and secure subscriber authentication can be used to log website historical... The intention of this new out of band proposal is to maintain that control but taking advantage the knowledge of the developer about the use case and nature of their customers, ensuring that reaching the customer for that purpose is feasible and agile leveraging the channels of the third party. But always maintaining the ownership of the telco in the process, webpage is from telco, authentication of the user/subscriber with telco credentials is from telco... |
Why does it have to be temporary and non-predictable? In ICM examples we have this: Why not turn this into the following for the purposes of this API proposal? No client authentication is needed if the URL is standardized in this way... Sorry, for the many questions. I am not against the idea to decouple consent collection from API usage and accss-token-creation. Though, I do not understand why this needs an API. @jgarciahospital Maybe update this PR with the collected answers? |
|
@jgarciahospital and @jpengar Did you guys have any particular reason to not have a "regular" consent management API instead of the proposed consent url api? Just wanted to know the thought behind. |
From my point of view, the proposed API is not intended to do consent management against the operator, it is specifically intended to provide an out-of-band consent capture mechanism to the API client (via a consent URL). By "regular" consent management API, I assume you mean an API to perform CRUD operations on consent records on the operator side, which is a completely different feature with a completely different scope. The consent URL allows the API client to collect consent through an operator channel. With a CRUD API on consent records, the operator would be exposing the ability to create, update, or delete consent records to third parties, so that consent management could be delegated. This is completely outside the scope of this API. |
|
Hi, This would be like operating with a delegated consent mode, which the partner would retrieve and then transmit to the operator.
Consent is, imho, a very sensitive subject, and I always tend to be suspicious when it's delegated outside of the operator. |
hi @sebdewet, as we tried to clarify in the slide set and in the backlog meeting, this mechanism is not intended at all for privacy or consent delegation. That is a red-line of the operators and Telefonica is totally positioned in the side of the telco always remaining in charge of managing privacy and consent, basically because of the problems that this would bring as you detailed. The proposal is meant for maintaining the telco as the one gathering the consent, using the subscriber authentication and providing a webview of the telco as well, but allowing the application/developer to show it to the customer in the best moment and channel posible. So the API only generates a URL of the telco that the developer can show to the customer. |
|
@AxelNennker leaving technical details apart until definition phase can start, we can focus on a requirement discussion as per backlog scope. So I prefer to go over the specification details when the proposal has started and the scope is ready.
With CIBA, developer can choose the "when" but not the "where/how", since the process is managed by the operator once the developer has started the request. So, there is not possibility for the developer to choose the channel where to reach the user if in a backend flow. Let's imagine again a case of location API service where the SIM is installed in a tracking device. Consent is required and if operator tries to reach customer by SMS or similar, it is clear that this SIM is not going to be reachable this way. With consent URL API the developer can ask for a consent capture link and present it in the tracking configuration app/interface, where the user will introduce the telco credentials and provide the consent.
Again, I think we don't need to provide a technical definition of how the operator will create the webpage for authenticating users or gathering consent, for sure not in this stage but maybe even neither in the technical specification phase. If we think again on this mechanism as a way to provide to the backend the frontend capture page used in authcode (step 7 of the authcode flow), we just need to define the mechanism for retrieving that webpage URL, but not the webpage details (as neither defined in authcode right now).
Most of the use cases will be just the user interacting in one of their devices (not the OGW device) providing the consent after logging in a trusted telco webpage. Again, it's exactly the same as happens in a authcode flow but without the restriction of this happening in the OGW device. BUt yes, developer can choose to show this webpage in a nother device during a user interaction phase. Let's imagine again a location service for car tracking, where the user provides the consent during the purchase of the car in the car dealer premises, or in the configuration webpage of the dealer just including one additional screen in the process. It is clear the the user experience will be much clear than a backchannel mechanism from the operator, and that the current CIBA flow do not allow it.
Any consent API can use this mechanism, not restricted to any service or category. I don't see any difference from antifraud to marketing. Included changes in the API proposal as well as a draft User Story |
|
@jgarciahospital I am going into the technical details because I am trying to understand whether there are already standards that could be used. If the technical standards already exist then this API is not needed. Regarding this use case:
This sounds like the use case of a primary device (Smartphone with Tracking App ODSA) and a companion device (tracking device) which are paired. (That could be viewed like OAuth2 where the picture frame has a SIM-card.) Maybe this proposal is going to render TS.43 ODSA use cases obsolete, because this is much simpler. I do not think that the technical details can be skipped. The technical details discussion is something like "prio art" in a patent application, I think. The patent should explain why it is new and not like that prior art. |
|
Hi all :) Vonage and Ericsson have been pondering the need for an API similar to this for a while, so it's great that this is being proposed. Vonage sees a need to expose an API that provides metadata linked to a Application/Scopes/Purposes per Subscriber/CSP at runtime, and this API should incorporate a Consent capture URL for the use cases described above. We agree that there will sometimes be a need for Consent to be captured or revoked for application use cases upfront, out-of-band, and also Consent to be collected at runtime, in-band. As stated before, we do not believe that collecting consent using a web portal in the frontend flow is viable, as it will materially deteriorate the End-User experience and will not be acceptable to most ASPs - the introduction of this mechanism will likely severely damage the market. Instead, frontend flows should always use upfront Consent capture using an API like this, or rely on a non-Consent-like legal basis. Whilst the Consent URL API SHOULD be authenticated using OAuth 2.0 Client Credentials flow, the URL supplied by this Consent URL API MUST NOT have any guise of security, authentication MUST happen after the URL has been loaded, otherwise it could always be background loaded by a malicious app; therefore we do not see that there's a need for this URL to include dynamic one-time-use or secure components. The mechanism of authentication would depend on what the URL loads, but this is a per-CSP decision that this API would permit. One could imagine that the URL could be a link to the CSP's website where username/password/MFA auth is used, or in the case of iOS a Universal Link that launches the CSP's installed app where authentication has already been completed; there are also other better options and mechanisms that can be discussed separately. With respect to the API itself we have additional proposals for how it should work, for example, we suggest that optionally Scopes and Purposes could be included in the request and embedded within the URL in the response, or without providing these fields the URL's invocation would show all relevant privacy options for the application's registered use cases. Lastly, I think that this API could be expanded to a general Consent API where Consent states for Scopes/Purposes could also be retrieved - this would guide the ASP on which APIs are available for each Scope/Purpose for the subscriber and CSP without further Consent capture, and where Consent capture will need be triggered preparing the End-User for an interruption to their usual scheduling. |
The reason why to focus in the requirements instead on the solution is first the scope of the backlog group and second the main purpose of this proposal, which is enhancing current CAMARA auth/consent process, in which we have identified this gap (no possibility for a developer to show a consent webpage to a customer in any other device than the OGW device during a frontend flow). The TS.43 companion device is a good example, but it shows more or less a CAMARA frontend flow with device authentication: main device is authenticated employing EAP-AKA mechanism (due to the sensibility of the SIM onboarding) (instead of authcode redirect network identification as in CAMARA) and later a websheet is exposed to the customer for the authentication as a CSP subscriber, and to validate the activation of the service in another device. So it is a parallel flow as the frontend that we have in CAMARA, even though there is a second device in which the service is finally executed. But, in any case, here we are only focusing on the second step, reaching a websheet/webpage URL of the telco in which the consent can be provided, similar to the product activation in TS.43. Following previous statement, once we understand that this mechanism is required we can decide on which solution is better to solve it, whether a TS.43 approach or any other market existing one, but for sure now it's not covered in CAMARA and that is what we need to confirm and start working on the solution. |
|
@chrishowell thanks for the feedback, really welcomed.
I believe we are mostly aligned with your authentication strategy, and main purpose of the URL one-shot proposal is to ensure it cannot be generated by anyone else than the telco.
Agreed that final subscriber authentication is part of each CSP strategy and mechanisms. I'd prefer to avoid device-dependant solutions, allowing options where a non-CSP device is used.
We need to take care on how this API could be used to request for information instead of its main purpose of gathering consent. Information exposed about existing consents/lawful bases shall be limited, and of course around telco finder.
Same as previous comments, let's try to avoid information to be exposed by this API, otherwise we may enter in the chicken-an-egg situation of this API requiring consent itself because of the information it's exposing. But let's keep it open for discussion when we start working on the details, for sure. |
|
I still don't get why the standard OIDC get-accesstoken page is not enough. The developer can show this page whenever they like and whenever they think consent for this client, this scopes and purpose is best to be collected. Best means best UX, no interruptions, .... API usage is completely decoupled from accesstoken retrieval in OIDC. To @nickvenezia comment: the page can be branded and must take all legal requirements into account. The page is easily adaptable to the client. Actually, I think, it always must be adapted to the client because the user has to take an informed decision when they provide their consent. "SupaClient wants to retrieve the location information of your kid's SupaTelco tracker for the next 4 weeks, do you consent?" To @jgarciahospital comment:
There is no such assurance. The hacker can always build a look-alike page to fool the user. Random, one-shot urls are no protection. Even if the developer downloads a signed zip-file from the user-consent url and validates the signature, there is no way to stop a hacker who fakes the device and collects the user credentials. This reminds me of the qrcode cross-device login case. The hacker tries to login, gets presented a qrcode, modifies the user's qrcode page to show the hacker's qrcode. If the user authenticates and consents then the user consents to the hacker's login. (Which is why passkey's qrcodes are Bluetooth-protected) Considering the above: Why is the standard OIDC "page" not enough? |
I assume that by "existing identity and consent APIs" you mean OIDC and CIBA? The authorization server gets an OIDC/CIBA authentication request and knows exactly which client is requesting an access token for which scopes and purpose. The authorization server then has the obligation to show the user an authentication page so that consent can be collected by that user can give their informed consent. |
| | ---- | ------- | | ||
| | ***Summary*** | As an enterprise application developer, I want my customer (end-user) to provide the consent to access certain CAMARA API before the actual API call is made, taking advantage of, for example, my onboarding process. | | ||
| | ***Roles, Actors and Scope*** | **Roles:** Customer:User, Customer:BusinessManager, Customer:Administrator,<br> End-user, Communication Service Provider (CSP), Channel Partner <br> **Actors:** End-user, Communication Service Provider (CSP), Channel Partner <br> **Scope:** <br> - Retrieves a consent capture URL based on the required services, so end-user can accept/deny consent in a CSP webpage. | | ||
| | ***Pre-conditions*** |The preconditions are listed below:<br><ol><li>The Customer:BusinessManager and Customer:Administrator have been onboarded to the CSP's API platform.</li><li>The Customer:Administrator has onboarded the Customer:User to the platform.</li><li>The Customer:User performs an authorization request to CSP</li><li>The Customer:User has the access token allowing a secure access of the API.| |
There was a problem hiding this comment.
The Customer:Administrator has onboarded the Customer:User to the platform
Which platform is this? Customer:Platform or ...
| | ***Summary*** | As an enterprise application developer, I want my customer (end-user) to provide the consent to access certain CAMARA API before the actual API call is made, taking advantage of, for example, my onboarding process. | | ||
| | ***Roles, Actors and Scope*** | **Roles:** Customer:User, Customer:BusinessManager, Customer:Administrator,<br> End-user, Communication Service Provider (CSP), Channel Partner <br> **Actors:** End-user, Communication Service Provider (CSP), Channel Partner <br> **Scope:** <br> - Retrieves a consent capture URL based on the required services, so end-user can accept/deny consent in a CSP webpage. | | ||
| | ***Pre-conditions*** |The preconditions are listed below:<br><ol><li>The Customer:BusinessManager and Customer:Administrator have been onboarded to the CSP's API platform.</li><li>The Customer:Administrator has onboarded the Customer:User to the platform.</li><li>The Customer:User performs an authorization request to CSP</li><li>The Customer:User has the access token allowing a secure access of the API.| | ||
| | ***Activities/Steps*** | **Starts when:** The customer application makes a request to the Consent URL API, including the end-user identifier whose consent will be retrieved, the scope(s) of the services requested and the purpose associated to them.<br>**Ends when:** The CSP provides the CSP's consent webpage URL to the customer application. | |
There was a problem hiding this comment.
How does the Customer:Application know the CSP:User-Identifier?
including the end-user identifier
| | ***Roles, Actors and Scope*** | **Roles:** Customer:User, Customer:BusinessManager, Customer:Administrator,<br> End-user, Communication Service Provider (CSP), Channel Partner <br> **Actors:** End-user, Communication Service Provider (CSP), Channel Partner <br> **Scope:** <br> - Retrieves a consent capture URL based on the required services, so end-user can accept/deny consent in a CSP webpage. | | ||
| | ***Pre-conditions*** |The preconditions are listed below:<br><ol><li>The Customer:BusinessManager and Customer:Administrator have been onboarded to the CSP's API platform.</li><li>The Customer:Administrator has onboarded the Customer:User to the platform.</li><li>The Customer:User performs an authorization request to CSP</li><li>The Customer:User has the access token allowing a secure access of the API.| | ||
| | ***Activities/Steps*** | **Starts when:** The customer application makes a request to the Consent URL API, including the end-user identifier whose consent will be retrieved, the scope(s) of the services requested and the purpose associated to them.<br>**Ends when:** The CSP provides the CSP's consent webpage URL to the customer application. | | ||
| | ***Post-conditions*** | The customer application can show the provided CSP's webpage to the end-user, where end-user will introduce CSP's end-user credentials to provide the required consent (or refuse it). | |
There was a problem hiding this comment.
Security Considerations: The CSP:User enters their CSP credentials into a webview controlled by Customer:Application which might enable the Customer:Application to steal the CSP:user's credentials.
Please see RFC8252 OAuth 2.0 for Native Apps
and AppAuth regarding security recommendations for security recommendations.
|
Under the GDPR you have to make the revocation of user consent in a way which is as easy as giving consent. |
|
I still do not see the need for a Consent URL API. At some point in time the user has to give consent at the telco. If the Camara API the client needs consent for something that involves a different SIM/IMEI/device/subscription than the authentication device or the consumption device, then that is a unsolved problem. Nobody yet wrote a user story that shows the need for the consent url API. If you talk about an out-of-band revoking consent API, then we might start talking about a general consent management API (out-of-band or other). I think all telcos and Camara participants would benefit from a consent management API. |
|
@AxelNennker There are some API's in which you can't have user interaction during the API call, because the user interface is busy at that moment in time, for example for making a phone call. In these cases you will have to acquire user consent way before the actual API call, and for that you may want to have a set of separate calls defined to handle consent. |
@HuubAppelboom The user interaction is when consent is granted or not, and that is code/accesstoken generation time. |
|
@AxelNennker Yes, I understand that the consent is acquired during code / access token generation time. What I am referring to is that sometimes you may want to acquire user consent long before the actual API is needed. For example, you may want to acquire the user consent for certain checks when opening a bank account. And that the checks are actually performed during transactions weeks later. Now, you can try to use the same consent acquisition during the account opening and transaction time (and generate a code and acces token which are never used), but most likely you would need to provide different information to the end user because the context is different. For example, if the API is about location verification, during onboarding you will ask whether the end user will agree to location verification when doing transactions in the future, while during a transaction you will ask for permission to check location now (otherwise the transaction does not happen) and during future transactions. Context is everything when communicating with end users, and you need to be transparant about the consequences. Hence I do see a need for an a priori consent acquisition and an on-the-fly consent acquisition, so you can diffentiate communciation and what is relevant at that point in the user flow. |
|
@HuubAppelboom The API consumer can ask for consent as often as they like and provide the context as appropriate. How does the consent URL help? I am guessing (again): Maybe the consent-url is pre-authenticated user consent collection? I think that does not count because the consent-url is not under control of the user. The API consumer could use the consent-url without the knowledge of the user. I think the user needs to be authenticated by the telco every time the API consumer asks for consent. For that the user needs an interaction with the telco. To pickup your example: Why is the API consumer/bank not asking for both consents when the account is opened? I would kindly ask supporters of this API proposal to provide one or two example use cases that can't be done with OIDC or CIBA. Everything I heard in this thread and other discussions about consent-url does not explain the benefit or the need of the consent url API. All the proposed use cases are vague and I got the impression consent-URL API is expected to solve a different problem than user consent collection. |
|
@AxelNennker In the example that I mentionned it is not the idea that you ask consent twice, just once will do. So it is either in the onboarding that consent is acquired, or at the moment of transaction (in case the consent is not there yet). The consent is acquired is presented by the API Consumer, but is given to and stored by the CSP. I think the consent question should be controlled by the CSP, because that is the only way you can ensure it meets the legal requirements, for which the CSP is responsible. Otherwise you rund the risk that the API Consumer may change the question for example to a less sensitive matter to get a higher conversion rate. Now the MNO does not know the context, so how is this going to work ? |
|
My two cents. I fully agree that an Authorization Code or CIBA authentication flow can be initiated at any time, depending on the use case and the application's capabilities, to capture consent. In fact, consent capture doesn't need to happen precisely when the API is consumed. The key benefit of the Consent URL API is that it offers a significant advantage by enabling a fully decoupled, out-of-band mechanism for consent capture. This API allows the application to control the user experience entirely. The application can generate a consent URL from the Operator, which the user must authenticate with. However, the application has the flexibility to deliver this URL to the user through the most appropriate channel or medium, tailored to the user's current context. Importantly, this API doesn't delegate consent capture to a third party but rather empowers the third party (the application) to present the Operator's consent capture URL at the most opportune time and place. The actual consent capture occurs within the Operator's secure environment, ensuring the user's authentication with the Operator. Historically, in uses cases for CAMARA, the Authorization Code flow was thought to be used primarily for network authentication (a.k.a. silent authentication), where user interaction was minimal. Partners have often raised concerns about the user experience, especially when the user is directed to an Operator portal for authentication or consent within the Authorization Code flow—a point also highlighted by @chrishowell. Furthermore, the Authorization Code flow assumes the availability of a front-end device for the user, which isn't always the case. The Consent URL API adds a layer of flexibility to the consent collection process, allowing applications to integrate and customize the consent experience more seamlessly without intending to replace existing CAMARA OIDC flows. Instead, it enhances these flows by providing more options for when and how consent is captured. |
How does consent URL API help? The current flows allow the CSP to capture consent. The API Consumer determines when the consent is captured, and for what scope, purpose. The CSP knows the scope(s) and the client_id, and maybe the request is even signed. The API consumer can ask once for all scopes or many times for each single scope. How does consent URL API help? |
I would question "entirely". The application MUST not control the UX entirely. The CSP MUST control the consent collection. The consent-URL is just a URL produced by the CSP. @jgarciahospital proposed a dog tracker use case but I think that also can be done with the standard flows and there was never a user story that benefited from the consent-URL API. Every consent collection has to be done by an authenticated user because otherwise the CSP does not know who grants consent. The consent-URL cannot be pre-authencticated because the API consumer controls the consent-URL and the CSP does not know whether the CSP:User uses the consent-URL or some employee of the API Consumer. The claim that the consent-url API has a ton of benefits is quite abstract. Can somebody please provide a user story / example that uses consent-URL API as required by API_backlog? Story ourtline:
u) user can use device Probably the device contains a SIM issued by CSP and owned by CSP:User. |
|
As shared offline, new slide set with detailed explanation and user stories has been included in this PR. |
|
@jgarciahospital Could you please turn the pptx into md documents, maybe each user story in a separate supporting document? |
|
@gmuratk as API is to be brought to next TSC, please include new information to be reviewed. |
What type of PR is this?
New API Proposal
What this PR does / why we need it:
API for retrieving a Consent Capture URL (name TBC), improving the integration and experience of developers and users in this process.
Which issue(s) this PR fixes:
Fixes #68