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 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.0.0
Copyright (c) 2016-2019 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. 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.

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. You can test this 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.

$ approov 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.

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.0.0
Copyright (c) 2016-2019 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. Type:

$ export APPROOV_MANAGEMENT_TOKEN=eyJhbGciOiJIUzI1NiI…

The base64 token string should be copied from the development 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 command invocation. You can test this 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.

$ approov 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.

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.0.0
Copyright (c) 2016-2019 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.