SHAPES-EXAMPLE.md

Shapes Example

This quickstart is written specifically for native Android apps that are written in Java and use HttpsUrlConnection for making the API calls that you wish to protect with Approov. This quickstart provides a step-by-step example of integrating Approov into an app using a simple Shapes example that shows a geometric shape based on a request to an API backend that can be protected with Approov.

WHAT YOU WILL NEED

• Access to a trial or paid Approov account
• The approov command line tool installed with access to your account
• Android Studio installed (Android Studio Bumblebee 2021.1.1 is used in this guide)
• The contents of this repo

RUNNING THE SHAPES APP WITHOUT APPROOV

Open the project in the shapes-app folder using File->Open in Android Studio. Run the app as follows:

You will see two buttons:

Click on the Say Hello button and you should see this:

This checks the connectivity by connecting to the endpoint https://shapes.approov.io/v1/hello. Now press the Get Shape button and you will see this (or a different shape):

This contacts https://shapes.approov.io/v1/shapes to get the name of a random shape. This endpoint is protected with an API key that is built into the code, and therefore can be easily extracted from the app.

The subsequent steps of this guide show you how to provide better protection, either using an Approov Token or by migrating the API key to become an Approov managed secret.

ADD THE APPROOV DEPENDENCY

The Approov integration is available via maven. This allows inclusion into the project by simply specifying a dependency in the gradle files for the app. The Maven repository is already present in the gradle.build file so the only import you need to make is the actual service layer itself.

The approov-service-httpsurlconn dependency needs to be added as follows to the app/build.gradle at the app level:

implementation("io.approov:service.httpsurlconn:3.5.3")

Make sure you do a Gradle sync (by selecting Sync Now in the banner at the top of the modified .gradle file) after making these changes.

Note that approov-service-httpsurlconn is actually an open source wrapper layer that allows you to easily use Approov with HttpsUrlConnection. This has a further dependency to the closed source Approov SDK itself.

ENSURE THE SHAPES API IS ADDED

In order for Approov tokens to be generated for shapes.approov.io it is necessary to inform Approov about it:

approov api -add shapes.approov.io

Tokens for this domain will be automatically signed with the specific secret for this domain, rather than the normal one for your account.

MODIFY THE APP TO USE APPROOV

Uncomment the three lines of Approov initialization code in io/approov/shapes/ShapesApp.java:

This initializes Approov when the app is first created. The Approov SDK needs a configuration string to identify the account associated with the app. It will have been provided in the Approov onboarding email (it will be something like #123456#K/XPlLtfcwnWkzv99Wj5VmAxo4CrU267J1KlQyoz8Qo=). Copy this into io/approov/shapes/ShapesApp.java:36, replacing the text <enter-your-config-string-here>.

Next we need to use Approov when we make request for the shapes. Change the marked code in io/approov/shapes/MainActivity.java:

Note you will also need to uncomment the ApproovService import near the start of the file.

We pass the HttpsUrlConnection to the ApproovService.addApproov method and this automatically fetches an Approov token and adds it as a header to the request. It also pins the connection to the endpoint to ensure that no Man-in-the-Middle can eavesdrop on any communication being made.

Note that this method may throw an ApproovException (derived from IOException) if it is unable to fetch an Approov token due to no or poor Internet connectivity then ApproovNetworkException is thrown. In this case the user should be able to initiate a retry. Therefore the call should be in atry-catch block, possibly the same one as connect or reads of the body for a GET.

You should also edit the res/values/strings.xml file to change to using the shapes https://shapes.approov.io/v3/shapes/ endpoint that checks Approov tokens (as well as the API key built into the app):

ADD YOUR SIGNING CERTIFICATE TO APPROOV

In order for Approov to recognize the app as being valid, the local certificate used to sign the app needs to be added to Approov. The following assumes it is in PKCS12 format:

approov appsigncert -add ~/.android/debug.keystore -storePassword android -autoReg

This ensures that any app signed with the certificate used on your development machine will be recognized by Approov. See Android App Signing Certificates if your keystore format is not recognized or if you have any issues adding the certificate.

IMPORTANT: The addition takes up to 30 seconds to propagate across the Approov Cloud Infrastructure so don't try to run the app again before this time has elapsed.

SHAPES APP WITH APPROOV API PROTECTION

Run the app and press the Get Shape button. You should now see this (or another shape):

This means that the app is getting a validly signed Approov token to present to the shapes endpoint.

NOTE: Running the app on an emulator will not provide valid Approov tokens. You will need to force the device to always pass (see below).

WHAT IF I DON'T GET SHAPES

If you still don't get a valid shape then there are some things you can try. Remember this may be because the device you are using has some characteristics that cause rejection for the currently set Security Policy on your account:

• Ensure that the version of the app you are running is signed with the correct certificate.
• Look at the logcat output from the device. Information about any Approov token fetched or an error is output at the DEBUG level. You can easily check the validity and find out any reason for a failure.
• Use approov metrics to see Live Metrics of the cause of failure.
• You can use a debugger or emulator and get valid Approov tokens on a specific device by ensuring you are forcing a device ID to pass. As a shortcut, you can use the latest as discussed so that the device ID doesn't need to be extracted from the logs or an Approov token.
• Also, you can use a debugger or Android emulator and get valid Approov tokens on any device if you mark the signing certificate as being for development.

SHAPES APP WITH SECRETS PROTECTION

This section provides an illustration of an alternative option for Approov protection if you are not able to modify the backend to add an Approov Token check. Firstly, revert any previous change to res/values/strings.xml to using https://shapes.approov.io/v1/shapes/ that simply checks for an API key. The shapes_api_key should also be changed to shapes_api_key_placeholder, removing the actual API key out of the code:

You must inform Approov that it should map shapes_api_key_placeholder to yXClypapWNHIifHUWmBIyPFAm (the actual API key) in requests as follows:

approov secstrings -addKey shapes_api_key_placeholder -predefinedValue yXClypapWNHIifHUWmBIyPFAm

Note that this command requires an admin role.

Next we need to inform Approov that it needs to substitute the placeholder value for the real API key on the Api-Key header. Only a single line of code needs to be changed at io/approov/shapes/MainActivity.java:

Build and run the app and press the Get Shape button. You should now see this (or another shape):

This means that the app is able to access the API key, even though it is no longer embedded in the app configuration, and provide it to the shapes request.