Fundamentals

A security policy is set at the account level and determines which apps may be issued with a valid Approov token.

What is a Security Policy

Approov provides fundamental checks regarding the integrity of the app itself, so that valid Approov tokens are only issued to valid app instances. Additionally, various other runtime integrity checks are also performed and the results transmitted to the Approov cloud server in a secure manner. Whether these checks should result in an invalid Approov token or not is determined by the security policies that are selected. This gives you the flexibility to permit accesses or block them according to your risk assessments and the characteristics of your user base. For instance, if you develop a banking app, you may take the view that no rooted device should receive a valid Approov token. However, other consumer apps, deployed to certain markets or demographics, may require rooted devices to be accepted. Thus the security stance must be informed by the characteristics of the app’s user base and the particular threats that Approov is being used to defend against.

A security policy is shown and specified as three comma separated individual selections as follows:

• Security Rules Name: The security rules name that should be used. This will normally be set to default.
• Rejection Policy: Policy to be used to determine if a particular request should be rejected and an invalid Approov token issued. This allows preset rejection policies to be set. It is also possible to create custom rejection policies and custom options.
• Annotation Policy: Policy for including device property information in the Approov token itself. It is possible to create custom annotation policies.

When a new account is created it is allocated a security policy of default,default,default. This only issues valid Approov tokens where no threat has been detected.

info

Note that security policies may also be set for individual devices as well as the whole account as described in Managing Devices. For this reason blanket policies such as always-pass and always-fail are provided that would not normally be applied to the whole account.

Device Properties

When Approov analyzes a particular app instance, and the environment in which it is running, it will perform an assessment against a number of different possible device properties. Any particular analysis may result in a number of different device properties being detected. The full set of possible device properties is subject to change, as new ones may be added as enhanced detection capabilities are added in new Approov versions. In some cases these may be added dynamically via security rules updates. Therefore the full set of device properties is not fixed, and you must use a command to retrieve the current set. This command also provides the currently selected security policy:

approov policy -get

This outputs the current setting as follows:

security policy is "default,allow-root,all" meaning:
  rules: default (Default security rules)
  rejection: allow-root (Accept rooted Android devices but reject emulators/simulators and Frida/Cydia/Cycript)
  annotation: default (No device properties provided)

device property flags:
  reject app-not-registered    App is not registered, which may indicate that it is fake or tampered
  ...

option flags:
  enabled  allow-debug         Allow debugging of the app (only do this for development purposes)
  ...

The output is in three parts:

• Security Policy Summary: The first part of the output provides information about the security policy selected, including a description of the effect of each component of the policy. If you have set custom rejections or set custom options then the rejection policy is shown as custom. Furthermore, If you have set custom annotations then the annotation policy is shown as custom.

• Device Property Flags: The full set of device properties that are determined for each device then follows, with a short description for each. A reject tag is added to the output next to any device property that will cause a rejection if the property is detected. Thus you can see the impact of the chosen rejection policy at a fine grain level. A rejection causes a failed invalid Approov token to be returned. A device property may also be marked with annotate meaning that this property will be included in the anno claim of any Approov token if it is detected.

• Option Flags: The full set of options that you may enable that influences the policy. This allows you to opt in to particular behaviours or requirements, such as requiring a Play Integrity or AppAttest from every device. A enabled tag is added to those options that have been selected.

Changing Security Policy

The security policy may be changed for the account using the following command:

approov policy -set default,allow-root-and-jailbroken,default

You will be asked for confirmation:

WARNING: updating the security policy will have an immediate impact on your apps in production
ATTENTION: If you wish to continue then please type YES and return: YES

This requires an admin role and confirmation. This particular command will change the security policy to allow rooted and jailbroken devices. The user must confirm the confirmation prompt in order to apply the new security policy.

warning

If adding the new security policy is confirmed then it will have an effect on the account within 30 seconds. Care must be taken when making changes like this to a live account in case a new policy has a detrimental impact on legitimate users of your app.

Rejection Policies

The rejection policy is the second parameter in the comma separated list for setting a security policy. A number of preset options are available and the selection determines the set of device properties that cause a rejection of a fetch request. It is also possible to have custom rejection policies and we suggest using this if you have a more specific policy requirement.

The options are as follows:

Policy	Description
default	Reject all rooted/jailbroken devices, emulators, simulators, frameworks and cloned multiapps.
initial	This is only provided for backward compatibility with older versions of Approov and should not be selected. It rejects all rooted/jailbroken devices, emulators, simulators, frameworks and cloned multiapps. This policy is identical to default, except it has the side effect of disabling any defences that might cause an app to crash if it is being debugged.
allow-cloned	Reject all rooted/jailbroken devices, emulators, simulators and frameworks. However, cloned apps running in multiapps are allowed.
allow-root-and-jailbroken	Accept rooted Android, iOS jailbroken devices, emulator/simulators, cloned multiapps but reject Cydia/Cycript/Frida.
always-pass	A highly permissive policy that generates valid Approov tokens except when there is direct evidence of tampering in the Approov SDK. This generates valid tokens even if the app is not registered. This will typically only ever be applied to individual devices. Note this also has the side effect of disabling any defences that might cause an app to crash if it is being debugged. The app may need to be restarted to remove any already applied protection.
always-fail	Always rejects, thus generating invalid Approov tokens. Typically this will only ever be applied to individual devices.

Custom Rejection Policies

In addition to the preset rejection policies, it is also possible to use a customized rejection policy. The most applicable rejection policy should be used as the starting point, then it is possible to add or remove individual device properties to modify what will cause a rejection. If such modifications are made then the rejection policy will be automatically changed to custom. You can set a new security policy at any time, which will discard your custom policy and replace it with the preset policy you select.

Firstly get the current security policy as detailed in device properties. This shows the current reject status for each device property flag. To add a property to the set that cause a rejection, you can run a command similar to the following:

approov policy -addRejectFlag automated

Confirmation needs to be provided:

WARNING: updating the security policy will have an immediate impact on your apps in production
ATTENTION: If you wish to continue then please type YES and return: YES

This causes the device property flag automated to be added to the set that will cause a rejection. You can see the status by getting the security policy. Note you need an admin role and confirmation to perform this operation.

You can also remove a device property from the rejection set by using a command similar to the following:

approov policy -removeRejectFlag automated

warning

Within 30 seconds the customized policy will be applied to 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).

info

Note that you cannot apply custom rejection policies to custom devices, only the predefined ones.