Skip to content

TODO-APP.md

Latest commit

 

History

History
128 lines (83 loc) · 9.83 KB

TODO-APP.md

File metadata and controls

128 lines (83 loc) · 9.83 KB

Todo App

This is an Approov integration quickstart example for a Todo mobile app built with Flutter and using GraphQL. Approov is an API security solution used to verify that requests received by your backend services originate from trusted versions of your mobile app, and you will see how simple is to integrate it in your mobile app with this example. For a generic Approov quickstart for Flutter GraphQL please check the README.md at the root of this repo.

The base for this Todo app is derived, with gratitude from the hasura/learn-graphql repo, that has a MIT license, that is also on this repo. The Hasura repo is full of tutorials and examples that can be useful to start learning GraphQL or to sharpen your knowledge on it.

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 (version Bumblebee 2021.1 is used in this guide) if you will build the Android app
  • Xcode installed (version 13.3 is used in this guide) to build iOS version of application
  • Cocoapods installed to support iOS building (1.11.3 used in this guide)
  • Flutter stable version 3.0.1 is used in this guide. Note that integration is not possible with stable versions earlier than Flutter 3.
  • The contents of this repo

TRY THE TODO APP WITHOUT APPROOV

First, clone this repo:

git clone https://github.com/approov/quickstart-flutter-graphql.git

Next, open a shell on the directory quickstart-flutter-graphql/src/app-final. You can then use flutter run to build and run the app on a connected physical device.

NOTE: The app will run against this live backend https://unprotected.phoenix-absinthe-graphql.demo.approov.io, and the code for it is in this Github repo.

iOS Potential Issues

If the iOS build fails with an error related to Pods-Runner then navigate inside ios folder using cd ios and run pod install.

If the iOS build fails with a signing error, open the Xcode project located in ios/Runner.xcworkspace:

$ open ios/Runner.xcworkspace

and select your code signing team in the Signing & Capabilities section of the project.

Also ensure you modify the app's Bundle Identifier so it contains a unique string (you can simply append your company name). This is to avoid Apple rejecting a duplicate Bundle Identifier when code signing is performed. Then return to the shell and repeat the failed build step.

Please also verify the minimum iOS supported version is set to iOS 10 if there is a supported version mismatch error.

Android Potential Issues

If the Android build fails with Manifest merger failed : Attribute application@label value=([...]) from AndroidManifest.xml:11:9-46 is also present at [approov-sdk.aar] AndroidManifest.xml:12:9-41 value=(@string/app_name), then open android/app/src/main/AndroidManifest.xml in an editor and make the following changes.

  • Add the schema as an attribute in the manifest tag:
    <manifest ...
        xmlns:tools="http://schemas.android.com/tools"
        ... >
  • Add the android:label and tools attributes to the application tag:
    <application ...
        android:label="@string/app_name"
        tools:replace="label"
        ... >

ADDING APPROOV SUPPORT

Approov protection is provided through the approov_service_flutter_httpclient plugin for both, Android and iOS mobile platforms. This plugin handles all Approov related functionality, including the fetching of Approov tokens, adding these to API requests as necessary, and managing certificate public key pinning.

Look at the quickstart-flutter-graphql/src/app-final/pubspec.yaml and find the lines that are commented that they need to be changed for Approov integration. The Absinthe support is located in the approov-flutter-packages repository and is installed by the changes. This also includes the approov-service-flutter-httpclient package.

Edit the file quickstart-flutter-graphql/src/app-final/lib/config/client.dart by finding the lines that need to be changed when using Approov. Uncomment the appropriate lines and add the config line. The <enter-your-config-string-here> is a custom string that configures your Approov account access. This will have been provided in your Approov onboarding email.

Now edit the file quickstart-flutter-graphql/src/app-final/lib/config/absinthe_socket.dart and locate the line marked for changing to add Approov. Uncomment the line and <enter-your-config-string-here> needs to be replaced by the string you obtained in your onboarding email.

ADDING THE PROTECTED API DOMAIN

The app will run against this backend, that is live at token.phoenix-absinthe-graphql.demo.approov.io, thus we also need to let the Approov cloud service know the API domain for it:

approov api -add token.phoenix-absinthe-graphql.demo.approov.io

The Approov cloud service will not issue Approov tokens for your mobile app if you forget this step, even if the mobile app binary is registered and no tampering is detected with the binary or the environment is running on.

If you want to run the mobile app against a backend you have control of, then you need to follow the deployment guide for the backend of this Todo App.

ADD YOUR SIGNING CERTIFICATE TO APPROOV

You should add the signing certificate used to sign apps so that Approov can recognize your app as being official.

Android

Add the local certificate used to sign apps in Android Studio. The following assumes it is in PKCS12 format:

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

See Android App Signing Certificates if your keystore format is not recognized or if you have any issues adding the certificate.

iOS

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

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.

RUN THE APP

You can now use the Todo app and play with it, but you need to restart it in order for the mobile to get a valid Approov token, because in the first launch it was not yet registered with the Approov cloud service.

WHAT IF THE TODO APP DOESN'T WORK

If you are unable to use the app, or even create an account or log in, then this may be because the device you are using has some characteristics that cause rejection for the currently set Security Policy on your Approov account:

  • Ensure that the version of the app you are running is signed with the correct certificate.
  • Look at the Flutter logging for the device. Information about any Approov token fetched or an error is output at the debug level and is prefixed ApproovService: updateRequest. You can easily check the validity of the loggable token provided 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/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 or Android emulator and get valid Approov tokens on any device if you mark the signing certificate as being for development.
  • Approov token data is logged to the console using a secure mechanism - that is, a loggable version of the token is logged, rather than the actual token for debug purposes. This is covered here.