Approov Quickstart: Flutter Elixir Phoenix Channels

Approov is an API security solution used to verify that requests received by your backend services originate from trusted versions of your mobile apps.

This is an Approov integration quickstart example for a mobile app built with Flutter and using a backend with Elixir Phoenix Channels. If you are looking for another mobile app integration you can check our list of quickstarts, and if you don't find what you are looking for, then please let us know here.

TOC

• Overview
  • What you will need
  • What you will learn
• Approov Integration Quickstart
  • Approov Plugin Setup
  • Approov Http Client
  • Mobile API Registration
  • Mobile App Binary Registration
• Echo Chamber Mobile App Example
• Next Steps

Overview

What You Will Need

• Access to a trial or paid Approov account

• The approov command line tool installed with Approov account access

• Flutter installed. This quickstart uses version:

  flutter --version
  Flutter 1.22.2 • channel stable • https://github.com/flutter/flutter.git
  Framework • revision 84f3d28555 (3 weeks ago) • 2020-10-15 16:26:19 -0700
  Engine • revision b8752bbfff
  Tools • Dart 2.10.2
  

TOC

What You Will Learn

• How to integrate Approov into a real app in a step by step fashion
• How to register your app to get valid tokens from Approov
• A solid understanding of how to integrate Approov into your own app that uses Flutter with Elixir Phoenix Channels
• Some pointers to other Approov features

TOC

Approov Integration Quickstart in your App

This quickstart is for any developer looking to integrate Approov in their own mobile app. For an hands-on ready mobile app example you can follow the guide for the Echo Chamber app example included in this repo.

Approov Plugin Setup

At the root of your project create a folder named approov:

mkdir approov

Clone the Approov Flutter plugin into the approov folder:

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

NOTE: The Approov Flutter plugin will be located at your-project/approov folder

If you want to build for Android then download the Android Approov SDK and add it to the Approov HTTP Client plugin, by executing from the root of your project:

approov sdk -getLibrary approov/flutter-httpclient/approov_http_client/android/approov-sdk.aar

NOTE: The approov command is downloading the Approov SDK into the folder your-project/approov/flutter-httpclient/approov_http_client/android/approov-sdk.aar

Instead, if you want to build for iOS execute from the root of your project:

approov sdk -getLibrary approov/flutter-httpclient/approov_http_client/ios/approov.xcframework

NOTE: The approov command is downloading the Approov SDK into your-project/approov/flutter-httpclient/approov_http_client/ios

Retrieve the approov-initial.config file and save it to the root of your project:

approov sdk -getConfig approov-initial.config

NOTE: The Approov initial config will be located at your-project/approov-initial.config

Edit your pubspec.yaml and add the Approov SDK and the approov-initial.config to it:

dependencies:
  approov_http_client:
    path: ./approov/flutter-httpclient/approov_http_client

flutter:
  assets:
    - ./approov-initial.config

TOC

Approov Http Client

The last step is to use the Approov Http Client in your code. This is a drop in replacement for the Flutter native Http Client.

So, wherever you have your HttpClient defined, you should replace it with the drop-in Approov HttpClient:

import 'package:approov_http_client/approov_http_client.dart';

//static final httpClient = new http.Client();
static final httpClient = ApproovClient();

Full example code for a Phoenix Channels mobile app:

import 'package:approov_http_client/approov_http_client.dart';

class PinnedHttp {
  static String apiBaseUrl = 'YOUR_API_SERVER_BASE_URL_HERE';

  static final httpClient = ApproovClient();
}

Usage example for protecting the user register/login requests with Approov:

class UserAuth {
  final http = PinnedHttp.httpClient;

  // code omitted for brevity

  Response response = await http
    .post(
      "${PinnedHttp.apiBaseUrl}/auth/login",
      headers: {"content-type": "application/json"},
      body: jsonEncode(credentials),
    )
    .catchError((onError) {
      print(onError);
      return null;
    });

  // code omitted for brevity

}

TOC

Mobile API Registration

Approov needs to know the domain name of the API for which it will issue tokens.

Add it with:

approov api -add your.api.domain.com

NOTE: This only needs to be done one time per API, not for every time you register a mobile app binary.

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.

Adding the API domain also configures the dynamic certificate pinning setup, out of the box. Approov Dynamic Pinning secures the communication channel between your app and your API with all the benefits of traditional pinning but without the drawbacks.

NOTE: By default, the pin is extracted from the public key of the leaf certificate served by the domain, as visible to the box executing the Approov CLI command and the Approov servers.

TOC

Mobile App Binary Registration

In order to use your mobile app with Approov you need to register the mobile app binary each time you build it.

First, build the mobile app by hitting the correspondent button in your IDE.

After the build is finished you can then register the resulting binary with the Approov CLI tool.

For Development:

For Android: from the root of your project execute:

approov registration -add build/app/outputs/flutter-apk/app-debug.apk --expireAfter 1h

For iOS it is necessary to build an app archive (.ipa extension), to sign and to export it. Install the app's .ipa on the device in order to ensure that the installed version and the registered version are the same. Assuming you exported your .ipa to Runner/app.ipa at the root of your project, the registration command is:

approov registration -add Runner/app.ipa --expireAfter 1h

IMPORTANT: During development always use the --expireAfter flag with an expiration that best suits your needs, using h for hours and d for days. By default, an app registration is permanent and will remain in the Approov cloud database until it is explicitly removed. Permanent app registrations should be used to identify apps that are being published to production. Read more in our docs at Managing Registrations.

This registration step is required for each time you change your code, even if you are just commenting out a line of code or fixing a typo in a variable.

The Flutter hot reload functionality doesn't write to the disk any changes made to the code, therefore you cannot re-register the mobile app without stopping it and starting it again, thus for a better development work-flow you may want to whitelist your mobile device with the Approov cloud service. This way the mobile app always get valid Approov tokens without the need to re-register it for each modification made to the code.

For example:

approov device -add h4gubfCFzJu81j/U2BJsdg== -policy default,whitelist,all

The value h4gubfCFzJu81j/U2BJsdg== is the device id, and you can read on our docs the section Extracting the Device ID for more details how you can do it.

For Production

For a production release, you can refer to the Managing Registration section of our docs for instructions on the several methods that can be used for Android and iOS.

TOC

Next Steps

This quick start guide has shown you how to integrate Approov with your existing app. Now you might want to explore some other Approov features:

• Managing your app registrations
• Manage the pins on the API domains to ensure that no Man-in-the-Middle attacks on your app's communication are possible.
• Update your Security Policy that determines the conditions under which an app will be given a valid Approov token.
• Learn how to Manage Devices that allows you to change the policies on specific devices.
• Understand how to provide access for other Users of your Approov account.
• Use the Metrics Graphs to see live and accumulated metrics of devices using your account and any reasons for devices being rejected and not being provided with valid Approov tokens. You can also see your billing usage which is based on the total number of unique devices using your account each month.
• Use Service Monitoring emails to receive monthly (or, optionally, daily) summaries of your Approov usage.
• Consider using Token Binding. The method <AppClass>.approovService!!.setBindingHeader takes the name of the header holding the value to be bound. This only needs to be called once but the header needs to be present on all API requests using Approov.
• Learn about automated approov CLI usage.
• Investigate other advanced features, such as Offline Security Mode, DeviceCheck Integration, SafetyNet Integration and Android Automated Launch Detection.

TOC