Question to documentation update for security schemes
Elisabeth-Ericsson opened this issue · 15 comments
With pull request #93 (Documentation update with securitySchemes final agreement #93), the agreement on protocol handling has been added.
The new text states: Which specific authorization flows are to be used will be determined during onboarding process, happening between the API Client and the Telco Operator exposing the API, taking into account the declared purpose for accessing the API.
This phrasing allows for several interpretations:
A: (API, Aggregator, Telco): The authorization flow to be used for an API call is agreed between AGGREGATOR (the physical API client) and Telco Operator and this is specific to "API, aggregator, CSP".
Consequence:
B. (API, Purpose, Aggregator, Telco). The authorization flow to be used for an API call is agreed between AGGREGATOR (the physical API client) and Telco Operator and this is specific to "API, aggregator, CSP and PURPOSE ". however the purpose is only settled when onboarding an app and ordering the API products (via TMF 931).
C. (API, Purpose, Application, Telco), The authorization flow to be used for an API call is agreed between AGGREGATOR (the physical API client) and Telco Operator, but might differ per application (the logical API client) and thus is specific to "API, application, aggregator, CSP and PURPOSE ". The purpose is only settled when onboarding an app and ordering the API products (via TMF 931).
Consequence of A: the authorization flow to be used is on the triple (API, Aggregator, Telco) and independent of purpose.
Consequence of B: the authorization flow to be used is on the quadruple (API, purpose, Aggregator, Telco). for different purposes, different authZ flows might be used for the same API.
Consequence of C: the authorization flow to be used for API invocation depends on a different quadruple (API, purpose. application, Telco. Thus the flow to be used is application dependent; for the same API and purpose, a different flow might be used between aggregator and Telco,
Can you please clarify which of the options A,B or C has to be supported ?
Which flow to use may also depend on other factors, like the legal basis which parties have agreed upon to be used for processing the personal data. Purpose is not sufficient in this matter; for example you can have cases which have fraud prevention as a purpose, but you may have in one case legitimate interest as a legal basis, and in other cases consent is used as a legal basis, and this can have impact on which flow to use. Assuming that this is defined in the Application, option C would be best.
This is my interpretation:
"The Telco Operator (i.e. API provider) will tell the API Client (i.e. API consumer) which authorisation flow is valid for which API endpoint during the client onboarding process. The API consumer (who may be an aggregator) has no say in this. Take it or leave it. And if the Telco Operator doesn't approve of the purpose for which the API consumer wants to access a given API endpoint, then it may be that no valid authorisation flow is offered."
How do we ensure that all "Telco Operators" make the same choices regarding which authorisation flows are valid for which API endpoints? That's where the "Technical Rulesets" come in. But this does assume a common interpretation of these rules.
Also, despite the possibility that different authorisation flows could be used for the different legal basis, I don't see this happening in practice. API providers will want to implement only one "flavour" of the API and, if there is the possibility that end user opt-in or opt-out needs to be checked, then a 3-legged flow will be used and those checks simply skipped if not required. So even LegalCompliance, which would have Legal Obligation as the legal basis, would use one of the 3-legged flows if other purposes requiring opt-in or opt-out consent (because of a different legal basis) were possible.
One final point. It is entirely possible that different API providers will attach a different legal basis to a given purpose, even within the same legal jurisdiction. This may be because their lawyers just had different opinions. Or it may be that the technical implementations are different and hence require a different legal basis to be used. Agreement amongst API providers on which authorisation flow to use must not depend upon a common interpretation of the legal basis under which a purpose is being processed.
In my opinion, the applicable authorization flow(s) depend pretty much on the API itself and its use cases. The scope to be used, the purpose under which the data will be processed and the list of allowed grant types is part of the information that is handled by the Operate APIs (TMF931) as part of the API product orders in the onboarding process as mentioned in the text. The API product definition will determine everything else.
On the one hand, if the API processes the user's personal information, then a 3-leeged grant type is used. So the only allowed grant type(s) would be Auth code and/or CIBA. If the API does not process user personal information, then Client Credentials (2-legged) would be a valid grant type. So the documentation clarifies this first. And depending on the use case, as I said, there may be APIs that only allow one specific grant type, e.g. Number Verify API can only be used with Auth code flow due to the nature of that API use case.
On the other hand, the documentation also provides technical ruleset for the applicability of Auth code flow (FE flow) vs. CIBA flow (BE flow) depending on the API use case. But I think that except for APIs like Number Verify, I see the most likely APIs to allow both 3-legged flow in general: Auth Code and CIBA. It will be part of the API product definition.
Regarding the purpose, I don't think the authorization flow has a direct relationship with the purpose. The allowed purpose(s) set during the onboarding process will actually determine the legal basis applied, which depends on the local legislation. And ultimately, it may determine whether an opt-in (consent capture)/opt-out is required.
One final point. It is entirely possible that different API providers will attach a different legal basis to a given purpose, even within the same legal jurisdiction. This may be because their lawyers just had different opinions. Or it may be that the technical implementations are different and hence require a different legal basis to be used. Agreement amongst API providers on which authorisation flow to use must not depend upon a common interpretation of the legal basis under which a purpose is being processed.
What is the difference between a legal basis and a legal jurisdiction? The jurisdiction is the legal basis our business operates in, right?
I sure hope that operators in one jurisdiction agree on whether consent is needed or not, otherwise, I think, selling Camara APIs becomes difficult. If operator1's legal counsel allow API use for #<technical_scope> without consent but operator2's legal counsel in the same jurisdiction, say Germany, forbid API use, then Camara is in trouble.
This is not really a technical question, but a business decision the operators in one market / jurisdiction should make. Better even if we all agree on one rule set globally but that seems unlikely.
@AxelNennker One of the legal basis that can be applied under the GDPR is legitimate consent. With legitimate consent, the data controller must make a (documented) balancing test between the privacy of the data subject and the interest of the application provider. Quite a number of aspects needs to be taken into account here, and some of these are by their very nature subject to interpretation. For example, one of the questions you must always ask is whether there is a less privacy invasive alternative available (which you should then use). Another question is whether the data subject can expect that this data processing occurs (like is this a normal beahviour or it something rare). For example, you can argue that to use an SMS for 2FA is normal behaviour, but whether your MNO needs to be involved in the processing of the one time code can be a different matter.
Because this evaluation is never defined by mathematical rules and subject to interpretation, you will always see differences in interpretation. What is important in this case is to set up discussions between privacy officers to try to come to an alignment.
BTW. What adds to the complexity, that some services do not only fall under the GDPR, but also under the telecom law. The telecom law in Europe is in principle harmonized, but in practice there are differences between countries. This results that in one European country you can do an API with legitimate interest as a basis, and in another country you must ask for user consent. So, you also need to talk with your legislators if you see this kind of differences between countries in Europe.
What you have to accomodate anyhow in the CAMARA standard is that in one country, you (or the application provider) must be able to ask for user consent, whereas in another one this is not required.
What is the difference between a legal basis and a legal jurisdiction? The jurisdiction is the legal basis our business operates in, right?
In the context of my comment:
- "legal basis" would be Consent, Contract, Legal Obligation, Vital Interests, Public Task, or Legitimate Interests
- "legal jurisdiction" is the territory over which the authority of a court extends - usually a nation state, but not necessarily
So they are different things, though obviously the "legal basis" that I have listed are only applicable in legal jurisdictions that recognise these in law.
I sure hope that operators in one jurisdiction agree on whether consent is needed or not
Well, we have this situation right now in Germany for Number Verification, as Vodafone's lawyers say the applicable legal basis for dpv:FraudPreventionAndDetection is "Consent" and other MNOs say otherwise. The difference in opinion arises from differences in the technical implementations, And CAMARA does not standardise implementation.
But a well designed consent checking mechanism can cope with this. And part of this is avoiding that the legal basis itself be used in the construction of scopes or otherwise signalled as part of the authorization flow. It is not required.
Hi Eric, the example you give (Number Verification in Germany) is why you can NOT assume there is always a 1:1 relationship between purpose and whether consent is required or not. At most you can use it to block requests for a purpose that you are not willing to support as MNO.
BTW, what do customers in Germany think that the legal basis should be ?for Number verify ? They are also responsible for sending the phone number to the MNO to be verified, so they must have an opinion on this as well.
the example you give (Number Verification in Germany) is why you can NOT assume there is always a 1:1 relationship between purpose and whether consent is required or not
Absolutely. The API provider, and only the API provider, must decide for themselves under what legal basis they are providing the API response given the "purpose" declared by the API consumer. CAMARA cannot standardise that.
what do customers in Germany think that the legal basis should be ?for Number verify ?
Number Verification and Number Verify are different APIs, of course :-) But the end user must be told this information when their consent is collected, because consent must be informed. Obviously MNOs who believe they do not need end user opt-in consent will not need to tell end users anything.
If, by "customer" you mean API consumer, then in this case they are only sending a MSISDN that the end user will have already told them. So they should already have the agreement of the end user that this data can be sent to the API provider in this way. The issues arises from the front end authorization flow, which involves a direct interaction between the end user device and the API provider. It is that that requires the consent.
@eric-murray
Hi Eric, under the GDPR there is no difference to what extend end users need to be informed, so even when you choose legitimate interest you still need to inform users what happens with their data, for example by describing this in the privacy policy. If the MNO believes user opt-in is not necessary, they still need to inform users to the same extend. The only difference is whether explicit consent is requested.
What happens in this case in Germany when consent is not granted with Number Verify. Will the API Consumer still provide access to the service (as they should under the GDPR, otherwise the consent is not given freely??). This becomes also interesting in case there is a legal requirement to use 2FA. Wil they have to offer an alternative ?
The differences in Germany are not due to GDPR. I'm not an expert, but understood GDPR to be common across the EU, but we do not have this issue in other EU countries.
But, yes, GDPR itself has other obligations on API providers, and I'm sure these are fulfilled. However, issues such as ensuring that the end user has read and understood the Ts&Cs of the service they are using are not an issue for CAMARA. CAMARA just has to ensure that the information required for the API provider to make a decision as to whether to fulfil the API service request or not is available.
Which specific authorization flows are to be used will be determined during onboarding process, happening between the API Client and the Telco Operator exposing the API, taking into account the declared purpose for accessing the API.
Maybe we can write something more general like:
Which specific authorization flows are to be used will be determined during onboarding process, happening between the API Client and the API Provider or Aggregator exposing the API, taking into account the declared purpose for accessing the API.
When there is no aggregator the onboarding is between the API Client and the API Provider.
When there is an aggregator the onboarding is between the API Client and the Aggregator, which is in this case thte API Provider from the API Client PoV, right?
Does this go in the right direction, even if it is not the full answer to the original question...
@Elisabeth-Ericsson:
IMHO, interpretation B should be valid. Unless TMF931 uses some app property (for e.g. application type) to change the outcome of B into something else. In such a case, C would be the valid interpretation. However, I am not aware of any such discussion.
@AxelNennker: I think that your interpretation is not fully correct.
TMF 931 is used between CSP (as provider) and the API client, which is usually the aggregator. There are only rare scenarios where the operate APIs (TMF 931) are used for API orders, if there is no aggregator in the picture. In the latter, the app developer would go to a market place exposed by the CSP.
@shilpa, @jpengar: I agree with your analysis. As a conclusion
- the possible authorization flows are configured on the API product.
- the authorization flow to be used will be settled when the API product is ordered.
Now I have a minor question left: What happens if multiple APIs are bundled within one API product ? Are we taking the assumption that all of these APIs must be called using the same flow ?
Now I have a minor question left: What happens if multiple APIs are bundled within one API product ? Are we taking the assumption that all of these APIs must be called using the same flow ?
As far as it has been discussed today, I think this is not the case with CAMARA. In the past we always talked about a 1:1 relationship between API and product, AFAIK.
@shilpa, @jpengar: I agree with your analysis. As a conclusion
the possible authorization flows are configured on the API product.
the authorization flow to be used will be settled when the API product is ordered.
In that case, do you suggest any action items to resolve this issue? Do you feel there is a need for further clarification in the v0.2 documentation? If so, could you contribute with a PR for everyone to review? Or could this issue just be closed with the understanding aligment in the comments above?
Thanks for the comments.
I think that it would be good to update the documentation for 0.2 and clarify. Pull request #120 has been created..