Skip to main content

Administration

Setting Pinning Mode​

It is also possible to set the pinning mode for a particular device. This changes the way pins are handled for the device and can cause a new dynamic configuration to be downloaded to the app. This command removes all pinning or restrictions for managed trust roots for the app, by causing an empty set of pins to be transmitted as the dynamic configuration:

approov device -add h4gubfCFzJu81j/U2BJsdg== -pinMode unpin

This has the further impact of sending a special dynamic configuration update to the app on the particular device that has all the certificate public key pins removed. This causes all pinning (and any managed trust roots) protection to be removed from the app, allowing a proxy (such as Charles Proxy or MITM Proxy) to be used to intercept traffic between the app and the API endpoints. This can be useful for debug or pentesting. Note that some apps may require a relaunch to unpin after receiving the update if they are not written to be immediately reactive to pinning changes.

Other options may be provided for the pinning mode as follows:

  • block: This transmits a fixed but invalid pin in the dynamic configuration for all domains that have had pins added. This will force the app to experience a pinning failure in the same way it would if the API endpoint's certificates had changed. This can be used for testing what happens in the app when such a certificate mismatch occurs.
  • blockAll: This works like block but it also causes the Approov channel to detect a MITM. This simulates what happens if all TLS traffic is being intercepted. In this case any Approov fetch (that is unable to use a cached result) will receive a MITM_DETECTED error.
  • pin: This is the default and using this option resets the device to the default pinning configuration for the account.
info

Note that since no security policy is explicitly set, the device is assigned the current security policy for the account. You may also set an explicit security policy for the device in the same command.

Listing Your Devices​

A full list of devices that have had a special override security status can be obtained with:

approov device -list

This produces a list, for example:

1 device:
 h4gubfCFzJu81j/U2BJsdg== default,always-pass,all  unpin  A N Other

It shows the device ID, the security policy currently being applied and any pinning mode that has been set (or pin by default).

The name of the user that added the device is also provided. If a device label has been set then this is also shown. This makes it easier to determine the user of a particular device. If security rules version management is in use for the account then the applicable security rules version is also shown for the device, in parentheses after any user name and label, for example A N Other (security rules v3.6.0).

If the device was added by a user with the pentest role then this is also shown as an attribute on the device. A user with the pentest role is only able to see or modify devices that have been added using that role, so that they are not able to determine the device IDs being used for development.

Removing Devices​

A particular device can be removed as follows:

approov device -remove h4gubfCFzJu81j/U2BJsdg==
warning

The standard account policy will be applied to the device within 30 seconds for new Approov fetches. Note that, if the app is already running then a new fetch will be necessary before the new policy is enforced (up to 5 minutes).

Device removal is not restricted to the user that added the device.

Removing Multiple Devices​

Sometimes it is desirable to be able to remove multiple devices with a single command. For instance, if we perform:

approov device -list

We will get a list like the following:

3 devices:
 h4gubfCFzJu81j/U2BJsdg== default,always-pass,all  unpin  A N Other
 VI2c+UugQ6L7v0wkovXOSg== default,always-pass,all  pin  A N Other
 iDpOemiTdame9qvAQF4w/g== default,always-pass,all  pin  Me

You can issue a command to remove all devices associated with the user name A N Other as follows:

approov device -removeMatching "A N Other"

You will be asked for confirmation for the operation:

2 matched devices:
 h4gubfCFzJu81j/U2BJsdg== default,always-pass,all  unpin  A N Other
 VI2c+UugQ6L7v0wkovXOSg== default,always-pass,all  pin  A N Other
WARNING: are you sure you wish to remove these devices
ATTENTION: If you wish to continue then please type YES and return: YES
removed h4gubfCFzJu81j/U2BJsdg==
removed VI2c+UugQ6L7v0wkovXOSg==

You must specify the name in quotes if it contains any spaces. The matching devices will be listed and you will be asked for confirmation.

Note that the provided string also matches against any label that has been provided.

Clearing All Device State​

It is possible to clear the persisted state of all devices in the account. If you are using DeviceCheck Integration, AppAttest or Play Integrity integrations then the previous results of these fetches will be erased and devices will be forced to perform the checks again next time they connect to the Approov service.

You can clear the state as follows:

approov device -clearDeviceState

You need an admin role and confirmation to perform this operation and pay careful attention to the warnings before confirming:

WARNING: clearing device state will require all app installs to redo any DeviceCheck/AppAttest/PlayIntegrity checks
WARNING: consider PlayIntegrity API quota limits as all devices will need to reattest after clearing
WARNING: this will have an immediate impact on your apps in production
ATTENTION: If you wish to continue then please type YES and return: YES
successfully cleared all device state

If you are using Play Integrity and you clear the device state, this means that new attestations will be required for all devices as they perform their first Approov fetch after the reset and this may exceed the Play Integrity API quota you have in place.

Note that clearing the device state will have no impact on your billing or the calculation of hourly, daily or monthly active devices. However, it will impact the derivation of the new-install flag so existing app installations will be considered to be new the next time they fetch an Approov token.

warning

If you are using require-devicecheck, require-appattest or require-playintegrity option flags then you should consider clearing them before using this command. This is because the record of these checks will be cleared, and Approov attestation fails if they have not been completed. However, the checks cannot be performed again until the app is relaunched. Do not enable the option flags again for several days to provide ample opportunity for the apps to have been restarted.

info

If you have a very large app user base and are using AppAttest/PlayIntegrity then you might want to consider AppAttest Rate Limiting or Play Integrity Rate Limiting before using this option to prevent throttling by Apple or Google servers. This is because all subsequent new app launches by apps will attempt to perform an attestation and create a request to the Apple servers.