Approov Installation

Setup

Requirements

In order to integrate Approov you will need the following:

  • Approov account. You can sign up on the website. When you sign up you will receive management tokens for accessing your account.
  • Server exposing the API that you want to protect.
  • Android and/or iOS app that communicates with that API.
  • Development environment to compile the app. More detailed software requirements are in the SDK Integration section.

Approov Tool

All management of the Approov account is done using a command line tool available for Linux, MacOS and Windows. Examples are provided showing how to use this tool throughout the documentation, and a detailed reference for all the commands can be found in the Approov CLI Tool Reference. The first step in using Approov is to install this tool on your system and make a management token accessible to the tool so it is able to authorize itself to the Approov servers. On sign up you will receive development and administration management tokens.

The latest version of the Approov tool can be downloaded directly from here. Note that if a new version of the tool becomes available then an upgrade availability message will be shown when you invoke the tool. This will provide a link to the new version.

You should make your development token available as an environment variable. Doing this means that you will not need to type the path to the token on each command invocation. This is explained in the installation sections below.

Most command operations can be carried out using a development token, with an administration token reserved for a few more specialized operations. We suggest that you only ever put your development token in an environment variable. You can make explicit reference to the administration token, stored in a file, if an operation requires one. This reduces the chances of an accidental operation being performed with an administration token.

The approov command line tool has been tested on Ubuntu Linux 18.04, MacOS Mojave 10.14.2, MacOS Catalina 10.15.3 and Windows 10.

Installation on Linux

The tool download package includes a Linux subdirectory containing the approov executable. This should be placed in a directory that is on the $PATH. All examples in the documentation assume the approov tool is on the path and can be invoked directly.

Linux systems normally expect a bin directory at ~/bin or ~/.local/bin, and automatically include them in your $PATH:

$ cat ~/.profile | grep '/bin' -
if [ -d "$HOME/bin" ] ; then
    PATH="$HOME/bin:$PATH"
if [ -d "$HOME/.local/bin" ] ; then
    PATH="$HOME/.local/bin:$PATH"

You could, for instance, write the approov executable to ~/bin or ~/.local.bin, which should already be on your $PATH, or if you prefer you can add it to /usr/local/bin, but you will need sudo permissions to copy it there.

Alternatively, you can create a new approov directory in your home directory (or other location of your choice) and then add this directory to your $PATH defined in the ~/.bashrc (or other depending upon the shell used). For example the following can be added if the approov executable has been written to ~/approov-tool:

PATH=~/approov-tool:$PATH

When you install the Approov CLI tool in a custom location, like ~ /approov-tool, and after you add this location to the $PATH, you need to reload your shell source ~/.bashrc, otherwise invoking approov will fail.

Once you have approov installed on the path you can check that it is accessible by typing:

$ approov
Approov Tool 2.2.0
Copyright (c) 2016-2020 CriticalBlue Ltd.
…snip…

You should see the overall usage information if the tool is accessible.

Now you should add your development token to your environment. You can do this easily with the following command:

$ read -r APPROOV_MANAGEMENT_TOKEN < development.tok; export APPROOV_MANAGEMENT_TOKEN

The parameter development.tok should point to the file containing the development management token that you received on signup. You can test the environment variable was set with the following command that provides information about the management token you are using.

$ approov whoami
account: my-account (https://admin-something.approovr.io)
userName: A N Other (development)
userEmail: other@domain.com
expiry: 2029-05-08 15:01:05

If you get something like this then it indicates that the management token is being read okay and you are ready to proceed. Alternatively, if you get the following then there is an issue with the setup.

$ approov whoami
No management token specified in APPROOV_MANAGEMENT_TOKEN or on command line

Note that the environment variable APPROOV_MANAGEMENT_TOKEN will only be set while this shell is running. If you want to make the setting more permanent then you can edit your ~/.bashrc file (or equivalent for other shells) and add the line:

APPROOV_MANAGEMENT_TOKEN=eyJhbGciOiJIUzI1NiI…

The string for your development token should be copied from the development token file you received on account signup. Alternatively you can run the read command above in the context of your shell startup. Now any newly created shells have the management token available in the environment so that it is not necessary to make it available on each approov command invocation.

If you intend to use Android App Bundles then you should also ensure the Android Bundletool is installed

Installation on MacOS

The tool download package includes a MacOSsubdirectory containing the approov executable. This should be placed in a directory that is on the $PATH. All examples in the documentation assume the approov tool is on the path and can be invoked directly. We suggest you write the approov executable to /usr/local/bin which should already be on your $PATH. You will need sudo permissions to copy it there.

Once you have approov installed on the path you can check that it is accessible by typing:

$ approov
Approov Tool 2.2.0
Copyright (c) 2016-2020 CriticalBlue Ltd.
…snip…

You should see the overall usage information if the tool is accessible.

Now you should add your development token to your environment. You can do this easily with the following command:

$ read -r APPROOV_MANAGEMENT_TOKEN < development.tok; export APPROOV_MANAGEMENT_TOKEN

The parameter development.tok should point to the file containing the development management token that you received on signup. You can test the environment variable was set with the following command that provides information about the management token you are using.

If you get something like the following then it indicates that the management token is being read okay and you are ready to proceed.

$ approov whoami
account: my-account (https://admin-something.approovr.io)
userName: A N Other (development)
userEmail: other@domain.com
expiry: 2029-05-08 15:01:05

Note that starting with MacOS 10.15.0 Catalina, Apple has changed the way Gatekeeper verifies binaries downloaded from the Internet, and disabled the “open anywhere” option from System Preferences. Thus, the following dialog box will appear the first time trying to run the approov executable:

alt_text

In order to execute the binary, you need to open the System Preferences panel and in the Security and Privacy section click the Allow anyway button.

alt_text

The next time the approov binary is invoked, a slightly different message will appear:

alt_text

You can now select the Open option, which will allow the binary to be executed.

alt_text

If you get the following then there is an issue with the setup.

$ approov whoami
No management token specified in APPROOV_MANAGEMENT_TOKEN or on command line

Note that the environment variable APPROOV_MANAGEMENT_TOKEN will only be set while this shell is running. If you want to make the setting more permanent then you need to edit your shell initialization file. This is ~/.bashrc for versions prior to Catalina, or ~/.zshrc since Catalina which uses the zsh by default. If you are using a non-standard shell then you will need to consult its documentation.

Add the line:

export APPROOV_MANAGEMENT_TOKEN=eyJhbGciOiJIUzI1NiI…

The string for your development token should be copied from the development token file you received on account signup. Alternatively you can run the read command above in the context of your shell startup. Now any newly created shells have the management token available in the environment so that it is not necessary to make it available on each approov command invocation.

If you intend to use Android App Bundles then you should also ensure the Android Bundletool is installed

Installation on Windows

The tool download package includes a Windows subdirectory containing the approov.exe executable. This should be placed in a directory that is on the $PATH. All examples in the documentation assume the approov.exe tool is on the path and can be invoked directly. Check you have approov.exe installed on the path (or in the current directory) by typing:

$ approov.exe
Approov Tool 2.2.0
Copyright (c) 2016-2020 CriticalBlue Ltd.
…snip…

You should see the overall usage information if the tool is accessible.

Now you should add your development token to your environment. Open the advanced settings page:

Windows Advanced Settings Page

Then click on the “Environment Variables” button. This opens up another dialog where you can click on the “New” for user variables to add a new environment variable. The token should be put in the user, rather than system, variables so that it is not accessible to other users of the same machine.

alt_text

The development token string should be copied from the token file you received on account signup.

Now any newly created shells have the management token available in the environment so that it is not necessary to make it available on each approov.exe command invocation. You can test this with the following command that provides information about the management token you are using.

$ approov.exe whoami
account: my-account (https://admin-something.approovr.io)
userName: A N Other (development)
userEmail: other@domain.com
expiry: 2029-05-08 15:01:05

If you get something like this then it indicates that the management token is being read okay and you are ready to proceed.

$ approov.exe whoami
No management token specified in APPROOV_MANAGEMENT_TOKEN or on command line

If you get this then there is an issue with the setup.

Note that the remainder of this document uses approov for invocation of the command line tool. Remember on Windows you will need to use approov.exe instead.

If you intend to use Android App Bundles then you should also ensure the Android Bundletool is installed

Android Bundletool Installation

In order to use App Bundles with Approov you need to make the Android bundletool available. The bundletool is a command line tool written in Java and distributed as a .jar. To use it you will need Java installed, although it is likely you have it installed already if you are developing Android apps. It can be installed from here. Once you have Java installed you can download the latest version of the bundletool from here. If you have saved the bundletool-all-<version>.jar to the current directory then try a command such as:

$ java -jar bundletool-all-0.11.0.jar version
0.11.0

Substitute the filename to the version you have. This confirms that it is running correctly.

When you make a registration of a .aab Android app the approov tool needs to be able to invoke the bundletool and therefore needs to know its location. This can be done by specifying the -bundletool option providing its path for all registrations of app bundle .aab files. Alternatively the path of the bundletool jar file can be set in the environment variable APPROOV_BUNDLETOOL. This can be made permanent in a similar manner to the APPROOV_MANAGEMENT_TOKEN so that there is no need to set it each time the development machine is restarted.