ShipFast - Advanced Usage

This guide is for anyone that wants to build all the components used in the Shipfast blog series from scratch. This is not normally necessary as you can follow the blog series using the services and apps deployed and maintained by the Approov team, as described in the blog series and in the top level README. You will need to follow these instructions if you take up the challenge to pentest Approov, presented at the end of the final blog post of the series.

The setup steps can be summarized as follows:

Install dependencies: Docker, Docker Compose, Git, Approov CLI. We capture as many build and deployment dependencies/steps in docker images so we can simplify the overall process and reduce the number of steps we have to document here
Approov Free Trial - Sign up for a free trial Approov account
Google Maps - Obtain Google Maps API Key
DNS records - Configure a sub-domain to be used as the base domain for creating the ShipFast and ShipRaider endpoints. We need web-accessible end-points, so that the Traefik edge-router can automate the process of obtaining and managing LetsEncrypt certs to protect communications between the ShipFast API and the app. It also enables us to use Approov's dynamic certificate pinning which simplifies the management of pinned TLS connections in apps.
Free Auth0 Account - Sign up and configure a free trial Auth0 account
ShipFast Configuration - Clone and configure this repository for building in your environment
ShipFast App APKs - Run the scripts to build the ShipFast APKs. A different APK is generated for each blog post; they can all be installed on a device at the same time
Backend Servers Setup - Configure a box to serve the ShipFast API and the ShipRaider website and deploy it

This process will probably take about four hours, although it will take less if you are already familiar with some of the steps.

Install Dependencies

Please install the required dependencies using instructions appropriate for your host platform

Docker
Docker Compose >= 2.1
Git
Approov CLI

Approov Free Trial

Please sign up for a free trial here. There is a small set of questions and you will need a business email address. Once you have been onboarded, which can take up to 24hrs, you will receive a set of management tokens which you need in order to use the Approov CLI.

Google Maps

The ShipFast app uses Google maps to display locations. Please follow these instructions to get your API key; you will need a Google account.

DNS Records

In our setup, the ShipFast API and ShipRaider website will be deployed in docker containers behind a Traefik edge-router that will manage TLS termination and traffic forwarding. The easiest way to achieve this is to create a new subdomain, from a domain you already own, and then define a wildcard route for that subdomain that will target the box running the services. How you change the DNS configuration will depend on the DNS provider for your chosen domain.

You cannot add the Address records to your DNS configuration until you have deployed the ShipFast services, but you need the DNS names you will use to configure Auth0. So, at this stage, please choose the subdomain you will use and then proceed with Auth0 configuration.

For example, if you controlled the domain, example.com and you chose the subdomain server, you will later need to add the Address record *.server.example.com targeting the server running the shipfast backend examples.

Free Auth0 Account

The ShipFast app uses Auth0 to provide OAUTH2 user authentication. Please sign up for a free Auth0 account on their website.

Configuring Auth0

Once you have an account, please follow these steps to configure it for ShipFast. You will need to replace <<YOUR-ACCOUNT>> with your Auth0 account name and <<YOUR-DOMAIN>> with the domain you chose in the previous step:

Create a new Native Client in the Auth0 dashboard and name it "ShipFast"
Take a note of your Auth0 Domain and Client ID as these will be required later to configure the build.

In the "Allowed Callback URLs" field, enter:

demo://com.criticalblue.shipfast/android,
demo://<<YOUR-ACCOUNT>>.auth0.com/android/com.criticalblue.shipfast.api_key/callback,
demo://<<YOUR-ACCOUNT>>.auth0.com/android/com.criticalblue.shipfast.static_hmac/callback,
demo://<<YOUR-ACCOUNT>>.auth0.com/android/com.criticalblue.shipfast.dynamic_hmac/callback,
demo://<<YOUR-ACCOUNT>>.auth0.com/android/com.criticalblue.shipfast.approov/callback,
https://shipfast.<<YOUR-DOMAIN>>,
https://api-key.shipraider.<<YOUR-DOMAIN>>,
https://static-hmac.shipraider.<<YOUR-DOMAIN>>,
https://dynamic-hmac.shipraider.<<YOUR-DOMAIN>>,
https://approov.shipraider.<<YOUR-DOMAIN>>

Auth0 should already be pre-configured to include Google and GitHub social accounts allowing you to log in to ShipFast with those, but go ahead and add more if you wish.

ShipFast Configuration

The ShipFast build is mainly configured by modifying the .env file in the root of the repository. Then there are bash scripts to build the different components: ShipFast App APKs, the ShipFast API server, and the ShipRaider Web server. These all depend on the same .env file.

Clone the ShipFast Repository

git clone https://github.com/approov/shipfast-api-protection.git && cd shipfast-api-protection

Copy the Example Env File

The example env file, included in the repository file has placeholder values that need to be modified before it can be used to build the components successfully.

cp .env.example .env

Approov Setup

Approov is added to all Apps, although it isn't used until the last blog article.

Download the Approov SDK

approov sdk -getLibrary ./app/android/kotlin/ShipFast/approov/approov.aar

Set the Initial Config for the Approov SDK

approov sdk -getConfig initial-config.txt

Now edit the .env file and add the contents of the file initial-config.txt to the var:

APPROOV_INITIAL_CONFIG=initial-approov-config-here

Approov Secret

The Approov secret will be used to decode the Approov tokens in the ShipFast API.

Retrieve it with:

approov secret ~/path/to/administration.token -get base64

Now edit the .env file and add the secret to the var:

APPROOV_TOKEN_SECRET=approov-secret-here

The ShipFast API Key

The ShipFast API requires an API Key to gain access. For a new build we need to generate one and add it to the .env file:

openssl rand -hex 64 | base64 | tr -d '\n'; echo

or with:

strings /dev/urandom | head -n 256 | openssl dgst -sha256

Now edit the .env file and add it:

SHIPFAST_API_KEY=your-api-key-here

The HMAC Secret

To generate one:

openssl rand -base64 64 | tr -d '\n'; echo

Now copy the output and and add it into the .env file:

SHIPFAST_API_HMAC_SECRET=the-hmac-secret

Google Maps API Key

Now that you have one add it to the .env file:

ANDROID_GEO_API_KEY=your-google-maps-api-key-here

Configuring Auth0 in the .env File

Now edit the .env file and add replace the placehoders for:

AUTH0_DOMAIN=your-domain-for-auth0
AUTH0_CLIENT_ID=your-auth0-client-id

The ShipFast and ShipRaider Domains

Now add the domain for the ShipFast API and the ShipRaider website to the .env file, again replacing <<YOUR-DOMAIN>> with the domain you chose in the DNS configuration step:

SHIPFAST_PUBLIC_DOMAIN=shipfast.<<YOUR-DOMAIN>>
SHIPRAIDER_PUBLIC_DOMAIN=shipraider.<<YOUR-DOMAIN>>

Optional Customization

There is a small amount of customization supported when the apps are built

Custom location

If you are using an emulator, you can configure the default GoogleMaps location that is presented by the app when it starts. (If you are using a real device, then the app will display your current location.)

Add your preferred starting location to the .env file. You will also need to go to the settings for the Android emulator and set the defaults there to use the same coordinates.

DRIVER_LATITUDE=51.535472
DRIVER_LONGITUDE=-0.104971

Custom Currency and Metric System

If you wish, you can adjust the currency symbol and whether to use Miles or Kilometers:

CURRENCY_SYMBOL="£"
DISTANCE_IN_MILES=true

ShipFast App APKs

The ShipFast APKs are built from a docker container that includes all the necessary dependencies. The different steps are triggered by running the supplied bash script with different parameters.

Build the Docker Image

./apk docker-build

Create the Key Store to Sign the APKs

./apk create-keystore

You will need to add the keystore password to the app's properties file, ./app/android/kotlin/ShipFast/local.properties:

android.private.key.password=YOUR_PASSWORD_HERE
android.keystore.password=YOUR_PASSWORD_HERE

Gradle Build for the APKs

To build the APKs for all blog posts at once, run the following command:

./apk gradle build

NOTE: The bash script wrapper supports gradle option forwarding. For example, if you run into problems, try the following: ./apk gradle build --stacktrace. NOTE: The different product flavours can be found in the build.gradle file.

Backend Servers Setup

The server setup relies on Traefik and Docker. Traefik uses LetsEncrypt certificates to secure its TLS connections. You will need to have a server that is accessible through DNS to complete this part of deployment

Install and Setup Traefik

To easily deploy your own online server just follow one of these guides:

AWS EC2 Traefik Setup
Debian Traefik Setup

Once the servers are deployed please make them reachable using the domains you decided on earlier by adding the appropriate DNS Address records.

Install and Setup ShipFast and ShipRaider servers

You will need to run the instructions for this section on the box running the Traefik server you setup in the previous step.

Make a folder to hold files associated with the shipfast deployment. We have used a folder named demo and clone the shipfast repository into that. All subsequent instructions should be run from inside the repository.

mkdir ~/demo
git clone https://github.com/approov/shipfast-api-protection.git ~/demo/shipfast-api-protection
cd ~/demo/shipfast-api-protection

Copy the Env File from your Computer

From your local computer run:

scp .env <<MY-USER>>@<<MY-SERVER>>:~/demo/shipfast-api-protection

Confirm it exists in the online server:

ls -a | grep .env -

output should be something like the following:

.env
.env.example

Building the Docker Images

./shipfast build servers

Deploy the ShipFast API Server and ShipRaider Web Servers

Bring up with:

./shipfast up servers

Tail the logs with:

./shipfast logs --follow