Proposal to simplify device object and improve interoperability

[jpengar]

What type of PR is this?

• enhancement/feature
• documentation

What this PR does / why we need it:

PR incorporating the existing DRAFT proposal to simplify the device object and improve interoperability as per issue #171.

The solution proposed to be covered in the scope of this meta release was:

1. Apply the mechanism to rely on the access_token (not providing the device object in the API request) for 3-legged access scenarios. This would fix interoperability in all these scenarios, which is a huge improvement. We can define the device identifier as optional in the API specification and, if not provided, simply refer to access_token. The developer would simply not provide any further device information, which is simpler. The operator does not need to check that the device identifier actually matches the access_token provided and could simply rely on the access_token itself.
2. Validate the current situation among operators regarding the support and use of the networkAccessIdentifier in order to agree on the removal of this identifier for this meta-release.
   At least these two points would be a big improvement over the current situation. To cover all 3-legged scenarios, and in other cases where it is necessary to explicitly provide the device object in the request (such as 2-legged access with client credentials), we would have a smaller set of identifiers that would mitigate the problem a bit. So far, the APIs we are discussing (Device Location family, Device Status, Quality On demand) are mostly consumed with 3-legged access_tokens.

Reference: #171 (comment)

Which issue(s) this PR fixes:

Fixes #171

Special notes for reviewers:

DISCLAIMER: The proposal is a minimum proposal that does not aim to solve all existing problems, and it is recognised that it does not cover all possible future use cases. However, in the context of the next meta-release, the two proposed measures could already be of great benefit.

• Please find relevant context in Revise the device object definition to simplify it #171
• As agreed at the 10 June WG meeting, the DRAFT proposal has been included as an appendix to the API Design Guidelines for the time being. But we would need to decide what is the best place to document it. It could be as an appendix, in another specific document in the Commonalities, or even document it in ICM if the mechanism for relying on the access token is considered more appropriate for the ICM (e.g. in "CAMARA APIs access and user consent management" doc).

Changelog input

- Device object simplification
- Mechanism to rely on access token to obtain device information

Additional documentation

2024-05-23 - Commonalities Ad-Hoc Meeting - Device Object review

[PedroDiez]

Minor indentation comment

In my view proposal and information allocation is fine

LGTM in advance

[PedroDiez]

LGTM

[PedroDiez]

LGTM

[Elisabeth-Ericsson]

We do not think that it is reasonable to remove the networkAccessIdentifier, even though it is not widely used yet.
We actually would like to add a further option to allow identification via the operator token.
For security reasons we see a mandatory need to allow verification of the data subject named in the access token against the target resource, which is input to the api call. We need to keep all option open, especially since we are discussing (in issue #145 in ICM group requesting to support the operator token).

[jpengar]

We are focusing on a proposal in the scope of the next meta release. The proposal to remove the networkAccessIdentifier is precisely because the feedback so far has been favourable to doing so, and there is no explicit feedback from any WG participant that they are currently using it. Of course, it could be revisited for future releases if the WG needs it, and it could be re-evaluated whether or not to include it again.

The operatorToken discussed in camaraproject/IdentityAndConsentManagement#145 is just an open discussion for now (in ICM backlog), so I would suggest not even considering it for this meta release. In fact, operatorToken might fit as networkAccessIdentifier from our point of view, but it should be discussed for a release when there is a clear position and solution defined in CAMARA for operatorToken.

[shilpa-padgaonkar]

Can we try to find a middle way here? I would propose that we could write in the guidelines that the networkAccessIdentifier is only part of the schema to be able to be future-proof and Camara currently does not permit its use.
Post meta-release work, and after the resolution of the relevant issues in ICM, its use will have to be explicitly documented in ICM and in the guidelines.

This will be similar to what we have done for subscriptions where even though event type is an array (for being future-proof), we are allowing for the meta release the use of just single event type and after the meta-release we will target usecases which need subscriptions to support multiple event types.

WDYT?

[jpengar]

If it works and helps us reach an agreement, that would be fine with me. But I think it would be better to just have an artifact definition of what needs to be supported and allowed to be used. And then just evolve it in the next releases.

[shilpa-padgaonkar]

@Elisabeth-Ericsson : Could you please confirm if this suggested middle way would be ok for you as well?

[jpengar]

Middle way agreement applied in 4ae03bb
Please have a look @shilpa-padgaonkar @Elisabeth-Ericsson and suggest any necessary changes to the wording I use.

[jpengar]

If an API client only provides the networkAccessIdentifier, we can return a 422 error, and if the networkAccessIdentifier is provided along with other allowed identifiers, it should be ignored.

Should we also add this to the NOTE included in the common.yaml file? Should it be documented in the corresponding API subprojects?

[javierlozallu]

This clarification is very useful, could you confirm if we can add this in our API subprojects?

[rartych]

This clarification is very useful, could you confirm if we can add this in our API subprojects?

There is general guideline in API Design Guidelines section 6.2 Error Responses - Device Object.
The clarification above is in line with it, so it can be added in subprojects.
If more detailed guideline is needed for networkAccessIdentifier it can be added as a fix for API Design Guidelines.

[PedroDiez]

Agree with Rafal

[Elisabeth-Ericsson]

We (E///) think that we rather should recommend to have the additional validation in place and compare the target device in the access token against the target device named on the API input. This gives additional security and allows for a better reporting in line with GDPR.

[jpengar]

I don't see how comparing the device identifier in the API request to the target device in the access token provides any additional security. And if we take the access token information as the source of truth, if we can rely directly on the access token, we would avoid additional validations that add complexity and new potential points of failure. In addition to improving interoperability as explained in #171 (comment)

[hdamker]

Some suggestion for changes. Especially the template should not be strictly mandatory ("must") as we identified the potential need in QoD for cases where additional information from the device object might be needed. Even if we haven't identified them in detail yet, we want to have the option to describe them in our documentation.

Personal note: I'm not sure if all developers can decide if "the device can be uniquelly identified by the token". If unsure they might provide additional information within the device object, effectively creating the situation that the token is another parameter beside the ones within the device object. Some of them might be validated, others ignored (if not supported).

[shilpa-padgaonkar]

/LGTM

[patrice-conil]

LGTM

[PedroDiez]

LGTM