USING APPROOV IN YOUR CORDOVA APP THE EASY WAY

Friday 15 June 2018 By Johannes Schneiders

Topics: Cordova, Integration

 

A couple of months ago we released a little thing called Cordova Approov HTTP that makes it super-easy to add Approov mobile API protection to a Cordova mobile app using Cordova Advanced HTTP.

Cordova is a platform for building native mobile applications using HTML, CSS and JavaScript. It is an open source project managed by the Apache Software Foundation.

Approov protects mobile APIs by enabling dynamic software attestation for mobile apps. It allows mobile apps to uniquely authenticate themselves as the genuine, untampered software you originally published. Upon successfully passing the integrity check the app is issued a short-lifetime token which can then be presented to your API with each request. This allows your server side implementation to differentiate between requests from known apps, which will contain a valid token, and requests from other sources, which will not. This gives you complete control over what you allow to communicate with your mobile API server. Watch the Approov Product Video for a quick, three minute overview on how to improve your mobile security.

Cordova Advanced HTTP is a popular Cordova plugin for communicating with HTTP(S) servers and works for both Android and iOS.

CORDOVA APPROOV HTTP

Cordova Approov HTTP is a Cordova plugin that supports easy integration of Approov mobile API protection with a Cordova mobile app. This ease of integration is achieved by adding a general, non-Approov-specific callback/interceptor mechanism to the implementation of Cordova Advanced HTTP which is then used to call all Approov-specific functionality from Cordova Advanced HTTP. The source code for both, Cordova Approov HTTP and the modified Cordova Advanced HTTP is available on GitHub.

The interface of Cordova Approov HTTP consists of just a single configuration function. Typically this function will be called once at the start of the app, but can optionally be called repeatedly, which allows to add further hosts/domains to be protected or to update the token payload value.

approovConfigure(config, successCallback, errorCallback) configures the Cordova Approov HTTP plugin and calls the appropriate response function:

  • config: Map that can have the entries (among others, for full documentation see the Cordova Approov HTTP readme):

    • "customerName": String defining the customer name.

    • "tokenPayloadValue": String specifying the user-defined token payload value as an ASCII encoded string.

    • "protectedDomains": Array of maps specifying the domains to be protected by Approov. Each array-item has the entries:

      • "protectedDomainURL": String specifying the URL for the domain to protect.

      • "isMITMProtectedDomain": Boolean ("true" or "false") specifying whether the Approov token should be protected from theft through MITM attack on the connection from the app to the mobile API server.

  • successCallback: success function callback. This function will be invoked if the call to approovConfigure() completes successfully.

  • failureCallback: Error function callback. Called with an error parameter if the configuration does not complete successfully.

USING CORDOVA APPROOV HTTP IN A CORDOVA APP

To use Approov mobile API protection with the Cordova platform, we can integrate Approov into a mobile app like this:

  1. In the code of the mobile app that handles the device ready event, add a call to configure Approov:

    if ("deviceready" == id) {
        // Configure Approov. For details, please see the plugin documentation.
        var config = {
            "customerName": "me",
            "protectedDomains": [
                {
                    "protectedDomainURL": "https://my.domain.com/endpoint",
                    "isMITMProtectedDomain": "true"
                },
                // You can add more hosts/domains to protect here
            ]
        };
        cordova.plugin.approov.http.approovConfigure(
            config,
            function() {
                // Success
                console.log("Successfully configured Approov HTTP Plugin");
            },
            function(error) {
                // Failure
                console.log("Error configuring Approov HTTP Plugin: " + error);
            });
    }
    

    This configures Cordova Approov HTTP to Approov-protect any request to "my.domain.com" and to prevent theft of valid Approov tokens through a man-in-the-middle (MITM) attack. All requests to other domains will not be affected. The readme for Cordova Approov HTTP contains further details about configuring Cordova Approov HTTP.

  2. Then call the HTTP request functions of Cordova Advanced HTTP as normal. Approov protection will be in place for requests to any domain for which this has been configured - enabling the API server to reject requests that do not originate from a bona-fide app.

    Example: Call to Cordova Advanced HTTP's get request function (note: no change to the invocation of this function):

    cordova.plugin.http.get("https://my.domain.com/endpoint", {}, {}, 
        function(response) {
            // Success
            if (response.status == 200) {
                console.log("Successfully performed GET request");
            }
        },
        function(response) {
            if (response.status != 200) {
                // Failure
                console.log("Error on GET request: " + response.status);
            }
        });
    

And this is it - integration done.

BUILDING AND RUNNING AN APP WITH CORDOVA APPROOV HTTP

When building the mobile app it is important to ensure that the modified Cordova Advanced HTTP with the interceptor hooks is picked up by Cordova, not the original Cordova Advanced HTTP plugin. You also need to include the Cordova Approov HTTP plugin from GitHub or from NPM in your Cordova project. Then build the mobile app as normal.

You can now run the mobile app, but it will not authenticate until you have registered it with the Approov Cloud Service. You will need

  • an Approov subscription - it's free for a month, you can sign up here
  • and the Approov registration tools which you can download once you have your trial subscription.

When the mobile app is registered, after a short propagation delay of no more than 30 seconds, the mobile app will be recognized as valid by our service and will be issued tokens that your mobile API server can check for validity in order to accept only good requests. Note: Attaching a debugger or using a rooted device will be detected by the Approov SDK and you will not get a valid token.

You can find detailed instructions about building and registering a mobile app using Cordova Approov HTTP in the readme for the Cordova Approov HTTP Demo.

WHERE TO GO FROM HERE

  • The Cordova Approov HTTP Demo shows how to use the Cordova Approov HTTP plugin to add Approov Mobile API Protection to requests made through Cordova Advanced HTTP. If you would like to try this, please refer to the instructions in the demo's readme. This demonstrates a complete working system consisting of a mobile app that uses Cordova Advanced HTTP and Cordova Approov HTTP, the Approov Cloud Service and an example mobile API server without any need to sign up for a trial subscription.

  • If you are curious to see how we implemented the Approov the platform SDK for easy Approov integration with Cordova and how you too can create easy integrations, please head over to How We Integrated Approov with Cordova. The integration techniques used there can also be applied to other, non-Approov related integrations.

  • The Approov server-side integration documentation guides you through the server-side code required to receive and validate tokens.

  • Please also see the full Approov documentation.

  • If you have any questions or problems, please just get in touch via Zendesk.

 

Test Drive Approov!