Security Schemes and Scopes for Device Identifier API

[eric-murray]

Problem description
Commonalities will shortly adopt modified CAMARA API security guidelines (see Commonalities PR #57. The proposed changes are:

• the defined security scheme should normally be of type openIdConnect
• scopes should follow a defined hierarchical naming convention

For this sub-project, available scopes for the /get-device-identifier endpoint need to be agreed.

Possible evolution
The response to a /get-device-identifier request can be up to 5 fields:

• imeisv
• imei
• tac
• model
• manufacturer

However, these fields are not independent - the lower fields can generally be determined knowing a higher field. For example, tac can be derived from imei, and manufacturer can be derived from tac. Hence a scope allowing the imeisv to be provide also implicitly allows all fields to be provided.

It is proposed to define only two scopes for this endpoint - one allowing "device specific" parameters to be returned (i.e. imeisv and imei) and another allowing only "device model" parameters to be returned (i.e. tac, model and manufacturer). Generally, imei and imeisv are considered to be personal data, whereas the other parameters are not.

The proposed scopes are thus:

• device-identifier:get-device-identifier:read:imei
• device-identifier:get-device-identifier:read:tac

where device-identifier:get-device-identifier:read:imei returns all parameters and device-identifier:get-device-identifier:read:tac only returns tac, model and manufacturer.

Alternative solution 1
Alternative scope definitions can be considered, e.g.:

• A single scope device-identifier:get-device-identifier:read, which returns all parameters
• Individual parameter scopes (requiring up to 5 scopes to be specified if all parameters are required)

Alternative solution 2
The current /get-device-identifier endpoint can be split into two separate endpoints:

• /get-device-imei, which returns imei and imeisv (and possibly also tac, model and manufacturer); and
• /get-device-tac, which returns only tac, model and manufacturer

Each endpoint would have a separate scope:

• device-identifier:get-device-imei:read for get-device-imei; and
• device-identifier:get-device-tac:read for get-device-tac

Additional context
None

[sachinvodafone]

Hi @eric-murray , I believe , two scopes provides clear separation between access to personal and non-personal data and also aligned with privacy principles by limiting access to personal data only when necessary.

[HuubAppelboom]

Hi @eric-murray , I think it should be wise to split these 2 up as much as possible, since the use cases are quite different.

I was even asking myself whether it would not be better to split it even up further, and have 2 separate API's defined, because one will have to communicate what an API can be used for, and then these can be positioned more clearly.

If we keep it as one API, I would propose to go for the 2 separate endpoints, but I would suggest the naming of the endpoints a bit more descriptive by what you would do with it :

Two separate endpoints:

/get-device-identifier, which returns imeisv and imei; and
/get-device-model, which returns only tac, model and manufacturer

and each endpoint would have a separate scope as you propose:

device-identifier:get-device-imei:read for get-device-identifier; and
device-identifier:get-device-tac:read for get-device-model

[sachinvodafone]

I believe , by utilizing different scopes, we can seamlessly accommodate new attribute combinations (imeisv and tac) without creating additional endpoints for keeping any future requirement in mind. This approach will also minimize code duplication on the backend, particularly when the backend network element is same for all. It may also contribute to a reduction in resource overhead compared to having distinct endpoints for each attribute combination.

[eric-murray]

Having discussed this internally, Vodafone's position is to separate the two endpoints for the following reasons:

• Current Identity & Consent guidelines only allow a single scope per endpoint / method
• It keeps the two use cases separate, allowing YAML to be easily split if necessary
• It is technically slightly easier to manage from an implementation point of view

So proposal is to have two separate endpoints as follows:

get-identifier with scope device-identifier:get-identifier which returns:

• imeisv
• imei
• tac
• model
• manufacturer

get-type with scope device-identifier:get-type which returns:

• tac
• model
• manufacturer