Application thumbprint

App integrity levels

In the Token Server configuration you can select one of the two app integrity levels: NONE or FULL. The FULL level will perform a number of sanity checks for the app, including a tampering/modification check by calculating its thumbprint. The Application thumbprint is calculated by the SDK at runtime during the DCR and it is verified against the application thumbprint stored in the Token Server. To calculate the thumbprint for the Token Server configuration please use the thumbprint calculation tool.

When the app integrity level is set to NONE, the SDK will perform only the most basic sanity checks (like the app's name), but will not calculate the thumbprint.

Obtain the thumbprint calculator

Onegini support can provide you with the application thumbprint calculator. It can be downloaded from the Onegini Artficatory repository where also the Android SDK can be downloaded from. The tool is a java application that is packaged as a jar file. The artifact is called android-app-signature-calculator.

You must download the 2.1.0 or newer version of the thumbprint calculator tool.

Requirements

In order to execute the tool you need to have Java 8+ installed on you machine.

Calculate value

Once you have obtained the thumbprint calculator you can execute it. The tool is a java utility that you need to execute from the command line.

Perform the following command:

java -jar android-app-signature-calculator-2.1.0.jar {PATH_TO_APPLICATION_BINARY}

If the provided path is valid the tool will print the calculated thumbprint value.

Calculated thumbprint - a491d0374840ac684d6bcb4bf9fc93ee4d9731dbe2996b5a1db2313efb42b7e

Optional flags

The calculator takes two additional flags:

• -quiet or -q to return the calculated thumbprint without additional Calculated thumbprint label
• -packageName or -p to calculate the thumbprint based on the provided package name rather than the binary itself. This option is less secure since it disables the tampering protection.

Store the application thumbprint

The value that is calculated must be stored in the Token Server admin console. Every application version has it's own specific application thumbprint, since the thumbprint will change for every build that you make of an application. The Token Server application version documentation provides more info on where and how to store the application thumbprint for a specific application version.

Limitations

The application thumbprint changes whenever the application is modified. If the application thumbprint changes you need to update the Token Server configuration with the new value. Communication will fail if the thumbprint that is configured in the Token Server configuration does not match the thumbprint of the
application. Please note that some Android features like "App Bundles" or "App signing by Google Play" modify the application thumbprint. Also some custom firmwares for rooted devices (notably "AvatarRom") apply a zipalign when the application is installed, resulting in changed application thumbprint. In such cases, if the tampering detection is enabled, the SDK will not allow to use the tampered application.

If you plan to use features that can modify the application thumbprint (like the Google Play app signing) you should use a NONE
integrity level in the Token Server application configuration.