How to use fingerprint authentication in cordova (phonegap,ionic) for Android and iOS

How to use fingerprint authentication in cordova (phonegap,ionic) for Android and iOS

Typing a password into your smartphone is, like, so 2013-2014.

With support for fingerprint sensors becoming a native part of Android in Marshmallow, Touch ID in Apple, and fingerprint sensors rapidly becoming standard fare in flagship phones as a result t's easy to get spoiled by the ease of unlocking something with a touch of your finger.

We cannot forget to use this feature if is available on the device in our cordova application and your app offers a way to use it. Just imagine, instant login, instant payment etc.

To use the fingerprint authentication on our device using cordova, we are going to use 2 plugins (respectively for every know platform : Android and iOS).

Requirements

  • A device (iPhone >= 5s for Apple and An Android Device with fingerprint) with fingerprint reader support.

Note that in every platform there's a way to detect if the fingerprint is supported or not to keep providing support to older devices.

It's worth to say, that if you want to implement this feature at the initialization of your cordova app (i.e to access the application, you need to grant the access with the fingerprint) you need to execute the code during or after the ondeviceready event of the document:

document.addEventListener("deviceready", function(){
    // Here the code to verificate the fingerprint
}, false);

Now that you know the basics, let's get started!

Android

For the Android platform, you need to use the cordova-plugin-android-fingerprint-auth.

This plugin was created referencing the Fingerprint Dialog sample and the Confirm Credential sample referenced by the Android 6.0 APIs webpage.

This plugin will open a native dialog fragment prompting the user to authenticate using their fingerprint. If the device has a secure lockscreen (pattern, PIN, or password), the user may opt to authenticate using that method as a backup.

To install this plugin on your project execute the following command in the command prompt :

cordova plugin add cordova-plugin-android-fingerprint-auth
# Or clone the repository
cordova plugin add https://github.com/mjwheatley/cordova-plugin-android-fingerprint-auth.git

After a succesfully installation, a Global variable will be accesible in the document named FingerprintAuth. This object has 2 available methods : isAvailable and show.

The show method expects an object with its configuration, the available properties are listed in the following table :

Param Type Default Description
clientId String undefined (REQUIRED) Used as the alias for your key in the Android Key Store.
clientSecret String undefined (REQUIRED) Used to encrypt the token returned upon successful fingerprint authentication.
disableBackup boolean false Set to true to remove the "USE BACKUP" button (disallow the authentication using the device PIN instead the fingerprint)
locale String "en_US" Change the language. Available languages (English: "en_US", Spanish: "es").

The following snippet shows a basic implementation and handles the fingerprint authentication with all its possible cases:

var client_id = "Your client ID";
var client_secret = "A very secret client secret (once per device)";

FingerprintAuth.isAvailable(function(result) {
    if (result.isAvailable) {
        if(result.hasEnrolledFingerprints){
            FingerprintAuth.show({
                clientId: client_id,
                clientSecret: client_secret
            }, function (result) {
                if (result.withFingerprint) {
                    alert("Successfully authenticated using a fingerprint");
                } else if (result.withPassword) {
                    alert("Authenticated with backup password");
                }
            }, function(error) {
                console.log(error); // "Fingerprint authentication not available"
            });
        }else{
            alert("Fingerprint auth available, but no fingerprint registered on the device");
        }
    }
}, function(message) {
    alert("Cannot detect fingerprint device : "+ message);
});

Note : clientId and clientSecret values are set by the developer to be specific for their application. The clientId is the alias for your application's use of the keystore via this plugin. The clientSecret is used to create an encrypted token that is returned upon successful fingerprint validation. You may use a different clientSecret per user.

The Dialog will be shown after the execution of the show method. Simple and quick authentication without use any password.

Fingerprint Auth Dialog Fingerprint Auth Dialog Success Fingerprint Auth Dialog Fail

iOS

For the iOS platform, you need to use the cordova-plugin-touch-id.

This plugin allow you to scan the fingerprint of your user with the TouchID sensor (iPhone 5S).

  • Compatible with Cordova Plugman.
  • Minimum iOS version is 8 (error callbacks will be gracefully invoked on lower versions).
  • Requires a fingerprint scanner, so an iPhone 5S or newer is required.

To install this plugin on your project execute the following command on your command prompt:

cordova plugin add cordova-plugin-touch-id
#Or clone from the repo
cordova plugin add https://github.com/EddyVerbruggen/cordova-plugin-touch-id

After a succesfully installation, an object will be registered in window.plugins named touchid.

First you'll want to check whether or not the user has a configured fingerprint scanner (to provide fallback for users without an iPhone 5s or lower), use the success callback to use the other methods.

window.plugins.touchid.isAvailable(
    function() {
        alert('available!')
    }, // success handler: TouchID available
    function(msg) {
        alert('not available, message: ' + msg)
    } // error handler: no TouchID available
);

If the onSuccess handler was called, you can scan the fingerprint. There are two options: verifyFingerprint andverifyFingerprintWithCustomPasswordFallback. The first method will offer a fallback option called 'enter passcode' which shows the default passcode UI when pressed. The second method will offer a fallback option called 'enter password' (not passcode) which allows you to provide your own password dialog.

window.plugins.touchid.verifyFingerprint(
    'Scan your fingerprint please', // this will be shown in the native scanner popup
    function(msg) {
        alert('ok: ' + msg);
    }, // success handler: fingerprint accepted
    function(msg) {
        alert('Something is wrong: ' + JSON.stringify(msg));
    } // error handler with errorcode and localised reason
);

Scan fingerprint

The errorhandler of the method above can receive an error code of -2 which means the user pressed the 'enter password' fallback.

window.plugins.touchid.verifyFingerprintWithCustomPasswordFallback(
  'Scan your fingerprint please', // this will be shown in the native scanner popup
   function(msg) {
       alert('ok: ' + msg)
   }, // success handler: fingerprint accepted
   function(msg) {
       alert('not ok: ' + JSON.stringify(msg))
   } // error handler with errorcode and localised reason
);

This will render a button labelled 'Enter password' in case the fingerprint is not recognized. If you want to provide your own label ('Enter PIN' perhaps), you can use the named function verifyFingerprintWithCustomPasswordFallbackAndEnterPasswordLabel (added in version 3.1.0):

window.plugins.touchid.verifyFingerprintWithCustomPasswordFallbackAndEnterPasswordLabel(
    'Scan your fingerprint please', // this will be shown in the native scanner popup
    'Enter PIN', // this will become the 'Enter password' button label
    function(msg) {
       alert('ok: ' + msg)
    }, // success handler: fingerprint accepted
    function(msg) {
       alert('not ok: ' + JSON.stringify(msg))
    } // error handler with errorcode and localised reason
);

Increasing the security on iOS

Since iOS9 it's possible to check whether or not the list of enrolled fingerprints changed since the last time you checked it. It's recommended you add this check so you can counter hacker attacks to your app. See this article for more details.

So instead of checking the fingerprint after isAvailable add another check. In case didFingerprintDatabaseChange returnstrue you probably want to re-authenticate your user before accepting valid fingerprints again.

window.plugins.touchid.isAvailable(
    // success handler; available
    function() {
      window.plugins.touchid.didFingerprintDatabaseChange(
          function(changed) {
            if (changed) {
              // re-auth the user by asking for his credentials before allowing a fingerprint scan again
            } else {
              // call the fingerprint scanner
            }
          }
      );
    },
    // error handler; not available
    function(msg) {
      // use a more traditional auth mechanism
    }
);

Multiplatform wrapper

As the code of the plugins vary, you need to check wheter the OS of the device is iOS or Android to prevent errors. If you are working in both platforms, you can use the following wrapper function to check when to use which code:

function verifyFingerprint(callbacks){
    var triggerCallbackIfExists = function(callback_name){
        if(typeof(callbacks[callback_name]) == "function"){
            // Execute function
            callbacks[callback_name]();
        }
    };

    // if IOS
    if(!!navigator.platform && /iPad|iPhone|iPod/.test(navigator.platform)){
        triggerCallbackIfExists("ios");
    // If Android
    }else if(navigator.userAgent.toLowerCase().indexOf("android") > -1){
        triggerCallbackIfExists("android");
    // If other OS
    }else{
        triggerCallbackIfExists("others");
    }
}

And use it like:

verifyFingerprint({
    ios: function(){
        // Here the code to verify the fingerprint only on IOS
    },
    android: function(){
        // Here the code to verify the fingerprint only in Android
    },
    others: function(){
        // alert("There's no plugin to verify fingerprint in this platform");
    }
});

Note that is up to you to check if the device supports the fingerprint feature with the plugin itself.

Have fun

Become a more social person