Approov Quickstart: Mendix React Native

This quickstart is written specifically for Android and iOS apps that are implemented using Mendix that uses React Native under the hood. If this is not your situation then please check if there is a more relevant quickstart guide available.

This page provides all the steps for integrating Approov into your app. Additionally, a step-by-step tutorial guide using our Mendix App Example is also available.

Note that the minimum OS requirement for iOS is 13.4 and for Android the minimum SDK version is 21 (Android 5.0). You cannot use Approov in apps that need to support OS versions older than this.

To follow this guide you should have received an onboarding email for a trial or paid Approov account.

HOW APPROOV AND MENDIX FIT TOGETHER

The Mendix App will include the Approov SDK to secure any API requests made by the mobile app to the Mendix Runtime. The Approov SDK will attest the mobile app with the Approov Cloud service and will receive a JWT that is then added by the Approov SDK to the Approov-Token header of each API request. The Mendix App will have the Runtime URL pointing to a reverse proxy (Cloudflare worker on the diagram), and when the Approov worker receives an incoming request it will look for the presence of an Approov-Token in the headers of the request, and if it succeeds it will then verify its correctly signed and not expired and will forward the API request to the Mendix Runtime, otherwise an error response its returned. The Mendix Runtime on its turn will then make the API requests with the API keys it has stored on their cloud, not on the Mendix App, that is free of any hard-coded secrets and secured by Approov.

While Cloudflare its used here as an example of a Reverse Proxy you can use any other one of your choice, provided you have the ability to add some code to perform a JWT token check. See more details in the API-PROTECTION requirements section.

ADDING THE APPROOV SERVICE DEPENDENCY TO THE MENDIX MOBILE APP

The quickstart assumes that you already have built a native mobile app from your Mendix project by selecting App > Build Native Mobile App from your Mendix Studio Pro editor, and all instructions are based on the code generated by this build, thus all actions we instruct you to take must be done inside the folder where this build is located, for example C:\Users\User1\AndroidStudioProjects\YourMendixApp, not on the folder for your Mendix project or in your Mendix Studio Pro editor.

The Approov integration is available via the @approov/react-native-approov NPM package. This package is actually an open source wrapper layer that allows you to easily use Approov with Mendix. This has a further dependency to the closed source Android Approov SDK and iOS Approov SDK packages. Those are automatically added as dependencies for the platform specific targets.

Now, from the root of your Mendix native mobile app project install the latest version for the Approov dependency:

npm install --save @approov/react-native-approov

The package.json file at the root of your Mendix native mobile app project should have now the Approov dependency listed:

 "dependencies": {
    "@approov/react-native-approov": "3.2.0",
    "@mendix/native": "~1.0.0",
    ...
 },

ANDROID MANIFEST CHANGES

The following app permissions need to be available in the AndroidManifest.xml file to use Approov:

<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
<uses-permission android:name="android.permission.INTERNET" />

If not present on your app then you need to manually add it, for example at C:\Users\User1\AndroidStudioProjects\YourMendixApp\android\app\src\main\AndroidManifest.xml.

Please read this section of the reference documentation if targeting Android 11 (API level 30) or above.

IOS

The Approov React Native package generates a Cocoapods dependency file. From the directory containing the iOS project files you can install it by executing:

pod install

USING APPROOV IN THE MENDIX MOBILE APP

The ApproovService React Native package will handle any API request in the same way as usual in your mobile app, but with the additional features provided by the Approov SDK. The only additional requirement when using the ApproovService is providing an initialization string during object creation.

Open the main.js native theme file on your Mendix native mobile app folder, for example C:\Users\User1\AndroidStudioProjects\YourMendixApp\theme\native\main.js, and then add the following code:

import { NativeModules } from 'react-native'
const { ApproovService } = NativeModules

try {
    ApproovService.initialize("<enter-your-config-string-here>")
} catch (e) {
    // Approov doesn't attest mobile apps that are running against an API backend in localhost.
    // The try/catch block will allow you to continue developing as usual with your localhost 
    // instance of the Mendix Backend Runtime. 
    // You want or not to add some logging here. 
    // If you decide to show a pop-up to the user then don't use the exception message.
}

export {ApproovService}

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. This initializes Approov when the app is first created. Please note that you must provide the Config String every time you initialize an ApproovService but the underlying SDK only actually initializes the library once.

USING APPROOV TO SECURE APIS OUTSIDE THE MENDIX RUNTIME OR FOR THIRD-PARTY API CALLS

After initializing the ApproovService any API requests made by the Mendix Mobile App will be secured by it, even the ones you create explicitly within Javascript code, where you fetch and await responses as normal, for example:

const res = await fetch('https://my.api.example.com/v1/endpoint/path')

The ApproovService includes an interceptor that protects channel integrity (with either pinning or managed trust roots) and may also add Approov-Token or substitute app secret values, depending upon your integration choices.

When calling an API you have control of then you need to add an Approov token check to it, by following the most appropriated Approov Backend Quickstart for your project. For third-party APIs you cannot add this check therefore you need to use a Reverse Proxy, like you used for the Mendix Backend Runtime or you can use instead the Approov Runtime Secrets feature.

CHECKING IT WORKS

From Android Studio or Xcode launch the mobile app in a real device or emulator and use it as usual.

Initially you won't have set which API domains to protect, so the interceptor will not add anything. It will have called Approov though and made contact with the Approov cloud service. You will see logging from Approov saying UNKNOWN_URL.

Your Approov onboarding email should contain a link allowing you to access Live Metrics Graphs. After you've run your mobile app with Approov integration you should be able to see the results in the live metrics within a minute or so. At this stage you could even release your mobile app to get details of your app population and the attributes of the devices they are running upon.

NEXT STEPS

To actually protect your API(s) there are some further steps. Please follow the API PROTECTION guide to ensure that a valid Approov token is being passed by the Mendix Mobile app to your API(s), usually the Mendix Backend Runtime. Once you are not in control of the Mendix Backend Runtime you will need to place a Reverse Proxy (Nginx, Cloudflare, API Gateways, etc.) between the Mendix mobile app and the Mendix Backend Runtime.

An Approov Token is a short lived cryptographically signed JWT proving to the backend the authenticity of the API request.