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.
Please install the required dependencies using instructions appropriate for your host platform
- Docker
- Docker Compose
>= 2.1
- Git
- Approov CLI
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.
The ShipFast app uses Google maps to display locations. Please follow these instructions to get your API key; you will need a Google account.
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.
The ShipFast app uses Auth0 to provide OAUTH2 user authentication. Please sign up for a free Auth0 account on their website.
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.
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.
git clone https://github.com/approov/shipfast-api-protection.git && cd shipfast-api-protection
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 is added to all Apps, although it isn't used until the last blog article.
approov sdk -getLibrary ./app/android/kotlin/ShipFast/approov/approov.aar
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
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 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
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
Now that you have one add it to the .env
file:
ANDROID_GEO_API_KEY=your-google-maps-api-key-here
Now edit the .env
file and add replace the placehoders for:
AUTH0_DOMAIN=your-domain-for-auth0
AUTH0_CLIENT_ID=your-auth0-client-id
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>>
There is a small amount of customization supported when the apps are built
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
If you wish, you can adjust the currency symbol and whether to use Miles or Kilometers:
CURRENCY_SYMBOL="£"
DISTANCE_IN_MILES=true
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.
./apk docker-build
./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
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.
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
To easily deploy your own online server just follow one of these guides:
Once the servers are deployed please make them reachable using the domains you decided on earlier by adding the appropriate DNS Address records.
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
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
./shipfast build servers
Bring up with:
./shipfast up servers
Tail the logs with:
./shipfast logs --follow
or with:
./shipfast logs --follow api
Restart with:
./shipfast restart servers
Bring the services down with:
./shipfast down servers
NOTE: you can handle just the API server or the Web servers by replacing
servers
withapi
orweb
, like./shipfast restart api
.
The top level README of this repository contains the urls for the versioned APIs:
- Every time you update the
.env
file you need to restart the servers with./shipfast restart servers
.
This usually happens when you are running the APK for the final blog post, APPROOV_APP_AUTH_PROTECTION
, but the APK has not been registered with the Approov service. Please use the Approov CLI tool to:
- Register the APK.
- Add the API server domain.
After performing the above actions you will need to restart the mobile app in order to get a new Approov token.
-
Make sure you use the same login for the App and for the ShipRaider website
-
If you tweak the location sweep radius and/or the location sweep step you may end up with fewer shipments, or no shipments at all.
-
When using the mobile app on a real device you need to click the "Find My Location" button on ShipRaider.
-
When using the mobile app on an emulator please ensure that:
- in the emulator settings the default location is set to be as near as possible to the coordinates in the
.env
file: theDRIVER_LATITUDE
andDRIVER_LONGITUDE
variables - do not click the "Find My Location" button
- the coordinates shown in the web interface match the ones you set in the emulator settings
- in the emulator settings the default location is set to be as near as possible to the coordinates in the