Approov Installation

Setup

Requirements

In order to integrate Approov you will need the following:

  • Approov account. You can sign up for a free trial. You will receive an email with the subject Approov Onboarding with activation information.
  • Approov tool that can be downloaded directly from here.
  • 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 Android SDK Integration and iOS SDK Integration sections.

Initializing the Approov CLI

All management of the Approov account is done using a Command Line Interface (CLI) tool available for Linux, MacOS and Windows and downloaded from here. Examples, showing how to use this tool, are provided 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 then initialize it using the information provided in the Approov Onboarding email. If you are the account owner, initialization will grant account access with dev (development) and admin (administration) level roles available. Most operations can be carried out using the dev role, but the admin role is necessary for certain operations needing elevated privileges. If you received your Approov Onboarding email as a result of being added to an existing Approov account then you will be provided with a specific access role.

Follow the instructions to install the Approov CLI on Linux, MacOS or Windows. Once you have done this can proceed with the remainder of these instructions.

Initialize access to your Approov account using the information from the Approov Onboarding email. Copy and paste the instruction from the email, such as:

$ approov init myaccount 542f15e4-6224-43c2-8e4b-015c5a5251cd
IMPORTANT: your recovery PIN is 287572 - make a note of this in case you ever need to recover your access
please provide a password (6 characters or more) to protect access
enter password:
confirm password:
approov access has been initialized - use "approov role" to see available roles

If approov cannot be found then there has been an issue with the OS specific installation.

This operation grants access to your Approov account from your machine. The parameter myaccount is the identifier of your allocated Approov account. The next parameter is a time limited onboarding code for your account.

You will normally be invited to choose a password for your access to Approov. If your onboarding included a dev role then this will be automatically selected for subsequent uses of the Approov CLI. You will be invited to type in the password again on first usage, and after every one hour session expires.

Note that you are also provided with a PIN number. You should make a note of this somewhere private and secure, it will be needed if you ever need to recover access to your account via email. The PIN provides an additional level of protection for your Approov account in case access to your email account is compromised.

You are now ready to start using Approov!

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

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.

Installation on Linux

The 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. So you could, for instance, write the approov executable to ~/bin or ~/.local/bin, which should already be on your $PATH. If you prefer you can add it to /usr/local/bin instead, 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, such as ~/approov-tool, and after you add this location to the $PATH in your ~/.bashrc, you need to reload your shell source ~/.bashrc, otherwise invoking approov will fail.

Installation on MacOS

The 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.exe executable to /usr/local/bin which should already be on your $PATH. You will need sudo permissions to copy it there.

Installation on Windows

The download package includes a Windows 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.

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-1.4.0.jar version
1.4.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.