“指纹登录“ -- 项目中用到的两个cordova插件基本使用

1. 概要：

最近项目中需要实现指纹登录，用到了两个cordova插件

　　　　cordova-plugin-android-fingerprint-auth

　　　　cordova-plugin-touch-id

简单记录一下它们的基本使用过程；

2. 实现流程：

初始化 -- 获取手机指纹识别支持情况（传感器支持，API支持，用户设置支持等）
用户凭证登录（通常是用户名+密码）成功，调取系统指纹验证，验证通过，本地存储用户凭证；
登录画面调用系统指纹验证，验证通过，使用本地存储的用户凭证执行登录。

对手机指纹验证的个人理解是：指纹认证通过的用户，对手机而言是可信用户；而对我们的系统而言，拥有合法有效凭证的人才是可信用户。第2步中，在用户使用凭证登录成功后，调取指纹验证，意在让用户“授权”我们的程序，能够在指纹验证通过的情况下使用其凭证，在用户授权程序后，程序才可以把用户凭证记录下来，以用于之后的登录过程。这两个可信用户联系起来，就相当于手机的可信用户就是我们系统的可信用户，在用户通过指纹验证后，就可以成功登录系统。

3. 插件使用

1） cordova-plugin-android-fingerprint-auth

文档地址：https://www.npmjs.com/package/cordova-plugin-android-fingerprint-auth

这个插件将打开一个本地对话框，提示用户使用指纹进行身份验证。如果设备有安全锁屏(模式、PIN或密码)，用户可以缩退选择使用其他方法，进行身份验证。

注意：此插件仅适用于制造商已实现Android 6.0指纹认证API的设备。这个插件不支持Samsung Pass SDK，也不是所有的三星设备都实现Android 6.0指纹认证API。

// 插件安装
cordova plugin add cordova-plugin-android-fingerprint-auth

插件安装后，会自动在 window 上绑定 FingerprintAuth 属性，使用它访问插件

// 使用插件
Call isAvailable() to check the fingerprint status.
 
Call encrypt() or decrypt() show the Authentication Dialog.
 
Call delete() when you want to delete the cipher for the user.

另外，值得一提的是，该插件在指纹验证过程中提供了凭证加密解密的功能；

即在保存凭证的指纹验证过程中将用户凭证作为参数传给它，success 回调时会得到 password 加密后的 token；

在执行指纹验证登录的过程中将该token传给它，在 success 回调时会得到解密后的 password；

相当于插件给本地存储的凭证加了个签名。

// 检查指纹验证可用性
FingerprintAuth.isAvailable(isAvailableSuccessCallback, isAvailableErrorCallback);

// 检查指纹验证可用性的成功回调
function isAvailableSuccessCallback(result) {
    // result = {
    // isAvailable:boolean, // Fingerprint Authentication Dialog is available for use.
    // isHardwareDetected:boolean, // Device has hardware fingerprint sensor.
    // hasEnrolledFingerprints:boolean // Device has any fingerprints enrolled.
    // }
}

// 指纹验证；如果需要加解密凭证，需要传入clientId,usename,password
// 验证成功的回调中可以获得加密过的token
FingerprintAuth.encrypt(encryptConfig, encryptSuccessCallback, encryptErrorCallback);
// encryptConfig 参数是一个参数对象
var encryptConfig = {

    clientId         : undefined, // 在使用凭证加解密时是必须的，用于访问使用android key store，并且是加密的盐；
    usename          : undefined, // 在使用凭证加解密时是必须的，加密的盐；
    password         : undefined,// 加密时需要，解密时不需要
    token            : undefined, // 加密时不需要，解密时是必须的，
    disableBackup    : false, // 是否允许用户使用缩退方案，即当指纹验证有问题时是否提供用户密码等方式验证的按钮；
    maxAttempts      : '5', // 最大重试次数，默认为5次，可以比5小
    locale           : "en_US", // 对话框的语言，默认是英文en_US
    userAuthRequired : "false",
    encryptNoAuth    : "false",
    dialogTitle      : 'title', // 对话框标题
    dialogMessage    : 'message', // 对话框的提示文字
    dialogHint       : 'hintIconMsg' // 对话框的指纹图标显示的文字
};

// 验证成功的回调
function encryptSuccessCallback(result) {
    // result = {
    // withFingerprint:boolean, // 使用指纹验证的.
    // withBackup:boolean, // 使用缩退方案验证的.
    // token:boolean // 验证成功获得的token.
    // }
}

// 指纹验证，解密时，token参数是必须的
// 如果不需要解密凭证，请使用encrypt(不传入相应option值)
// 验证成功的回调中可以获得解密得到的凭证信息
FingerprintAuth.decrypt(decryptConfig, encryptSuccessCallback, encryptErrorCallback);
function encryptSuccessCallback(result) {

    // result = {
    // withFingerprint:boolean, // 使用指纹验证的.
    // withBackup:boolean, // 使用缩退方案验证的.
    // password:boolean // 验证成功，解密得到password
    // }
}

FingerprintAuth.delete(config, successCallback, errorCallback);
FingerprintAuth.dismiss(successCallback, errorCallback);
FingerprintAuth.ERRORS = {
    Key : value
}

2）cordova-plugin-touch-id

文档地址：https://github.com/EddyVerbruggen/cordova-plugin-touch-id

// 安装后，在使用 window.plugins.touchid 访问插件
cordova plugin add cordova-plugin-touch-id

注意：

ios插件提供了指纹验证的功能，不提供上边android插件里加解密凭证的能力；

插件支持iphoneX（有人脸，没指纹）；

isAvailable函数的successCallback中可以获得检测到验证类型：iphoneX得到是‘face’, 其他是‘touch’，可以在初始化时执行该函数，检证使用的什么验证，进而给用户显示合适的文字等；

// 初始化
window.plugins.touchid.isAvailable(
    function (type) {
        alert(type); // 成功回调: 'face'（iPhone X）, 'touch'（others） 
    },
    function (msg) {
        alert('not available, message: ' + msg); // 错误回调
    }
);

// 指纹（人脸）验证，指纹验证识别可以提供缩退策略的按钮，使用passcode(解锁密码)验证
window.plugins.touchid.verifyFingerprint(
    'Scan your fingerprint please', 
    function (msg) {
        alert('ok: ' + msg); //成功回调
    }, 
    function (msg) {
        alert('not ok: ' + JSON.stringify(msg));  
    }
);

// 指纹验证失败是，对话框中提供用户使用“password”进行登录的按钮，用户点击后会在errorCallback中收到error code 为-2，我们可以利用该信息弹出我们自己的密码输入框；

window.plugins.touchid.verifyFingerprintWithCustomPasswordFallback(
    'Scan your fingerprint please', // 提示指纹验证 
    function (msg) {
        alert('ok: ' + msg);
    },
    function (msg) {
        alert('not ok: ' + JSON.stringify(msg));
    }
);

// 功能类似上边的方法，多了一个case: “password”的按钮文字我们可以定制
window.plugins.touchid.verifyFingerprintWithCustomPasswordFallbackAndEnterPasswordLabel(
    'Scan your fingerprint please', // 提示指纹验证 
    'Enter PIN', // 自定义输入密码的按钮文字 
    function (msg) {
        alert('ok: ' + msg);
    },
    function (msg) {
        alert('not ok: ' + JSON.stringify(msg));
    }
);

------------------------ 补充：20200426

最近用到了插件 cordova-plugin-fingerprint-aio（https://www.npmjs.com/package/cordova-plugin-fingerprint-aio）

这个插件参考了上边两个插件，把android和ios统一了，尽可能的抹平了之前两个插件处理逻辑上的差异点，并且在github上相对活跃的多，建议使用这个；

注意：这个插件目前最新3.0.1版本，对应cordova-android版本要求8.0.0以上