Identification

Extracting the Device ID

In order to modify the policy of a particular app installation, its ID must be extracted. There are several methods by which this extraction may be done.

Via the logging that is output by Approov when the SDK is first initialized, output with an Approov tag. On Android this can be seen by viewing the logcat output from the device. On iOS, you can look at the console output from the device using the Console app from MacOS. This provides console output for a connected simulator or physical device. Select the device and search for Approov to obtain specific logging related to Approov. Here is an example of the output (in this case from Android) with the device ID h4gubfCFzJu81j/U2BJsdg== shown at the end of the line.
```
2021-05-20 13:56:57.789 29546-29546/com.criticalblue.demo I/Approov: test-account, com.criticalblue.demo, 2.6.0(5647), h4gubfCFzJu81j/U2BJsdg==
```
Via extraction from an Approov token that has been generated on the device. A loggable token contains the device ID directly in the did claim. It can also be extracted from a raw Approov token using the command line tool, for example:
```
approov token -check eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJkaWQiO…
```
Which will output something like the following including the did claim value:
```
failed: alg:HS256
payload: {
  "arc": "CHDCG4GHWJ",
  "did": "h4gubfCFzJu81j/U2BJsdg==",
  "exp": 1669924065,
  "ip": "1.2.3.4"
}
```
Use the value from the did claim, in this case h4gubfCFzJu81j/U2BJsdg==.
By calling the getDeviceID() method on the SDK interface. This provides the base64 encoded string of the device which may be presented in some way within the app.
By looking at the devices that have recently requested an Approov token using approov device -getFetches timed. Note that if you are adding a custom device you can use the shorthand approov device -add latest or approov forcepass -addDevice latest to select any device that has made a request in the last two minutes, as long as it is the only device that has done so.
By adding a device filter, perhaps using your IP address, and then analyzing filtered devices. From this you will be able to see the specific device ID that has been filtered.

Device ID Stability

To respect an individual’s right to privacy, both Apple and Google limit the ability to uniquely identify a device. The identifiers that are truly fixed for a device are hidden and device IDs are generated on-the-fly for new app installations. These, on-the-fly, platform generated device IDs are consistent for the same app but vary across iOS and Android as described below.

Approov device IDs are partly derived from the platform provided device ID, but also include information derived from the app identifier, so device IDs are really always just app installation IDs and cannot identify a particular physical device. If you are developing two different apps on the same physical device you will find that they will be allocated different device IDs. Moreover, any change to the package name of the app will also change the device ID.

The underlying identifiers used to derive the Approov device ID are as follows:

iOS: The identifierForVendor is used. This ID remains constant per app vendor as long as there is one or more apps from the vendor installed. If all the apps are uninstalled then a new ID will be allocated. However, the ID can also change when installing test builds using Xcode or when installing an app on a device using ad-hoc distribution.
Android: The ANDROID_ID is used. Since Android O, this is unique to an app installation and registered device user and is stable across app uninstalls and reinstalls. It will change if your app signing key changes or if the device user performs a factory reset.

Forcing a Device ID to Pass

A particular device ID may be extracted and then be forced to pass for development purposes. Where possible you should consider Auto Registration for this purpose, but there are cases (such as apps running on the iOS simulator) where this is not possible and this option should be used instead. Add the device ID with the command:

approov forcepass -addDevice h4gubfCFzJu81j/U2BJsdg==

The device ID is added to the set that will be forced to pass within 30 seconds. Note, if an app is already running, you will have to wait for a new attestation before a good token will be issued (up to 5 minutes by default). The default set size maximum is 100, and if this is exceeded then the device ID with the earliest addition time will be removed from the set to make room for the new entry.

If the device is the only one that has been used recently on your account you can use the latest shortcut, rather than having to specify the device ID explicitly.

approov forcepass -addDevice latest

Although, you should note that, the device must have performed a fetch in the last two minutes, and must be the only device doing so in that time. This option cannot be used reliably once you have your app in production where there may be a large number of end user Approov fetches in the 2 minute period.

The full list of devices in the forced to pass set can be shown with:

approov forcepass -listDevices

These are listed in time order, so the device most recently added or updated is shown last:

h4gubfCFzJu81j/U2BJsdg== 2023-11-21 11:56:11

Finally a particular device may be removed from the set as follows:

approov forcepass -removeDevice h4gubfCFzJu81j/U2BJsdg==

Forcing a Device ID to Fail

A particular device ID may be extracted and then be forced to fail. You might want to do this to ban some particular device from passing attestation; it will never receive valid Approov tokens or be able to read secure strings. Add the device ID as follows:

approov forcefail -addDevice h4gubfCFzJu81j/U2BJsdg==

The device ID is added to the set that will be forced to fail within 30 seconds. Note, if an app is already running, you will have to wait for a new attestation before a good token will be issued (up to 5 minutes by default). The default set size maximum is 100, and if this is exceeded then the device ID with the earliest addition time will be removed from the set to make room for the new entry.

The full list of devices in the forced to fail set can be shown with:

approov forcefail -listDevices

These are listed in time order, so the device most recently added or updated is shown last:

h4gubfCFzJu81j/U2BJsdg== 2023-11-21 11:56:11

Finally a particular device may be removed from the set as follows:

approov forcefail -removeDevice h4gubfCFzJu81j/U2BJsdg==

tip

If a particular device ID is marked to both fail and to pass, the pass will take priority.

info

The forced failure is only related to the particular device ID. On iOS in particular, if the app containing the Approov SDK is uninstalled and reinstalled again it may be allocated a different device ID. In order to combat this on iOS the DeviceCheck Integration can be used to provide a permanent ban of a physical device, unrelated to the device ID being used.

Adding a Device Security Policy

A specific security policy may be assigned to a device whose ID has been extracted as follows:

approov device -add h4gubfCFzJu81j/U2BJsdg== -policy default,always-pass,all

This causes the given device to have the particular policy applied without applying it to the rest of the account. This change should be actioned for new Approov token requests within 30 seconds. Remember though that if your app is already running on the device and has fetched a token then it might not need to fetch a new one for up to 5 minutes, in which case the revised policy will only be apparent when that new fetch occurs.

The example rejection policy of always-pass is a common one for development and has a similar impact to forcing a Device ID to pass but has more flexibility in terms of being able to apply a specific security policy or various other options. The maximum number of devices with custom policies is more limited (25 by default). Please contact Approov support if you need this limit to be increased. See Enabled Features and Limits for how to view the limit configured in your account.

If the device is the only one that has been used recently on your account you can use the latest shortcut, rather than having to specify the device ID explicitly.

approov device -add latest -policy default,always-pass,all

info

There is a maximum of 25 devices that may be added to an account at one time.

tip

If you don't specify the -policy option when adding a device it will inherit the overall security policy that has been set. Note though you cannot do this if you have set a custom rejection or annotation policy.

Labelling a Device

When adding a device it is also possible to set a label for it to make it easier to remember what device it is:

approov device -add h4gubfCFzJu81j/U2BJsdg== -policy default,always-fail,default -label bobs-iPhone7

This label will then be shown when you list the devices. Note that if you wish to include spaces in the label then you must surround it with quotes. This example uses the rejection policy always-fail to ensure the device never receives a valid Approov token. This may be useful for testing.

Extracting the Device ID​

Device ID Stability​

Forcing a Device ID to Pass​

Forcing a Device ID to Fail​

Adding a Device Security Policy​

Labelling a Device​