Proposed Enhancement: Include a multi-SIM dependent flag in responses

[eric-murray]

Problem description
The current API description does not specify the API behaviour for multi-SIM scenarios (i.e. scenarios where multiple SIMs share the same primary MSISDN).

For the specified use cases for this API, it is reasonable for an API provider to always return or verify the primary MSISDN, irrespective of which device / SIM is being verified, as that is the MSISDN that will be known to the end user and hence shared with the API consumer.

Hence it can be expected that implementations exist that will always return or verify the primary MSISDN.

However, for some API consumers, particularly where the API is being used for security / fraud prevention, it may be important for them to know whether the device / SIM interacting with their application is the primary device (containing the primary SIM) or a secondary device (containing a secondary SIM).

Currently, they do not know if the device contains the primary or secondary SIM.

Possible evolution
An optional flag can be added to the response to indicate whether the device whose MSISDN is being retrieved or verified is the primary device or a secondary device.

For example:

{
  "devicePhoneNumber": "+123456789",
  "primaryDevice": true
}

Some possible definitions of primaryDevice that can be given to the API consumer could be:

• The device that the mobile subscription account holder would normally use for personal transactions (phone calls, messaging, direct but relatively short interactions with apps)
• The device that mobile subscription account holder would choose to keep if they could only have one mobile subscription
• The mobile subscription account holder's personal smartphone that only they use

Identification of the primaryDevice will therefore be somewhat subjective, but nonetheless it can be expected that the mobile subscription account holder will normally have one, and only one, "primary device" which can be identified with a reasonably high probability by the network operator.

Making the flag optional means this is not a breaking change for any API provider. If it is preferred to keep the response body consistent between implementations, the flag could be made mandatory, but allowed to take a null value for those API providers who do not want to support the feature.

Alternative solution
Support for the feature could be made a requirement by mandating the additional flag with no option to assign a null value

Additional context
None

[AxelNennker]

I am. very unsure what a primary device is. I think at Telekom Deutschland a subscriber can have 10 multisim. A phone, a watch, two BMW, a dog tracker, ... If the subscriber puts a new SIM with a different number into the phone, then there would be no phone that has the multisim. I don't know what the primaryPhone is then.

I think, what we could add to NV responses is "isMultiSim" true/false.

That isMultiSim flag would also better match the title of this issue.
Do customers / ASPs ask for that?

[eric-murray]

Hi @AxelNennker

That's interesting, and a great reason why such a feature needs to be discussed between the different API providers.

So, for DT, there is no distinction between SIMs in a multi-SIM group? The SIMs could be used in any of the devices with no change in the functionality of these devices, and no perceivable difference to the account holder?

In that case, DT would not support the new flag, as it has no meaning for your multi-SIM implementation.

I think a flag simply to indicate whether or not the SIM is part of a multi-SIM group is not a particularly useful fraud marker. That sounds more like a separate standalone API, rather than an additional response parameter from this API.

I updated the issue title to avoid that it dictates possible solutions.

[eric-murray]

I added some possible definitions for "primary device" to help with the discussion and to guide any analysis of the likelihood of correctly identifying such a device.

[HuubAppelboom]

@eric-murray @AxelNennker At KPN we also have multi-sim propositions where we can not tell which sim is the primary device, because both sim cards act as the same.

What may be better is in stead of trying to define or detect what a primary device is, to provide information when a device belongs to a category which may require different handling from an anti-fraud perspective. For example, for Apple iWatch (and similar android smart watches) which use the same phone number as a regular phone, this is often well known to the telco and the end user alike.
So for this category, I would suggest to add an optional boolean to indicate it to be companion device, like:

{
"devicePhoneNumber": "+123456789",
"companionDevice": true
}
This also prevents that the telco shares more information than what parties already know.

And if there are more clear categories that can reliably be identified, and which are needed to be shared to detect/prevent fraud, this can be added with additional booleans.

[eric-murray]

Hi @HuubAppelboom

This is a reasonable proposal.

Is my understanding correct that you propose only two possibilities:

• The companionDevice property is present with value true; or
• The companionDevice property is not present at all

Hence companionDevice: false would never be returned, and if the companionDevice property was not present, then the API consumer could not infer anything about whether the SIM was a primary or secondary SIM.

[HuubAppelboom]

@eric-murray In any case, companionDevice : True should only be returned when it is 100% certain that the device is such a companion device. When it is unknown (because you have 2 identical SIM cards, with no differentiation) or the user has only 1 SIM, you can return False.
Regards
Huub

[ECORMAC]

Hi All,

Is there a need to indicate "Primary device" / "Companion Device" in the resp?

Prior to invoking the NumberVerification API, the API invoker shall get an Access token. This is done, for example, with CIBA, invoking the bc-authorize with a login_hint followed by a token. The login_hint includes the device IP address, or a TS.43 token that the device has obtained, so using these two formats, there is no doubt of which device the numberVerify applies. The third format of the login_hint is an MSISDN, which in this case does not work, due to the multi-SIM aspect (and may cause false verifications if the API invoker sets the “primary device” flag but the user is using a secondary device).

So the login-hint should be enough to allow the network to identify the device (primary/secondary etc)?
Thanks,
Cormac

[HuubAppelboom]

Hi All,

Is there a need to indicate "Primary device" / "Companion Device" in the resp?

Prior to invoking the NumberVerification API, the API invoker shall get an Access token. This is done, for example, with CIBA, invoking the bc-authorize with a login_hint followed by a token. The login_hint includes the device IP address, or a TS.43 token that the device has obtained, so using these two formats, there is no doubt of which device the numberVerify applies. The third format of the login_hint is an MSISDN, which in this case does not work, due to the multi-SIM aspect (and may cause false verifications if the API invoker sets the “primary device” flag but the user is using a secondary device).

So the login-hint should be enough to allow the network to identify the device (primary/secondary etc)? Thanks, Cormac

@ECORMAC Hi Cormac, with Number Verify, most implementations that I know follow currently the authorization code flow, where the MNO retrieves the phone number in the first step, and later compares this with the phone number submitted by the API consumer at the verify step. In this scenario the login_hint is not used.

For the newer TS.43 flow either the CIBA flow is used or (much better) the JWT Bearer Flow.

[HuubAppelboom]

@ECORMAC The issue the companion device solves is that the Operator Token (or the Authorization Code) could be generated on the companion device. For some customers this is allowed, others may see this as a security risk, and they only want to accept the Number Verification done on the primary device

The other thing you need to know is that with many implementations the companion device does have its own msisidn associated with it, but this phone number is never shared with the customer. With the share version of Number Verification, this would mean that you would typically share the msisdn associated with the primay device (so that companion device msisdn is never shared). But this makes it very relevant for API Consumer to know that it is a companion device.

By sharing the companion information, we can offering a working solution for companion devices (for customers who would like to have the primary msisdn verified/shared), and at the same time provide a solution for customers that would like to accept Number Verification only from the primary device.

[eric-murray]

In any case, companionDevice : True should only be returned when it is 100% certain that the device is such a companion device. When it is unknown (because you have 2 identical SIM cards, with no differentiation) or the user has only 1 SIM, you can return False. Regards Huub

OK, so there are three possibilities:

• The companionDevice property is present with value true when the API provider is sure that the identified device is NOT a device that the end user would be using to interact with a "regular" application; or
• The companionDevice property is present with value false when the API provider believes that the device is one that the end user MAY be using to interact with a "regular" application; or
• The companionDevice property is not present at all if, and only if, the API provider does not support this functionality

We can, of course, discuss the definition of a "regular application", as I'm sure someone can come up with a use case where they are using their smart watch for online banking. My preference is to agree a definition of companionDevice based on use case, rather than form factor.

[HuubAppelboom]

• The companionDevice property is present with value true when the API provider is sure that the identified device is NOT a device that the end user would be using to interact with a "regular" application; or
• The companionDevice property is present with value false when the API provider believes that the device is one that the end user MAY be using to interact with a "regular" application; or
• The companionDevice property is not present at all if, and only if, the API provider does not support this functionality

We can, of course, discuss the definition of a "regular application", as I'm sure someone can come up with a use case where they are using their smart watch for online banking. My preference is to agree a definition of companionDevice based on use case, rather than form factor.

@eric-murray This sounds a bit too complex to me, why would it be necessary to bring the application into this ?? After all, the API Consumer knows the application best, why would the API Provider need to detect whether it is a "regular"application.

The issue I see is that the API Consumer wants to know whether the phone number he receives does indeed belong to the SIM as a primary device, or that the phone number is coming from a companion device, which has the phone number of another primary device attached to it. I assume the API Consumer attaches a different risk factor to this class of companion device, under the assumption that they may be easier to be taken over/abused by fraudsters.

In the TS43 specs they are also mentionning that there are actually three forms of companion devices:
SharedNumber - Indicates that the “Shared Number” service is active on the companion device (where the device carries the same MSISDN as the primary one)
DiffNumber - Indicates that the “Diff Number” service is active on the companion device (where the device carries a different MSISDN from the primary one but is assigned to the same subscriber.)
FamilyNumber - Indicates that the configuration is for the “Family Number” service (where the device carries a different MSISDN from the primary one and the MSISDN can be assigned to another individual or subscriber.)

What may be better is to simply share that it is a companionDevice True/False, and the type of the phone number as defined in TS.43
The API Consumer can then always decide what they want to do with the it.

[HuubAppelboom]

@eric-murray Regarding companion devices, with IOS27 you can also have this situation with 2 iphones, where one iphone acts as a primary device, and the 2nd iphone as a companion device. Especially with the phone number share version with TS.43 token it becomes important what number will be shared, and communicating what type of number it is. It may however be straightforward to implement this for the TS.43 flow, but with the authorization code flow, it may become much more complex. So, we probably also need to have an indicator that for this flow the information is not_available. So perhaps not a boolean treu/false, but a deviceType enumarator could work better (like primaryDevice, companionDevice, unknown). And if the device is companionDevice, also indicate what type of phone number it is (sharedNumber, diffNumber, familyNumber).