Customization
Custom Option Policies
It is possible to set particular option flags that affect the implementation of particular rejection policies. This allows fine-grained opt-in to particular capabilities and requirements that are available in security policies. A full set of the available option flags is shown by getting the security policy.
If you make option flag modifications then the whole rejection policy will be changed to custom, so that the individual rejection policies can also be changed in a fine-grained manner.
To enable a particular option, you can run a command similar to the following:
approov policy -addOptionFlag crash-on-memdump
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 feature crash-on-memdump to be enabled (causing an Android app to crash immediately if a memory dump event is detected). 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 an option by using a command similar to the following:
approov policy -removeOptionFlag crash-on-memdump
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).
Note that you cannot apply custom option flags to custom devices.
Annotation Policies
The annotation policy is the third parameter in the comma separated list for setting a security policy. This determines what flags any anno claim in the Approov token may contain. These are a subset of the device property flags. This allows some ancilliary information to be present within the token. This is particularly useful where a valid Approov token is still being issued, but analysis has demonstrated some questionable aspects of the requesting device which may need to be analyzed by the backend API in conjunction with other information sources. It is also possible to have custom annotation policies and we suggest using this if you have a more specific requirement.
The following are valid options:
| Policy | Description |
default | No annotations are made. |
all | Indicates that all asserted Device Properties should be included in the Approov token. This annotation policy should never be enabled for the whole account, only for specific devices, since this information may provide an attacker with significant information about the reasons for any Approov rejection. If constant monitoring of these properties is required in the backend API then we suggest that JWE Approov tokens are used so that the content is encrypted. Note that alternative mechanisms are provided using an Attestation Response Code or Rejection Reasons. We recommend using one of these alternatives instead unless the results of the property checks are to be used as part of the request processing. |
Custom Annotation Policies
In addition to the preset annotation policies, it is also possible to use a customized annotation policy. You should start with the default annotation policy (which doesn't include anything) and then add individual device properties that you wish to include in the anno claim. If such modifications are made then the annotation 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 annotation policy you select.
You should be very selective with the device properties that you add. Typically you should not add properties that are marked as already causing a rejection. The mechanism is really intended for adding a small number of properties where you may wish your backend to perform some additional analysis or steps because they are present, even though they do not cause an outright rejection. For instance, you could choose not to reject rooted devices but could include this property in the Approov token to enforce some additional verification steps in the backend. If you are only including annotations for support purposes, and not automatic analysis, then you should consider using Attestation Response Codes instead.
To add a property to the set that are annotated, you can run a command similar to the following:
approov policy -addAnnotateFlag rooted
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 rooted to be added to the annotation set. 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 annotation set by using a command similar to the following:
approov policy -removeAnnotateFlag rooted
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).
Note that you cannot apply custom annotation policies to custom devices, only the predefined ones.