Revise the device object definition to simplify it

[jpengar]

Problem description

In the current existing device object schema, the developer can choose to provide any of the following identifiers:

• ipv4Address, with 2 flavours
• ipv6Address
• phoneNumber
• networkAccessIdentifier

By assuming that each implementation will support a subset of identifier types, we are going against interoperability. A developer will have to code their application to collect and send every available value to maximize/ensure success. This is not a good practice and, in our view, it is not the way to favour interoperability.

At Telefónica, we believe that the current device object schema makes interoperability harder if not all identifiers in the specification are fully supported, or if we don't agree on certain rules about a common subset that should be fully supported. Agreeing on error codes to overcome this is not the long term solution.

Possible evolution

Review and simplify the device object definition with the following considerations:

• Depending on the functionality provided by the CAMARA API, some API subprojects may still define other specific identifiers that differs from the common device object definition proposed here. Not all APIs necessarily have to refer to a user device, e.g. Carrier Billing API only defines a phone number as a way to identify the mobile account to be billed, Know Your Costumer only defines a phone number as a way to identify the associated account data, Home Devices QoD API defines public IP v4 address as a way to identify the user home network, etc.

• Minimize the number of required identifiers as a common subset to be supported by all implementations. Telefónica suggests using the phone number, and the IMSI:

  • Phone number -> We may agree that the phone number is generally the most relevant identifier and it is suitable in most scenarios.
  • IMSI -> to cover mobile scenarios with devices that do not have a phone number associated, e.g. M2M SIM cards. Other options such as ICCID or IMEI could be discussed as an alternative identifier to IMSI. We need to choose one of them that best covers the required scenarios.

• Provide a mechanism for optionally specifying that the device to be considered in the API request is the one associated with the access token used to invoke the API (making potentially device object not necessary in the request). This makes sense for three-legged access tokens.

  • This avoids having to enter multiple identifiers and validate them against each other and against the identifier associated with the access token. Developers would be able to rely directly on the authenticated identifier associated with the access token and simplify the required validations on the operator side when using 3-legged access tokens.
  • In case the access token is a 3-legged token, but the API client still provide a device identifier, the API should validate that the provided device identifier matches the one associated with the access token. If they do not match, the API must return an error.
  • 2-legged access tokens would be not allowed to use this mechanism, as they do not have an associated authenticated identifier. And in this case, the API client must provide a device identifier in the request.

Alternative solution

• There is an ongoing discussion on CAMARA Common YAML: addition of common HTTP Headers for Device Identifiers #118 about specifying the identifiers as HTTP headers. We are also open to discussing this option as a potential alternative to providing the device identifiers in the request body. It might also allow us to use GET operations instead of POST operations with the request body to protect the device information (as it is not recommended to use device information as query parameter in GET operations). However, sending identifiers as HTTP headers does not solve the underlying problem of simplifying the device object as raised in this issue and it should still be considered even if HTTP header are used instead.

Additional context

Regarding IPv4 / IPv6 identifiers, if this information is available, it means that there is a mobile/fixed CSP connection, so the best thing to do is to use Frontend Flow in any case, as described here. Then the API client does not need to retrieve the IP from the device as it is automatically bound to the access token. This way the limitations on the operator side to support IPv4 and/or IPv6 are hidden to the developer and the operator can use the supported mechanism as part of the network based authentication applied in the auth code flow. It is assumed that if a developer can't execute the front-end flow, they will need to have other data to refer to the device: phone number or IMSI. The requirement to explicitly use the IP address, such as in the Simple Edge Discovery API, could be limited to those APIs that have that specific requirement.

And as for the Network Access Identifier, originally defined for use with the GPSI External Identifier, it may not be very developer friendly, and we suggest not including it as a device identifier, as it does not seem reasonable to mandate its support for all implementations unless there is a specific requirement to do so.

[jpengar]

Issue related to #127 discussions. As agreed, this new issue has been created as a separate topic from error definitions.

[jpengar]

@bigludo7 @eric-murray @diegogonmar @PedroDiez @jlurien @mhfoo @pjhac @shilpa-padgaonkar @rartych @uwerauschenbach @Kevsy @gmuratk Let me mention the participants in the related issue #127 to get some feedback in this parallel discussion.

[pjhac]

Hello,

Thank you for bringing your proposal into this discussion. I think that (please note this is my personal view, not necessarily the one from my company) I agree with most of your points. Now, as I am thinking more and more about this, I am under the impression that it is almost impossible to provide a minimal, common subset of fields as a base for all CAMARA APIs, and your example of Home Devices QoD using IPv4 is potentially a good one going against the use of PhoneNumber. Additionally, you indicate that we could avoid giving fields for 3-legged if they can be identified later on in the process, which makes sense, but that wouldn't work for 2-legged.

With that said, I would like to propose another approach, by taking the problem from another viewpoint. What I think may be useful to understand is not the field names, but rather the number of fields and types we need (or see) as "mandatory" ones -- in other words, fields that will prevent the API to work if not provided at all. With that number and associated minimal set of types being known, we could introduce "meta-fields".

Let me give an example. For many of the example APIs you listed, there seems to be at least one field needed independently of the API: the PhoneNumber, the IPv4, or v6. They are all different, so it is difficult to provide a fixed name for a common field. By using a meta-field descriptor, we could provide a baseline for all APIs, which would encompass the minimal set of fields needed, not in terms of names, but in terms of quantity and possible formats.

The Device object could look like this, starting with a single required common parameter (disclaimer: untested and reduced YAML on purpose, this is solely for the example):

Device:
  description: |
    End-user equipment able to connect to a mobile network. Examples of devices include smartphones or IoT sensors/actuators.
  type: object
  properties:
    primaryField:
      oneOf:
        - $ref: "#/components/schemas/PhoneNumber"
        - $ref: "#/components/schemas/NetworkAccessIdentifier"
        - $ref: "#/components/schemas/DeviceIpv4Addr"
        - $ref: "#/components/schemas/DeviceIpv6Address"

NetworkAccessIdentifier:
  type: object
  description: A public identifier addressing a subscription in a mobile network. In 3GPP terminology, it corresponds to the GPSI formatted with the External Identifier ({Local Identifier}@{Domain Identifier}). Unlike the telephone number, the network access identifier is not subjected to portability ruling in force, and is individually managed by each operator.
  properties:
    networkAccessIdentifier:
      type: string
  example:
    {
      "networkAccessIdentifier": "123456789@domain.com"
    }

PhoneNumber:
  type: object
  description: A public identifier addressing a telephone subscription. In mobile networks it corresponds to the MSISDN (Mobile Station International Subscriber Directory Number). In order to be globally unique it has to be formatted in international format, according to E.164 standard, optionally prefixed with '+'.
  properties:
    phoneNumber:
      type: string
      pattern: '^\+?[0-9]{5,15}$'
  example:
    {
      "phoneNumber": "123456789"
    }

...to be continued...

(the example above could probably be made even simpler if we directly pass the oneOf section under the main schema without the "primaryField" entry, but I personally find it simpler to spot it if there is an intermediate reference).

Swagger will still validate that the provided data under Device is syntactically correct and compatible with one of the available sub-objects under the 'oneOf' references. You will note that both PhoneNumber and NetworkAccessIdentifier have an additional level of hierarchy to make them easy to spot (or schema would look like "primaryField": "+18001234567"). Then each API will only need to pick the entries needed; if the API needs more fields that are not common with any existing from the Device baseline, they would be added as usual.

This might look totally crazy, but I wanted to share with the hope it progresses this issue and/or creates debate.

Best regards,
Pierre

[jpengar]

@pjhac Thank you so much for your proposal and feedback. And sorry for the late reply, but I was also waiting to see if we could get some more feedback from other WG participants.

The underlying problem raised by this issue is how to simplify the device object for those APIs that actually need this object definition. I don't think that we/CAMARA really need a device object (and therefore a common subset of fields/identifiers) as a base for all CAMARA APIs. I do believe (as suggested above) that depending on the functionality provided by the CAMARA API, some API subprojects may still define other specific identifiers that differ from the common device object definition proposed here. As mentioned before, an API (e.g. Carrier Billing) may need only the phoneNumber and define only that identifier instead of using a common CAMARA device object if we really want to make it simpler.

Having the ability to rely on the access_token is also a great simplification in all those scenarios that are accessed with 3-legged access_tokens, which will be a large part of them. In all these cases, the developer does not need to worry about which device identifier to use, and the operator does not need to worry about all the validations that are required, as defined and discussed in #127 (no need to check identifiers against each other or against the one associated with the access token, etc...).

If I understand your proposal correctly, it focuses on having a common device object definition for all CAMARA APIs. However, I don't quite see how this would solve the interoperability problem and the simplification of the device object raised here. In what you are proposing I still see the same challenges we have now with the device object... I don't see the difference or the nuance. Even if you define an intermediate PrimaryField and an allOfoneOf schema of sub-objects/identifiers, for those APIs that actually need to identify a device (say QoS, Device Location, Device Status), what does the developer do? What value do they put into that primaryField parameter? They have to choose a format, and in some operators it will work and in others it won't... it wouldn't solve interoperability.

[jpengar]

@bigludo7 @eric-murray @diegogonmar @PedroDiez @jlurien @mhfoo @pjhac @shilpa-padgaonkar @rartych @uwerauschenbach @Kevsy @gmuratk Let me mention the participants in the related issue #127 to get some feedback in this parallel discussion.

Any other feedback @bigludo7 @eric-murray @diegogonmar @PedroDiez @jlurien @mhfoo @pjhac @shilpa-padgaonkar @rartych @uwerauschenbach @Kevsy @gmuratk

[pjhac]

Hi @jpengar,

Thank you for your feedback. I would like to clarify a few points.

Even if you define an intermediate PrimaryField and an allOf schema of sub-objects/identifiers, for those APIs that actually need to identify a device (say QoS, Device Location, Device Status), what does the developer do?

The goal of my proposal is to use oneOf instead of allOf. Therefore, the "primaryField" is not an object with several fields, it is an object with only a single field. As I explained in my example, it can even be defined as "primaryField": "+18001234567" if that helps with simplification.

As such, the idea is to provide a few set of potential field formats, pick one based on what is provided, and still ensure interoperability. In the case where you completely remove the Device object and have each API decide which field(s) it needs, my proposal indeed makes no sense. But if you want to maintain a possible set of possible formats, then this is where my proposal tries to address the issue.

I think that interoperability can only happen if the set of possible fields is defined once and for all, without options unless they really are options (so not needed to execute the API). In other words, if you want to enforce Phone Number for a set of APIs, not proposing potential alternatives is probably the only way forward, and all operators will have to deal with it (and not start to support fancy parameters instead -- if the API says "phoneNumber", it has to be "phoneNumber").

The underlying problem raised by this issue is how to simplify the device object for those APIs that actually need this object definition.

As I read it, it probably calls for this question: which APIs need a common Device object, if at the end of the day such an object does not provide at least 1 common parameter for at least 2 different APIs? (and to note: it probably aligns with your next statement quoted below).

I don't think that we/CAMARA really need a device object (and therefore a common subset of fields/identifiers) as a base for all CAMARA APIs.

That makes sense, and then calls for dropping the Device object (and, in turn, any common base object) for any CAMARA API, is that correct? Or should it imply that some APIs could still want to share a common set of parameters?

I do believe (as suggested above) that depending on the functionality provided by the CAMARA API, some API subprojects may still define other specific identifiers that differ from the common device object definition proposed here. As mentioned before, an API (e.g. Carrier Billing) may need only the phoneNumber and define only that identifier instead of using a common CAMARA device object if we really want to make it simpler.

A concern that I personally see from this is the following: naming consistency of semantically-identical fields across several APIs. By removing a base set of fields, 2 (or more) APIs requiring the usage of a PhoneNumber (or something that resembles a PhoneNumber) might choose to name it differently, for example API A using "phoneNumber" and API B using "pNumber". My proposal was trying to address this semantic (and then syntactic) resemblance by focusing on the format, rather than focusing on the field name, and let the environment (swagger) determine that something following the matching regexp of a Phone Number was provided -- and if the operator does not support it, raise an error.

That said, I believe the next difficulty will be to have consensus on the field to use and enforce it across all operators, which is the crux of the problem as of now -- and the only way to alleviate this is to remove any common object having different possible fields and always enforce a single format. If DeviceStatus and SimSwap both use PhoneNumber, then let them define their Phone Number, with the (agreed) risk that formats and field naming may differ. No operator will be allowed to use something else than PhoneNumber, because the API will not allow it to.

I hope this makes sense and clarifies a few points. If it proves useful to drop a Device object completely, I'm not against it, especially if keeping it brings more problems than it solves any. I'm in favor of consistency, but if it cannot be achieved because no common baseline can be found for multiple APIs, we probably don't have many options left other than asking each API to define its own set of fields.

Best regards,
Pierre

[patrice-conil]

Hi @jpengar, @pjhac
Carefully reading your comment here and many other comments in #127, I agree with Pierre that Device object introduces more problems than it solves and should be removed.
Defining common fields/formats (PhoneNumber, DeviceIpv4Addr...) would be sufficient to ensure semantic consistency between APIs. We could then let each API define what information (PhoneNumber, DeviceIpv4Addr...) is best for its use and set it as mandatory to improve interoperability.

Best regards,
Patrice

[jpengar]

@pjhac

The goal of my proposal is to use oneOf instead of allOf. Therefore, the "primaryField" is not an object with several fields, it is an object with only a single field. As I explained in my example, it can even be defined as "primaryField": "+18001234567" if that helps with simplification.

My mistake, I meant oneOf, not allOf (corrected).

I think that interoperability can only happen if the set of possible fields is defined once and for all, without options unless they really are options (so not needed to execute the API). In other words, if you want to enforce Phone Number for a set of APIs, not proposing potential alternatives is probably the only way forward, and all operators will have to deal with it (and not start to support fancy parameters instead -- if the API says "phoneNumber", it has to be "phoneNumber").

+1

As I read it, it probably calls for this question: which APIs need a common Device object, if at the end of the day such an object does not provide at least 1 common parameter for at least 2 different APIs? (and to note: it probably aligns with your next statement quoted below).

The fact is that there are several existing CAMARA API subprojects (QoS, Device Location family, Device Status...), which for historical reasons, have already defined a common device object with several identifiers (ipv4Address, with 2 flavours, ipv6Address, phoneNumber, networkAccessIdentifier...). So the idea is to simplify this object as much as possible (and make life easier for developers) for those APIs that need it, and to get operators to fully support it to ensure interoperability.

A concern that I personally see from this is the following: naming consistency of semantically-identical fields across several APIs. By removing a base set of fields, 2 (or more) APIs requiring the usage of a PhoneNumber (or something that resembles a PhoneNumber) might choose to name it differently, for example API A using "phoneNumber" and API B using "pNumber".

This should not happen in any case, at least for known parameters such as phone number. In fact, there is a glossary of common terms to avoid this https://github.com/camaraproject/Commonalities/blob/main/documentation/Glossary.md

--

Actually I think we're pretty much aligned. But I think we are now targeting a solution for those existing CAMARA APIs that need to identify a device (as an end-user device to connect to the operator's network) due to the functionality they provide. Other APIs that already use and define other specific identifiers are fine with me. Such as Carrier Billing using the phone number as a way to identify the mobile account to be billed or Know Your Costumer using the phone number as a way to identify the associated account data...
And, as mentioned before, I wouldn't forget the ability to rely on the access_token as a great simplification whenever possible.

[jpengar]

Hi @jpengar, @pjhac Carefully reading your comment here and many other comments in #127, I agree with Pierre that Device object introduces more problems than it solves and should be removed. Defining common fields/formats (PhoneNumber, DeviceIpv4Addr...) would be sufficient to ensure semantic consistency between APIs. We could then let each API define what information (PhoneNumber, DeviceIpv4Addr...) is best for its use and set it as mandatory to improve interoperability.

Best regards, Patrice

What you are suggesting is not incompatible with what we are saying, and I agree with you on many points. But we might not necessarily drop the device object definition, but find a way to simplify it so that it is fully supported by all implementations and/or to provide mechanisms to make it interoperable and usable for developers. For example, to avoid them having to know as many identifiers about the device to make sure it works in as many operators as possible and so on...

[bigludo7]

Additional comments from Orange team (@patrice-conil @assanembengue @m-guez @GuyVidal)

• Very relevant topic - thanks to the TEF team to raised it
• We are not sure about the value to enforce a common device schema to be present in all APIs. We do not use this device in SIM swap API and perhaps we can just API per API provide relevant device identifier to be use (of course from a common dictionary defined in Commonalities).
• About adding IMSI - we understood your point about IoT but how this IMSI is retrieved by the developer. For us, the developer will not be able to get it.
• Fully agreed that for Frontend flow we did not require identifier as we get it from the network. We are more cautious for CIBA flow as developer need to provide an identifier in the login_hint. For example, suppose that we want to trigger a QoD session based on the presence of a device in a zone (here the QoD request should not be triggered from the device itself). This point should be tackled in this discussion
• Last, the externalIdentifier is probably in long term the best identifier (because it includes the domain) but, as of today, with first meta-release looming probably better to remove it.

[AxelNennker]

I am not sure whether APIs need a device object, at least not for API-access after authentication and consent collection, because then the client has an id_token which contains a sub which can be resolved to a device by the RS.

The login_hint might have been used for getting authorization and consent and login_hint's format is standardized here: https://github.com/camaraproject/IdentityAndConsentManagement/blob/main/documentation/CAMARA-Security-Interoperability.md#format-of-login_hint

Developers do not need to concern themselves with the format of sub because the value is opaque to the client developer.
OIDC defines as:

sub
REQUIRED. Subject Identifier. A locally unique and never reassigned identifier within the Issuer for the End-User, which is intended to be consumed by the Client, e.g., 24400320 or AItOawmwtWwcT0k51BayewNvutrJUqsvl6qs7A4. It MUST NOT exceed 255 ASCII [RFC20] characters in length. The sub value is a case-sensitive string.

Some might be pedantic about "End-User" but telcos often put the emphasis on subject which can be anything.

The id_token can contain additional fields besides the standard ones defined by OIDC. If we think Camara APIs need more fields then we should define them in ICM for interoperability.

Regarding client visible identifiers and information in general, we should be cautious what we show the client.
E.g. when booking or using a slice or QoD the BSS or RS might need the IMSI but we should never reveal the IMSI to the client.

An opaque identifier that can be resolved by the RS to the information the RS needs to serve the API is preferable to sending the information itself. The identifier should NOT be globally unique.
OIDC has proposals on how identifiers should be computed. https://openid.net/specs/openid-connect-core-1_0.html#PairwiseAlg

Why not use the id_token as a whole in the API or its field sub and get rid of the device object?

[RandyLevensalor]

• Minimize the number of required identifiers as a common subset to be supported by all implementations. Telefónica suggests using the phone number, and the IMSI:

This needs to support identifiers which apply to fixed line networks and Wi-Fi only devices as well, where phone number, and the IMSI may not be available.

[eric-murray]

@AxelNennker

Why not use the id_token as a whole in the API or its field sub and get rid of the device object?

This as been discussed before, but the argument against is that some regulatory regimes may effectively permit the use of client credentials for authorisation, and hence there will be no ID token associated with the access token.

So I agree that, if a 3-legged authentication scheme is used and an ID token is associated with the access token, then the client should not pass a separate device identifier. But if no end user can be identified from the access token used to call the service API, then some device object must be passed as part of the service API call.

The other comment I will make is that login_hint only works (as defined) to identify the end user by phone number or IP / port. But other methods of identifying the end user are being used which cannot currently be specified as a login_hint. So currently the only way to pass these other identifiers is by using a device object.

[jpengar]

@AxelNennker CC @eric-murray

Why not use the id_token as a whole in the API or its field sub and get rid of the device object?

In the case of 3-legged access (as mentioned in #171 (comment)), I think it is much easier for developers and operators to just rely on the access_token (and the information associated with it on the operator side) provided when accessing the corresponding CAMARA service API. This way:

• CAMARA will not define further requirements for API clients to manage id_token's and use them as device identifiers.
• CAMARA will not define further requirements for operators to validate that the provided id_token as device identifier corresponds to the access_token provided in the API call.
• Should we consider the id_token expiration time and define an error in case of it is expired? We can avoid this complexity.

If CAMARA relies on access_token in case of 3-legged access, we may define the device identifier as optional in the API spec and if not provided just refer to access_token. The developer would simply not provide any further device information, which is simpler. Operator does not have to check if the device identifier actually matches the access_token provided and could just rely on the access_token itself.

2-legged access tokens would not be allowed to use this mechanism as they do not have an associated authenticated identifier. And in this case, the API client must provide a device identifier (e.g. phoneNumber) in the request.

[mhfoo]

In Singapore market context, phone numbers are allocated for mobile broadband SIM cards and Machine-to-Machine SIM cards.
See Singapore National Numbering Plan for details.

[AxelNennker]

In Singapore market context, phone numbers are allocated for mobile broadband SIM cards and Machine-to-Machine SIM cards. See Singapore National Numbering Plan for details.

@mhfoo What is the relationship to device object definition?

[mhfoo]

In Singapore market context, phone numbers are allocated for mobile broadband SIM cards and Machine-to-Machine SIM cards. See Singapore National Numbering Plan for details.

@mhfoo What is the relationship to device object definition?

@AxelNennker

In the earlier ad-hoc call by @jpengar, there are operators indicating that IoT devices, mobile broadband SIM cards do not use a phone number, in their respective market.

The above document is from Singapore regulator. The purpose of the above comment is to indicate the Singapore market context.

[jpengar]

As requested by TSC, and announce by email and slack, yesterday we had the scheduled dedicated meeting call to discuss this Issue #171. You can find the meeting minutes in the link below:

https://wiki.camaraproject.org/display/CAM/2024-05-23+-+Commonalities+Ad-Hoc+Meeting+-+Device+Object+review

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.

It was agreed to set the end of next week (31/05) as the deadline for people to object or respond to the proposal. But if we want to finalise a solution for the next meta release, we need to have a deadline.

CC @rartych @diegogonmar @RandyLevensalor @tanjadegroot @shilpa-padgaonkar @FrimanJan @MarkCornall that you were particularly active in the call, please feel free to add or correct anything I may be missing here.

[jpengar]

Regarding pending action items from yesterday's call:

Action items
[x] @ Jesús Peña Create meeting notes in CAMARA Confluence and link them in #171
[x] @ Jesús Peña Document simplification proposal for next meta-release in #171
[x] @ Jesús Peña Include in #171 the agreed deadline (end of next week - 31/05) to provide feedback on the simplification proposal
[ ] @ Jesús Peña As per request of @ Fabrizio Moggio, include a comment in #171 pointing reviewers to existing CAMARA API Specs already delegating to the information associated to the access_token
[ ] @ Jesús Peña Make a text proposal for the API specs, aimed at the API consumer, on how the access_token delegation mechanism would work

I'm working on it. Please bear with me :)

[gauravji2192]

"Regarding IPv4 / IPv6 identifiers, if this information is available, it means that there is a mobile/fixed CSP connection, so the best thing to do is to use Frontend Flow in any case, as described here. Then the API client does not need to retrieve the IP from the device as it is automatically bound to the access token."

In my private opinion, I would not recommend using Frontend flow for all cases. We must only use authcode flow if it is absolutely necessary to collect user consent for usecases like Location/number verification APIs. Authcode flow puts a lot of requirements on developer community and has back and forth calls in case of an aggregator/channel partner, so we should refrain putting auth code flow requirement to developers if it is not absolutely necessary by regulations.

[jpengar]

Regarding pending action items from yesterday's call:

Action items
[x] @ Jesús Peña Create meeting notes in CAMARA Confluence and link them in #171
[x] @ Jesús Peña Document simplification proposal for next meta-release in #171
[x] @ Jesús Peña Include in #171 the agreed deadline (end of next week - 31/05) to provide feedback on the simplification proposal
[ ] @ Jesús Peña As per request of @ Fabrizio Moggio, include a comment in #171 pointing reviewers to existing CAMARA API Specs already delegating to the information associated to the access_token
[ ] @ Jesús Peña Make a text proposal for the API specs, aimed at the API consumer, on how the access_token delegation mechanism would work

I'm working on it. Please bear with me :)

@FabrizioMoggio @rartych @tanjadegroot et all, please find below a text proposal API consumer-oriented to explain in the required API Specs (info.description field section) how the mechanism would work to rely on access token information to identify the target device of the API request whenever possible.

---

Identifying a user device from the access token

This specification defines the device object field as optional in API requests, specifically in cases where the API is accessed using a 3-legged access token and the device can be uniquelly identified by the token. This approach simplifies API usage for API consumers by relying on the device information associated with the access token used to invoke the API. This mechanism reduces the need for multiple identifiers and extensive validation.

Handling of device information:

Optional device object for 3-legged tokens:

• When using a 3-legged access token, the device associated with the access token must be considered as the device for the API request. This means that the device object is not required in the request, and if included it must identify the same device, therefore it is recommended NOT to include it in these scenarios to simplify the API usage and avoid additional validations.

Validation mechanism:

• The server will extract the device identification from the access token, if available.
• If the API request additionally includes a device object when using a 3-legged access token, the API will validate that the device identifier provided matches the one associated with the access token.
• If there is a mismatch, the API will respond with a 403 - INVALID_TOKEN_CONTEXT error, indicating that the device information in the request does not match the token.

Error handling for unidentifiable devices:

• If the device object is not included in the request and the device information cannot be derived from the 3-legged access token, the server will return a 422 - UNIDENTIFIABLE_DEVICE error.

Restrictions for tokens without an associated authenticated identifier:

• For tokens that do not have an associated authenticated identifier, e.g. 2-legged access tokens, the device object MUST be provided in the API request. This ensures that the device identification is explicit and valid for each API call made with these tokens.

By following these guidelines, API consumers can use the authenticated device identifier associated with 3-legged access tokens, simplifying implementation and validation. This mechanism ensures that device identification is handled efficiently and securely, and appropriately accommodates different token types.

[jpengar]

Regarding pending action items from yesterday's call:

Action items
[x] @ Jesús Peña Create meeting notes in CAMARA Confluence and link them in #171
[x] @ Jesús Peña Document simplification proposal for next meta-release in #171
[x] @ Jesús Peña Include in #171 the agreed deadline (end of next week - 31/05) to provide feedback on the simplification proposal
[ ] @ Jesús Peña As per request of @ Fabrizio Moggio, include a comment in #171 pointing reviewers to existing CAMARA API Specs already delegating to the information associated to the access_token
[ ] @ Jesús Peña Make a text proposal for the API specs, aimed at the API consumer, on how the access_token delegation mechanism would work

I'm working on it. Please bear with me :)

@FabrizioMoggio regarding existing APIs that already rely on the information associated with the access token due to the functionality provided, here are a few examples:

• Number Verification API
• Home Devices QoD API

[jpengar]

All action items from last week's meeting have already been completed: https://wiki.camaraproject.org/display/CAM/2024-05-23+-+Commonalities+Ad-Hoc+Meeting+-+Device+Object+Review

Friendly reminder: It was agreed to set the end of this week (31/05) as the deadline for people to object or respond to the above proposal for inclusion in the next meta-release.

[AxelNennker]

@FabrizioMoggio regarding existing APIs that already rely on the information associated with the access token due to the functionality provided, here are a few examples:

* [Number Verification API](https://github.com/camaraproject/HomeDevicesQoD/blob/main/code/API_definitions/home_devices_qod.yaml)

* [Home Devices QoD API](https://github.com/camaraproject/HomeDevicesQoD/blob/main/code/API_definitions/home_devices_qod.yaml)

@jpengar I do not see that HomeDevicesQoD relies on information associated with the access token.
The ipAddress is required.

I think that ipAddress is not particular well working as an identifier anyway and that information associated with the access token works much better.
If a user requests real_time_interactive, and then the IP-connection is interrupted and a new ipAddress is assigned then the Internet Service Provider might set real_time_interactive for the new owner of the ipAddress.
With a 3-legged access token we do have this problem because the sub is constant.

[jpengar]

@FabrizioMoggio regarding existing APIs that already rely on the information associated with the access token due to the functionality provided, here are a few examples:

* [Number Verification API](https://github.com/camaraproject/HomeDevicesQoD/blob/main/code/API_definitions/home_devices_qod.yaml)

* [Home Devices QoD API](https://github.com/camaraproject/HomeDevicesQoD/blob/main/code/API_definitions/home_devices_qod.yaml)

@jpengar I do not see that HomeDevicesQoD relies on information associated with the access token. The ipAddress is required.

I think that ipAddress is not particular well working as an identifier anyway and that information associated with the access token works much better. If a user requests real_time_interactive, and then the IP-connection is interrupted and a new ipAddress is assigned then the Internet Service Provider might set real_time_interactive for the new owner of the ipAddress. With a 3-legged access token we do have this problem because the sub is constant.

https://github.com/camaraproject/HomeDevicesQoD/blob/807d5f72dd2e43311210198c7278c7848be730b7/code/API_definitions/home_devices_qod.yaml#L77

• The operation is executed for the user whose sub is in the access token used to call this endpoint, and for the home network also deducted from the information included in the access token.
• The target user device is identified by the internal IP address of that device in the home network.
• In case there is no device matching the input criteria, the operation returns a 404 error.

This API is a little bit specific. For example, in this API, we rely on the access token to identify the user and the user's home network, which would normally be associated with a Customer Premise Equipment (CPE), i.e., the home router. In addition, this API needs to define a mandatory IP address parameter to identify a specific device among those connected to the home router. It is the private IP address that the router assigns to this device.

So the access token would actually allow the API server to identify the home router where to apply the requested QoS behaviour (service class).

But it was just an example since I was asked to provide some. But I would focus the discussion on the proposal described above for the next meta release.

[AxelNennker]

* **The operation is executed for the user whose `sub` is in the access token used to call this endpoint, and for the home network also deducted from the information included in the access token.**

* The target user device is identified by the internal IP address of that device in the home network.

* In case there is no device matching the input criteria, the operation returns a 404 error.

I'll admit that I completely misunderstood the use case. Isn't one of the preconditions that the telco/ISP is the operator of the Wifi Access Point? That discussion is more for HomeDevicesQoD...

BTW, the link to NumberVerification your provided above points to HomeDevicesQoD.
https://editor-next.swagger.io/?url=https%3A%2F%2Fraw.githubusercontent.com%2Fcamaraproject%2FNumberVerification%2Fmain%2Fcode%2FAPI_definitions%2Fnumber_verification.yaml
https://github.com/camaraproject/NumberVerification/blob/main/code/API_definitions/number_verification.yaml

[MarkCornall]

I believe we need to be very careful with client credentials and 2 legged scenarios as there is no way defined to know where to route the request where an aggregator is used without inspecting the payload.
CAMARA scope assumes that an aggregating party (Aggregator or operator) can be involved at a global level and that capability should be supported. There was a suggestion from Elizabeth on how that could be achieved but it has never been expanded on.

[jpengar]

Hi @jpengar

About the following:

Restrictions for tokens without an associated authenticated identifier:

For tokens that do not have an associated authenticated identifier, e.g. 2-legged access tokens, the device object MUST be provided in the API request. This ensures that the device identification is explicit and valid for each API call made with these tokens.

Extract from the minutes:

[...] 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.

I think I'm fine with the overall proposal, it indeed simplifies things for 3-legged scenarios and the APIs being discussed.

As for the simplification of the device object in case of 2-legged scenarios, is the plan to drop the device object and let 2-legged APIs define their own set of fields then? Or shall it be discussed/mitigated later?

I just want to ensure I correctly understand the approach for 2-legged cases, apologies if I missed anything.

Best regards, Pierre

@pjhac The idea is to keep the device object definition for those APIs that need to identify a device (we've already discussed that not all APIs necessarily need to refer to a user device, such as Carrier Billing, Know Your Customer, etc, and for those other APIs it's fine to keep the existing approach of defining their own specific identifiers according to the functionality provided), but to reduce the number of possible identifiers by removing networkAccessIdentifier for the next meta-release (we've asked WG participants for feedback on this).
The proposal is summarised in #171 (comment)

[pjhac]

@jpengar Agree with you and I'm fine with this, I was just wondering if the set of attributes (even without networkAccessIdentifier, IP Addresses and PhoneNumber remain) was agreed upon yet or not. Sorry if I was not clear.

Best regards,
Pierre

[jpengar]

I believe we need to be very careful with client credentials and 2 legged scenarios as there is no way defined to know where to route the request where an aggregator is used without inspecting the payload. CAMARA scope assumes that an aggregating party (Aggregator or operator) can be involved at a global level and that capability should be supported. There was a suggestion from Elizabeth on how that could be achieved but it has never been expanded on.

That's true, but IMHO aggregation flows are out the scope of CAMARA. From a CAMARA perspective, the API consumer could be directly an application backend or an aggregator. I think the discussion about routing in an aggregation model when using 2-legged access should be handled in the GSMA Opengateway technical stream. And in any case, I would prefer to keep the discussion here focused on the original objective of this issue.

P.D: But I fully agree that aggregation routing with 2-legged access was something that was not closed in the GSMA Opengateway technical stream.

[MarkCornall]

I believe we need to be very careful with client credentials and 2 legged scenarios as there is no way defined to know where to route the request where an aggregator is used without inspecting the payload. CAMARA scope assumes that an aggregating party (Aggregator or operator) can be involved at a global level and that capability should be supported. There was a suggestion from Elizabeth on how that could be achieved but it has never been expanded on.

That's true, but IMHO aggregation flows are out the scope of CAMARA. From a CAMARA perspective, the API consumer could be directly an application backend or an aggregator. I think the discussion about routing in an aggregation model when using 2-legged access should be handled in the GSMA Opengateway technical stream. And in any case, I would prefer to keep the discussion here focused on the original objective of this issue.

P.D: But I fully agree that aggregation routing with 2-legged access was something that was not closed in the GSMA Opengateway technical stream.

Just saying :)

[RandyLevensalor]

For the three-legged scenarios, I don't see anything that would explicitly limit the scope of the token to a single device.

I agree that we should include the three-legged token when applicable, I think that would have to refer to an array or list of devices associated with the access token. Then perhaps we could reference the index of that device, assuming that we can query them from the API. This feels a like we'd be adding a bit of complexity by relying just the three-legged token rather than simplifying the process

Even with the three-legged scenarios, we'll need to allow for the more explicit ip address or phone number identifiers as well.

[FrimanJan]

Looking at this proposal from the QoD perspective:

• QoD needs to identify not only the device but also the “connection” (PDU session) and therefore the device object is needed in the API call anyways
• Therefore the statement “it is recommended NOT to include it in these scenarios” for 3-legged tokens is a bit too strong. Can we change it to something softer so that APIs that still need to use it are not “breaking” this recommendation?

[jlurien]

Looking at this proposal from the QoD perspective:

• QoD needs to identify not only the device but also the “connection” (PDU session) and therefore the device object is needed in the API call anyways
• Therefore the statement “it is recommended NOT to include it in these scenarios” for 3-legged tokens is a bit too strong. Can we change it to something softer so that APIs that still need to use it are not “breaking” this recommendation?

@FrimanJan in QoD, devicePorts is already independent of device. The proposal is about making device optional when it can be known from the access token, to avoid having to deal with so many identifiers. When this is not possible, device is needed or an error would be returned. Additionally, devicePorts, which is already optional, has to be kept for flow identification purposes.

[eric-murray]

For the three-legged scenarios, I don't see anything that would explicitly limit the scope of the token to a single device.

This is a question for ICM, but with the current three-legged authorisation flows, only a single end user can be associated with the access token. For the OIDC authorisation code flow, only a single device can call the /authorize end point and get the code. And for CIBA, login_hint is currently restricted to being a single phone number or single IP address (+ optional port).

My feeling is that multi-device access tokens may fall into the "too difficult" category for the currently allowed three-legged authorisation schemes, and that a two-legged access token not associated with any end user must be used in scenarios where multiple end users are involved.

[shilpa-padgaonkar]

@jpengar : Thanks for your summary here #171 (comment). We currently do not use networkAccessIdentifier.

[jpengar]

This is a question for ICM, but with the current three-legged authorisation flows, only a single end user can be associated with the access token. For the OIDC authorisation code flow, only a single device can call the /authorize end point and get the code. And for CIBA, login_hint is currently restricted to being a single phone number or single IP address (+ optional port).

+1. And in all these cases, access_token is sufficient.

[gauravji2192]

There may be many use cases for an API request (user invoked API feature request, machine invoked API feature request, API with no legal consent requirement); hence, API must clear define:

• Type of oAuth security mechanism required among CIBA, Authcode and Client credentials based on use cases. It will help developers to understand type of security mechanism required for type of API, consent requirement based on usecase.
• Type of identifier supported. For example, QoD require IP address or any other, location retrieval based on phone number. So that there are commonalities between Operators.

In addition to above,

1. It would be good to understand how IoT devices without phone numbers/sim would be supported in absence of network access identifier?
2. How would a developer know that token is covering necessary information required for network identifier?

[jpengar]

PLEASE NOTE: As requested by @shilpa-padgaonkar in today's bi-weekly Commonalities meeting, due to some holidays in Germany this week, the deadline is extended to next Monday, 03/06 (by the end of the day).
CC @rartych

The deadline for feedback has passed, and it looks like we don't have a clear consensus, if I'm not mistaken. How should we proceed? Should we bring this up again in the next Commonalities call? CC @rartych

Maybe we could try to keep the discussion focused only on the scope of the next meta release (knowing that we are not covering every potential scenario with the existing proposal) to see if we can come to an agreement?

I still think that just the two proposed points, especially the one about delegating in the 3-legged access token, would be a big improvement for existing use cases.

Regarding the networkAccessIdentifier, there has actually been very little feedback, so there is no clear picture of how many operators are actually currently using this identifier. So far, Telefónica and DT have confirmed, Orange also mentioned that they would be fine with removing it for the moment... And my educated guess is that this identifier is not widely used at the moment.

[AxelNennker]

I think that privacy-wise phoneNumber is the worst device identifier because it is globally unique and long lived.
IP addresses are somewhat better because they can be reassigned and there at least theoretically something like ipv6 privacy extensions (that do not really work to prevent tracking IMHO). But the API consumer might know the ip-address already anyway, so there is no sense in not using it IF it is already known.

I view networkAccessIdentifier as a catch-all that is the most privacy friendly, and as networkAccessIdentifier is assigned by the telco (AZ) and is therefore understood by the (telco) RS there is not really a need to specify what the format is.

3GPP defined the GPSI for that. So, I would go for recommending that networkAccessIdentifier is in GPSI-format.

Too bad that the current state of telco implementations is so tracking friendly.

Removing the most privacy-friendly option networkAccessIdentifier does not make me happy, but here we are (again).

APIs should use device-object only when the sub from the authorization code flow is not sufficient in specifying which device needs identification. That would be a API Design guideline "above" the schematics of device-object.

[FrimanJan]

Hi

To get a consensus and close this thread it is crucial that we have a detailed definition of what are included in the access token.

There is new issue #174 opened in the ICM to address this.

[jpengar]

IMHO, the information associated with an access_token (whether it is self-contained or not) is actually implementation dependent on the operator side. Each operator could associate different information depending on their own requirements, but the information associated with the access_token is transparent to the API consumer (access_token is opaque). It would be up to the operators to internally resolve how the API server can validate the information associated with the access token. This has also been discussed in the ICM in camaraproject/IdentityAndConsentManagement#100 and from the TEF side we have also provided some clarifications in camaraproject/IdentityAndConsentManagement#100 (comment). I don't think CAMARA needs to standardise the information associated with an access_token.

[rartych]

As indicated by TSC I have opened the issues in subprojects using Device object to review the proposed changes.

@jpengar As the timeline for Release Candidate is short, could you start drafting the relevant PR?

[jpengar]

2-legged access tokens would not be allowed to use this mechanism as they do not have an associated authenticated identifier

I've created #233 for the WG review. Please take a look and we can iterate on it.