用户认证开发指导

说明： 该开发指导需配合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%	能识别用户个体，有一定的活体检测能力，如声纹认证。	业务风控、一般个人数据查询、精准业务推荐、个性化服务

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

开发步骤

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

指定认证类型和认证等级，调用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);
}

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

开发步骤

申请权限。调用start接口，需要在module.json5文件的requestPermissions对象中配置ohos.permission.ACCESS_BIOMETRIC权限。更多配置信息请参考Stage模型应用程序包结构。
指定challenge、认证类型和认证等级，获取认证对象。
调用on接口订阅认证结果。

调用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));
}

如果业务需要取消订阅认证结果，可以使用已经成功订阅事件的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));
}

认证过程中取消认证

开发步骤

申请权限。调用cancel接口，需要在module.json5文件的requestPermissions对象中配置ohos.permission.ACCESS_BIOMETRIC权限。更多配置信息请参考Stage模型应用程序包结构。
指定challenge、认证类型和认证等级，获取认证对象。
调用start接口发起认证。

通过使用已经成功发起认证的调用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));
}