[Accesses API] x-device Header clarifications

[rkandoi]

CAMARA API Guide allows the use of GET with Headers:

https://github.com/camaraproject/Commonalities/blob/r3.2/documentation/CAMARA-API-Design-Guide.md#65-post-or-get-for-transferring-sensitive-or-complex-data

However, no other API in CAMARA seems to have adopted this approach.

This issue is to track future improvements made to the Commonalities API guide where the proposal from this API is documented as part of the Design Guide.

[eric-murray]

This approach is used by the latest public release of simple-edge-discovery

Note that this approach can ONLY be used for 2-legged access tokens (i.e. client credentials), as otherwise the device is identified by the access token, and providing additional device identifiers must result in an error.

The rule in CAMARA is:

In cases where personal data is processed by the API and users can exercise their rights through mechanisms such as opt-in and/or opt-out, the use of three-legged access tokens is mandatory.

In practice this means that, certainly for Europe and I would imagine many parts of North America, 2-legged access tokens can only be used for an API such as this for IoT devices or equivalent that are not owned or used by normal consumers. So if you only have a 2-legged implementation, that will severely restrict the applicability of this API.

[tlohmar]

I think, the issue is more on the usage of a header within the GET operation to provide sensitive information (e.g. the MSISDN) instead of the POST operation.

A 2-legged access token can be ok for B2B cases, where the API invoker is also the subscription owner / responsible.

[eric-murray]

A 2-legged access token can be ok for B2B cases, where the API invoker is also the subscription owner / responsible.

That depends on the use case. The mobile subscription for my work phone is owned (and paid for!) by Vodafone, but the MSISDN is absolutely my personal data. It's not about ownership, but who can be identified by it. If there is a consumer at the end of the chain, then the subscription identifier will normally be considered personal data for that consumer.

[tlohmar]

That depends on the use case. The mobile subscription for my work phone is owned (and paid for!) by Vodafone, but the MSISDN is absolutely my personal data.

This sounds like a B2B2X (i.e. C or E) use-case, where Vodafone (as CSP) is offering connectivity to Vodafone (as Employer), which is again providing the subscriptions to its employees. Might be easier to use the example of Vodafone (as CSP) offering connectivity to an Enterprise X (as Employer) who is then offering this to its employees.
But I dont understand the consequence of "MSISDN is absolutely my personal data", since the Employer knows the MSISDN (since subscription owner) and is also paying for the usage.

A B2B use-case would be that a CSP offers connectivity to an Enterprise X, who is using the subscription e.g. for Credit Card reader connectivity. The Enterprise X would know the MSISDN and the current device user.

[eric-murray]

But I dont understand the consequence of "MSISDN is absolutely my personal data", since the Employer knows the MSISDN (since subscription owner) and is also paying for the usage.

The consequence is that the MSISDN can be used to identify me. A simple example would be the device-location API. If that locates my MSISDN, then it is almost certainly locating me. If I don't want that, then I absolutely have a right not to opt-in or to opt-out from that API being able to locate that MSISDN. So 3-legged access token.

A B2B use-case would be that a CSP offers connectivity to an Enterprise X, who is using the subscription e.g. for Credit Card reader connectivity. The Enterprise X would know the MSISDN and the current device user.

It would depend on the relationship between "Enterprise X" and the "current device user", of which the CSP is likely to have no knowledge or control. Maybe Enterprise X rents out the PoS terminals to small market traders, who are individuals and not a business.

It is a reasonable assumption that the device user can be identified by the subscription MSISDN (at least, by Enterprise X). Should not the device user have the right not to opt-in to, or to opt-out of, that personal data being processed (for example, to obtain the location of the device, which will almost certainly be the location of the device user and/or their home address)?

Now, you might argue, maybe Enterprise X has a contract with the device user which allows the devices to be located, so they cannot opt-out. But how would the CSP know that? The device user does not have a contract with the CSP. Hence the CSP is still obliged to offer a mechanism allowing opt-in / opt-out where those rights might exist.

[tlohmar]

The consequence is that the MSISDN can be used to identify me. A simple example would be the device-location API. If that locates my MSISDN, then it is almost certainly locating me. If I don't want that, then I absolutely have a right not to opt-in or to opt-out from that API being able to locate that MSISDN. So 3-legged access token.

Yes, for a location API, a 3-legged token should be used, since the current-device-user (employee) should acknowledge the location check, and not the subscription owner (employer/enterprise) . However, Dedicated Networks is not about location, it is about connectivity performance. When the enterprise owns the subscription, the MSISDN is not sensitive data, isnt it? And, should an employee as current-device-user should have an opt-out or opt-in possibility, when the subscription owner changes connectivity performance aspects?

It is a reasonable assumption that the device user can be identified by the subscription MSISDN (at least, by Enterprise X). Should not the device user have the right not to opt-in to, or to opt-out of, that personal data being processed (for example, to obtain the location of the device, which will almost certainly be the location of the device user and/or their home address)?

For personal data certainly yes. However, is the MSISDN always personal data? Should the device user of a PoS device (e.g. a waiter with a Credit Card reader) get an opt-in or opt-out option, when the PoS device gets access to the reserved capacity provided by the Dedicated Network....

Now, you might argue, maybe Enterprise X has a contract with the device user which allows the devices to be located...

Note, the Dedicated Networks API is not about "locating the device".

[eric-murray]

I agree that dedicated networks is not about location, but neither is GDPR. I use that example because it makes it easy to understand why the rules are in place, but the rules apply to "personal data" (e.g. the MSISDN) and not the use case.

So if a 3-legged access token is required for a given MSISDN for location-retrieval, then it is also required for this API.

It can be hard to appreciate that an end user can have the right to "opt-out" of having a better network experience, but they really can if it is specific to a device that is identified by an identifier that is also the personal data of the end user.

This is not a technical concept - it is one for your privacy lawyer.

[tlohmar]

the issue is about passing sensitive information usage of GET (in a header) vs POST (in the body). When the sensitive information is passed within the access-token (3-legged access token), it is applicable for both approaches.

The issue is not about using 3-legged access tokens or not. The API needs to support both cases (2-legged and 3-legged) in order to give the choices for deployments and we may need to update the API documentation to make this clear.

[eric-murray]

Apologies, but I got confused by the issue title and assumed this was only about the x-device header. My comment was that this header is only applicable to 2-legged access token as, device identifiers cannot be passed explicitly when 3-legged access tokens are in use.

For other sensitive information that needs to be passed independent of the access token, either GET header or POST body are acceptable. Most APIs use POST because it is much cleaner and simpler when there are multiple parameters to pass, and keeps everything as a JSON.

[tlohmar]

SimpleEdgeDiscovery has been refactored in v2.0.0 and is no longer using headers for the device object. Instead, device information is provided in the body of a POST operation.

[hdamker]

Coming back to this one, because the thread has been quiet since October and the last comment here
already settled part of it.

The two conclusions on this thread point the same way.

• @eric-murray: "Most APIs use POST because it is
  much cleaner and simpler when there are multiple parameters to pass, and keeps everything as a JSON."
• @tlohmar: "SimpleEdgeDiscovery has been refactored in v2.0.0 and is no longer using headers for
  the device object" — so the precedent the header was modelled on is gone.

There is also a concrete problem with the header that has not been mentioned here. GET /accesses
now returns Link, X-Total-Count and X-Total-Pages, and a Link URL can only carry query
parameters. A device filter supplied in x-device cannot appear in those URLs, so following
next or last as given returns the unfiltered collection, and the counts describe a result set the
links do not reproduce. Every consumer has to know to re-attach the header to each page.

What this suggests is not replacing the operation but splitting it, because it is doing two jobs with
different properties:

Job	Filter	Shape
List the accesses, optionally for one network	networkId, not personal data	GET /accesses?networkId=&page=&perPage=
Find which accesses contain a given device	device, personal data	POST /accesses/retrieve

networkId is already a query parameter, so the first keeps the paginated collection exactly as it is
— and it becomes correct, because every remaining filter is now something a Link URL can carry.

The second follows what the other CQM APIs already do. quality-on-demand, qos-provisioning,
qos-booking and qos-booking-and-assignment each answer "which of these does this device have" with
a POST that takes the device in the request body, and each returns an array with an empty array when
there is nothing to return.

Doing that would let x-device and SerializedDevice be removed, which also removes the need to
specify the RFC 8941 serialization, and it makes the operation names line up with those APIs —
listAccesses for the collection, something like retrieveAccessesByDevice for the query, and
getAccess for the read by id.

Would it make sense to resolve this issue with whichever way you decide?