ns-approov-sdk-test v6.0.0

Approov Quickstart: NativeScript (TS, Angular, Vue)

Plugin version 6.0.0 works with NativeScript 6.1+.

For NativeScript 7 compatibiliy, install ns-approov-sdk version 7+.

This quickstart is written specifically for native Android and iOS apps that are written using NativeScript. If this is not your situation then check if there is a more relevant Quickstart guide available.

WHAT YOU WILL NEED

• This branch is tested with NodeJS version 14. So please make sure you are using Node v14 before proceeding.
• Access to either the demo account (request access here) or a trial/paid Approov account
• The approov command line tool installed with APPROOV_MANAGEMENT_TOKEN set with your account access token
• The contents of the folder containing this README

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 NativeScript
• Some pointers to other Approov features

RUNNING THE SHAPES APP WITHOUT APPROOV

The Shapes App is a simple NativeScript application written in Javascript using the Angular, VueJS and TypeScript-NativeScript.

The application consists mostly of boilerplate code, apart from the definitions of the shapes server’s URLs and setting up of the onPress callback for each of the buttons along the bottom of the screen.

The Hello and Shape buttons set up API requests to the shapes server, using the application’s built-in HTTP Module. For example, the Hello button initiates a GET request to the shapes.approov.io/v1/hello endpoint.

On a successful hello request to /v1/hello, the client app will say hello with a smile, while a failure or unsuccessful response will return a frown with some explanation of the error. The purpose of this simple endpoint is really just to test connectivity and to verify that you have built, installed and run the demo app correctly.

A successful shapes request to /v1/shapes returns one of four possible shapes:

To build the NativeScript Shapes app, first ensure that you have the npm package manager installed for your system ( see the instructions for your specific OS here). Also make sure your system is set up for NativeScript development by following their Setup instructions.

Open a shell terminal at ns-approov-sdk/src and type:

npm i // or npm install

Then, set up the demo to run, First navigate to the directory (demo-angular / demo-vue / demo)

npm i

This will install all the necessary packages and add the hooks to automatically add the approov-sdk in application.

Then, to run on an Android Emulator (which must already be launched), open another terminal window and type:

cd ns-approov-sdk/src
npm run demo-angular.android

Or to run on an iOS Simulator, type:

WIP

It is also possible to run the app on a real device by passing the --device flag to the command above. Example

npm run demo-angular.android -- --device
                    or
npm run demo-angular.android -- --emulator // (To run on emulator)

Now grab a shape and enjoy the endless family fun!

ADDING APPROOV SUPPORT

Add the Latest Approov SDK

Before proceeding further make sure you have Approov cli installed and APPROOV_MANAGEMENT_TOKEN set up, otherwise the application will fail to build.

Require the Approov NativeScript Package

Navigate to any of the three demo applications and run:

tns plugin add ../src

This will automatically install the plugin and add the necessary hooks to the application.

Add Approov Native Module

Approov protection is provided through the ns-approov-sdk module for both Android and iOS mobile platforms. // NPM LINK TO BE ADDED HERE

Enable Approov Support in the App

Based on the demo you are running you will need to update the files:

ns-approov-sdk/demo/app/main-page.ts for demo ns-aproov-sdk/demo-angular/src/app/app.module.ts from demo-angular ns-aproov-sdk/demo-vue/src/main.ts from demo-vue

/* Uncomment for Approov */

In order to enable Approov support in the Shapes app, this block of code must be uncommented. Specifically, the code imports a version of HTTP module with Approov support which can be used for making API calls in the app.

Approov also permits specifying the name of an existing HTTP header whose value will be bound to an Approov token for additional protection. In this example, we bind the user’s Authorization Bearer token to the Approov token so that the issued Approov token is only valid for a particular user. This effectively combines both app and user authentication for rock solid API protection!

/* Uncomment for Approov */
import { NSApproov } from 'ns-approov-sdk';

NSApproov.setApproovHeader('shapes.approov.io', { token: 'Approov-Token', binding: 'Authorization' });

// demo-angular/src/app/app.module.ts (Angular)
// demo-vue/src/main.ts               (VueJS)
// demo/app/main-page.ts              (Plain TypeScript)

Select the Correct Shapes Endpoint

The Shapes server provides the app with shapes using multiple versions of an API: version 1 (https://shapes.approov.io/v1/shapes) which is not protected by Approov, and version 2 (https://shapes.approov.io/v2/shapes) which is protected by Approov.

Now that we’re using Approov, let’s switch to use version 2 of the Shapes API.

  // demo-angular/src/app/app.component.ts
  readonly VERSION = 'v1'; // Change To v2 when using Approov
  
  // demo-vue/src/components/App.vue
  const VERSION = 'v1'; // use v2 for Approov
  
  // demo/app/main-page.ts
  const VERSION = 'v1';

VERSION = 'v1';

and change it to

VERSION = 'v2';

Ensure the Shapes API is added

In order for Approov tokens to be generated for https://shapes.approov.io/v2/shapes it is necessary to inform Approov about it. If you are using a demo account this is unnecessary as it is already setup. For a trial account do:

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.

Setup an Initial Approov Configuration

An Approov-enabled app requires a configuration file to initialize it. The Approov configuration is updated dynamically after subsequent launches of the app. When we run the NativeScript application that uses NativeScript Approov Plugin the initial configuration is already added to the platform assets before install.

NOTE: Make sure Approov CLI is set up properly.

Warning: Never log tokens in a released app as this could permit hackers to harvest data from your API while the token has not expired! Always use loggable Approov tokens for debugging.

REGISTER YOUR APP WITH APPROOV

If you are running the application using NativeScript CLI tns run <ios | android>. The plugin will automatically register the APK / IPA before installing it on device.

But if you are building a release / debug build using tns build <ios | android>. You have to register it manually using:

    // Android
    approov registration -add demo<vue | angular>/platforms/android/app/build/outputs/apk/<debug | release>/app-<debug | release>.apk
    
    // IOS
    approov registration -add demo<vue | angular>/platforms/ios/build/Debug-iphonesimulator/demo<angular | vue>.ipa
    
    The application / IPA is only registered in the first build. Subsequent build will not be registered automatically. 

Although the application is now receiving and forwarding tokens with your API calls, the tokens are not yet properly signed, because the attestation service does not recognize your application. Once you register the app with the Approov service, untempered apps will attest successfully and begin to fetch and transmit valid tokens.

If you plan to submit your application to the app store, you must remove the Intel CPU simulator support architectures from the Approov binary before submitting your app. To do so, at the directory demo-<vue | angular>/node_modules/ns-approov-sdk/platforms/ios/Approov.framework using the command line:

lipo Approov -remove i386 -output Approov
lipo Approov -remove x86_64 -output Approov

Since executing the above commands will disable support for the iOS Simulator, you can just remove the directory and the plugin will automatically add it during next application build.

rm -rf demo-<angular | vue>/node_modules/ns-approov-sdk/platforms/ios/Approov.framework

RUNNING THE SHAPES APP WITH APPROOV

Wait for the registration to propagate to the Approov service. This could take up to 30 seconds. Then restart your application to flush out any bad tokens, tap Get Shape and you should see:

or any of the four possible shapes returned by the server. Congratulations, your API is now Approoved!

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 exactly the one you registered with Approov.
• If you running the app from a debugger then valid tokens are not issued.
• 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. The code which performs this is:

const result = await Approov.fetchApproovToken(url);
console.log("Fetched Approov token: " + result.loggableToken);

and the logged token is specified in the variable result.loggableToken.

The Approov token format ( discussed here) includes an anno claim which can tell you why a particular Approov token is invalid and your app is not correctly authenticated with the Approov Cloud Service. The various forms of annotations are described here.

If you have a trial (as opposed to demo) account you have some additional options:

• Consider using an Annotation Policy during development to directly see why the device is not being issued with a valid token.
• Use approov metrics to see Live Metrics of the cause of failure.
• You can use a debugger and get valid Approov tokens on a specific device by whitelisting.

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 issue and revoke your own Management Tokens to control access to 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.
• Investigate other advanced features, such as Offline Security Mode , DeviceCheck Integration and Android Automated Launch Detection .