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.