Skip to content

Latest commit

 

History

History
181 lines (114 loc) · 11.1 KB

SHAPES-EXAMPLE.md

File metadata and controls

181 lines (114 loc) · 11.1 KB

Shapes Example

This quickstart is written specifically for native iOS and watchOS apps that are written in Swift 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. The project targets both iOS and watchOS, allowing you to execute and integrate Approov independently for each platform.

WHAT YOU WILL NEED

  • Access to a trial or paid Approov account
  • The approov command line tool installed with access to your account
  • Xcode installed (version 16.0 is used in this guide)
  • An iOS mobile device or simulator with iOS 12 or higher or a watchOS device with watchOS 7.0 or higher
  • The contents of this repo

RUNNING THE SHAPES APP WITHOUT APPROOV

Open the ApproovShapes.xcodeproj project in the shapes-app folder using File->Open in Xcode. Ensure the ApproovShapes project is selected at the top of Xcode's project explorer panel.

Select your code signing certificate in the Signing & Capabilities tab and run the application on your preferred device.

Codesign App

Once the application is running you will see two buttons:

>

Click on the 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 Shape button and you will see this (or another 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 SERVICE URLSESSION

The Approov integration is available via the Swift Package Manager. This allows inclusion into the project by simply specifying a dependency in the File -> Add Packages... Xcode option if the project is selected:

Add Packag Dependency

Enter the repositoryhttps://github.com/approov/approov-service-urlsession.git into the search box. You will then have to select the relevant version you wish to use. To do so, select the Exact Version, after which the latest tag from the selected repository should be selected. If you would like to use an earlier version, just replace the latest one, but bear in mind that the combined watchOS and iOS support began with version 3.3.0.

Once you click Add Package the last step will confirm the package product and target selection. Please, make sure you select a library for each one of your targets:

Target Selection

The approov-service-urlsession is actually an open source wrapper layer that allows you to easily use Approov with URLSession. This has a further dependency to the closed source Approov SDK.

ENSURE THE SHAPES API IS ADDED

In order for Approov tokens to be generated for https://shapes.approov.io/v3/shapes 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

Before using Approov you need to import the ApproovURLSession Service. In the ViewController.swift and/or ContentView.swift source file import the service module:

import ApproovURLSession

Find the following line in ViewController.swift and ContentView.swift source file and uncomment it (commenting the previous definition):

//*** UNCOMMENT THE LINE BELOW FOR APPROOV
var defaultSession = ApproovURLSession(configuration: .default)

Now locate and uncomment the line inside the viewDidLoad or init function that initializes the ApproovService and remember to add the config parameter. The approov-service-urlsession needs a configuration string to identify the account associated with the app. You will have received this in your Approov onboarding email (it will be something like #123456#K/XPlLtfcwnWkzv99Wj5VmAxo4CrU267J1KlQyoz8Qo=):

try! ApproovService.initialize(config: "<enter-your-config-string-here>")

The ApproovURLSession class adds the Approov-Token header and also applies pinning for the connections to ensure that no Man-in-the-Middle can eavesdrop on any communication being made.

Lastly, make sure we are using the Approov protected endpoint for the shapes server. Find this line and uncomment it to point to v3 (commenting the previous definition):

//*** UNCOMMENT THE LINE BELOW TO USE APPROOV API PROTECTION
let currentShapesEndpoint = "v3"

Note that from Xcode 14, the minimum deployment target is iOS 11.0 and you will need to update to this in the general settings to allow compilation.

ADD YOUR SIGNING CERTIFICATE TO APPROOV

You should add the signing certificate used to sign apps. These are available in your Apple development account portal. Go to the initial screen showing program resources:

Apple Program Resources

Click on Certificates and you will be presented with the full list of development and distribution certificates for the account. Click on the certificate being used to sign applications from your particular Xcode installation and you will be presented with the following dialog:

Download Certificate

Now click on the Download button and a file with a .cer extension is downloaded, e.g. development.cer. Add it to Approov with:

approov appsigncert -add development.cer -autoReg

This ensures that any app signed with the certificate will be recognized by Approov.

If it is not possible to download the correct certificate from the portal then it is also possible to add app signing certificates from the app.

IMPORTANT: Apps built to run on the iOS simulator are not code signed and thus auto-registration does not work for them. In this case you can consider forcing a device ID to pass to get a valid attestation.

RUNNING THE SHAPES APP WITH APPROOV

Run the app (without any debugger attached) and press the 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.

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 console output from the device using the Console app from MacOS. This provides console output for a connected simulator or physical device. Select the device and search for ApproovService to obtain specific logging related to Approov. This will show lines including the loggable form of any tokens obtained by the app. 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 simulator 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 and get valid Approov tokens on any device if you mark the signing certificate as being for development.
  • Inspect any exceptions for additional information.

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. We are still going to be using https://shapes.approov.io/v1/shapes/ that simply checks for an API key, so please change back the code so it points to https://shapes.approov.io/v1/shapes/.

The apiSecretKey variable also needs to be changed as follows, removing the actual API key out of the code. Find this line and uncomment it (commenting the previous definition):

//*** UNCOMMENT THE LINE BELOW FOR APPROOV USING SECRETS PROTECTION
let apiSecretKey = "shapes_api_key_placeholder"

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. Find the line below and uncomment it:

// *** UNCOMMENT THE LINE BELOW FOR APPROOV USING SECRETS PROTECTION
ApproovService.addSubstitutionHeader(header: "Api-Key", prefix: nil)

This processes the headers and replaces in the actual API key as required.

Run the app again 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 code, and provide it to the shapes request.