用户认证开发指导

说明: 该开发指导需配合API version 10版本的SDK使用。

场景介绍

当前用户认证支持Pin码认证、人脸识别和指纹识别,可应用于设备解锁、应用登录、支付等身份认证场景。

接口说明

userIAM_userAuth模块提供了用户认证的相关方法,包括查询认证能力、发起认证和取消认证等,用户可以使用人脸、指纹等生物特征信息进行认证操作。具体接口说明可以查阅API参考文档

在执行认证前,需要指定认证类型认证等级,查询设备是否支持该认证能力。

表1 用户认证开放能力列表

接口名称 功能描述
getAvailableStatus(authType : UserAuthType, authTrustLevel : AuthTrustLevel): void 根据指定的认证类型、认证等级,检测当前设备是否支持相应的认证能力。
getUserAuthInstance(authParam: AuthParam, widgetParam: WidgetParam): UserAuthInstance 获取UserAuthInstance对象,用于执行用户身份认证,并支持使用统一用户身份认证组件。
on(type: 'result', callback: IAuthCallback): void 订阅用户身份认证结果。
off(type: 'result', callback?: IAuthCallback): void 取消订阅用户身份认证结果。
start(): void 执行用户认证。
cancel(): void 取消本次认证操作。

表2 用户身份认证可信等级划分原则

确认用户身份的认证可信等级 认证能力指标 说明&举例 可支撑的典型业务场景
ATL4 FRR=10%时,FAR≤0.0003%,SAR≤3% 能高精度地识别用户个体,有很强的活体检测能力,如采用了安全键盘的PIN码认证和有特殊安全增强的指纹与3D人脸认证。 小额支付
ATL3 FRR=10%时,FAR≤0.002%,SAR≤7% 能精确识别用户个体,有较强的活体检测能力,如有特殊安全增强的2D人脸认证。 设备解锁
ATL2 FRR=10%时,FAR≤0.002%,7%<SAR≤20% 能精确识别用户个体,有一定的活体检测能力,如基于普通测距和佩戴检测的手表作为可信持有物的认证。 维持设备解锁状态、应用登录
ATL1 FRR=10%时,FAR≤1%,7%<SAR≤20% 能识别用户个体,有一定的活体检测能力,如声纹认证。 业务风控、一般个人数据查询、精准业务推荐、个性化服务

查询当前设备是否支持相应的认证能力

开发步骤

  1. 申请权限。调用getAvailableStatus接口,需要在module.json5文件的requestPermissions对象中配置ohos.permission.ACCESS_BIOMETRIC权限。更多配置信息请参考Stage模型应用程序包结构

  2. 指定认证类型认证等级,调用getAvailableStatus接口查询当前的设备是否支持相应的认证能力。

    import userIAM_userAuth from '@ohos.userIAM.userAuth';
    
    // 查询认证能力是否支持,如果该设备未录入相关特征,就会打印不支持日志信息
    try {
        userIAM_userAuth.getAvailableStatus(userIAM_userAuth.UserAuthType.FACE, userIAM_userAuth.AuthTrustLevel.ATL1);
        console.info('current auth trust level is supported');
    } catch (error) {
        console.error('current auth trust level is not supported, error = ' + error);
    }
    

执行认证操作并订阅认证结果

开发步骤

  1. 申请权限。调用start接口,需要在module.json5文件的requestPermissions对象中配置ohos.permission.ACCESS_BIOMETRIC权限。更多配置信息请参考Stage模型应用程序包结构

  2. 指定challenge、认证类型认证等级,获取认证对象。

  3. 调用on接口订阅认证结果。

  4. 调用start接口发起认证,通过onResult回调返回认证结果。

    import userIAM_userAuth from '@ohos.userIAM.userAuth';
    
    const authParam : userIAM_userAuth.AuthParam = {
      challenge: new Uint8Array([49, 49, 49, 49, 49, 49]),
      authType: [userIAM_userAuth.UserAuthType.PIN],
      authTrustLevel: userIAM_userAuth.AuthTrustLevel.ATL1,
    };
    const widgetParam : userIAM_userAuth.WidgetParam = {
      title: '请输入密码',
    };
    try {
      //获取认证对象
      let userAuthInstance = userIAM_userAuth.getUserAuthInstance(authParam, widgetParam);
      console.log('get userAuth instance success');
      //订阅认证结果
      userAuthInstance.on('result', {
        onResult (result) {
          console.log('userAuthInstance callback result = ' + JSON.stringify(result));
        }
      });
      console.log('auth on success');
      userAuthInstance.start();
      console.log('auth start success');
    } catch (error) {
      console.error('auth catch error: ' + JSON.stringify(error));
    }
    
  5. 如果业务需要取消订阅认证结果,可以使用已经成功订阅事件的UserAuthInstance对象调用off接口进行取消订阅。

    import userIAM_userAuth from '@ohos.userIAM.userAuth';
    
    const authParam : userIAM_userAuth.AuthParam = {
      challenge: new Uint8Array([49, 49, 49, 49, 49, 49]),
      authType: [userIAM_userAuth.UserAuthType.PIN],
      authTrustLevel: userIAM_userAuth.AuthTrustLevel.ATL1,
    };
    const widgetParam : userIAM_userAuth.WidgetParam = {
      title: '请输入密码',
    };
    try {
      //获取认证对象
      let userAuthInstance = userIAM_userAuth.getUserAuthInstance(authParam, widgetParam);
      console.log('get userAuth instance success');
      //取消订阅认证结果
      userAuthInstance.off('result', {
        onResult (result) {
          console.log('auth off result: ' + JSON.stringify(result));
        }
      });
      console.log('auth off success');
    } catch (error) {
      console.error('auth catch error: ' + JSON.stringify(error));
    }
    

认证过程中取消认证

开发步骤

  1. 申请权限。调用cancel接口,需要在module.json5文件的requestPermissions对象中配置ohos.permission.ACCESS_BIOMETRIC权限。更多配置信息请参考Stage模型应用程序包结构

  2. 指定challenge、认证类型认证等级,获取认证对象。

  3. 调用start接口发起认证。

  4. 通过使用已经成功发起认证的调用UserAuthInstance对象调用cancel接口取消本次认证。

    import userIAM_userAuth from '@ohos.userIAM.userAuth';
    
    const authParam : userIAM_userAuth.AuthParam = {
      challenge: new Uint8Array([49, 49, 49, 49, 49, 49]),
      authType: [userIAM_userAuth.UserAuthType.PIN],
      authTrustLevel: userIAM_userAuth.AuthTrustLevel.ATL1,
    };
    const widgetParam : userIAM_userAuth.WidgetParam = {
      title: '请输入密码',
    };
    try {
      //获取认证对象
      let userAuthInstance = userIAM_userAuth.getUserAuthInstance(authParam, widgetParam);
      console.log('get userAuth instance success');
      //开始认证
      userAuthInstance.start();
      console.log('auth start success');
      // 取消认证
      userAuthInstance.cancel();
      console.log('auth cancel success');
    } catch (error) {
      console.error('auth catch error: ' + JSON.stringify(error));
    }