在当今的数字化时代，信息安全和用户隐私保护变得越来越重要。用户身份认证是确保信息安全的第一道防线。通过验证用户身份，可以防止未经授权的访问和数据泄露。它有助于保护用户的个人信息、账户资金和其他敏感数据。此外，用户身份认证还可以提高系统的安全性，减少恶意行为和欺诈事件的发生。
HarmonyOS SDK用户认证服务（User Authentication Kit）提供了基于用户在设备本地注册的锁屏口令、人脸和指纹来认证用户身份的能力，并提供了多设备统一的、集多种认证方式（人脸、指纹、口令）于一体的系统级用户身份认证控件。用户身份认证可用于各种鉴权场景，如应用内账号登录、支付认证等。
开发准备
申请权限
在开发具备用户身份认证的应用前，需要先申请权限 ohos.permission.ACCESS_BIOMETRIC，应用才能使用生物特征识别能力（如人脸、指纹）进行身份认证。该权限授权方式为 system_grant（系统授权），开发者只需要在 module.json5 配置文件的 requestPermissions 标签中声明权限，即可获取系统授权。具体声明指导请参考申请应用权限-声明权限。
开发步骤
查询支持的认证能力
指定认证类型（UserAuthType）和认证等级（AuthTrustLevel），调用 getAvailableStatus 接口查询当前的设备是否支持相应的认证能力。
认证等级 ATL 的选择参见下表：
以查询设备是否支持认证可信等级≥ATL1 的人脸认证功能为例：
import { BusinessError } from '@kit.BasicServicesKit';import { userAuth } from '@kit.UserAuthenticationKit';
// 查询认证能力是否支持try { userAuth.getAvailableStatus(userAuth.UserAuthType.FACE, userAuth.AuthTrustLevel.ATL1); console.info('current auth trust level is supported');} catch (error) { const err: BusinessError = error as BusinessError; console.error(`current auth trust level is not supported. Code is ${err?.code}, message is ${err?.message}`);}
复制代码
发起认证
1.指定用户认证相关参数 AuthParam（包括挑战值、认证类型 UserAuthType 列表和认证等级 AuthTrustLevel）、配置认证控件界面 WidgetParam，调用 getUserAuthInstance 获取认证对象。
2.调用 UserAuthInstance.on 接口订阅认证结果。
3.调用 UserAuthInstance.start 接口发起认证，通过 IAuthCallback 回调返回认证结果 UserAuthResult。
当认证成功时返回认证通过类型（UserAuthType）和令牌信息（AuthToken）。
示例 1：
发起用户认证，采用认证可信等级≥ATL3 的人脸+锁屏密码认证，获取认证结果：
// API version 10import { BusinessError } from '@kit.BasicServicesKit';import { cryptoFramework } from '@kit.CryptoArchitectureKit';import { userAuth } from '@kit.UserAuthenticationKit';
try { const rand = cryptoFramework.createRandom(); const len: number = 16; const randData: Uint8Array = rand?.generateRandomSync(len)?.data; // 设置认证参数 const authParam: userAuth.AuthParam = { challenge: randData, authType: [userAuth.UserAuthType.PIN, userAuth.UserAuthType.FACE], authTrustLevel: userAuth.AuthTrustLevel.ATL3, }; // 配置认证界面 const widgetParam: userAuth.WidgetParam = { title: '请进行身份认证', }; // 获取认证对象 const userAuthInstance = userAuth.getUserAuthInstance(authParam, widgetParam); console.info('get userAuth instance success'); // 订阅认证结果 userAuthInstance.on('result', { onResult(result) { console.info(`userAuthInstance callback result: ${JSON.stringify(result)}`); // 可在认证结束或其他业务需要场景，取消订阅认证结果 userAuthInstance.off('result'); } }); console.info('auth on success'); userAuthInstance.start(); console.info('auth start success');} catch (error) { const err: BusinessError = error as BusinessError; console.error(`auth catch error. Code is ${err?.code}, message is ${err?.message}`);}
复制代码
示例 2：
发起用户认证，采用认证可信等级≥ATL3 的人脸 + 认证类型相关 + 复用设备解锁最大有效时长认证，获取认证结果：
// API version 10import { BusinessError } from '@kit.BasicServicesKit';import { cryptoFramework } from '@kit.CryptoArchitectureKit';import { userAuth } from '@kit.UserAuthenticationKit';
// 设置认证参数let reuseUnlockResult: userAuth.ReuseUnlockResult = { reuseMode: userAuth.ReuseMode.AUTH_TYPE_RELEVANT, reuseDuration: userAuth.MAX_ALLOWABLE_REUSE_DURATION,}try { const rand = cryptoFramework.createRandom(); const len: number = 16; const randData: Uint8Array = rand?.generateRandomSync(len)?.data; const authParam: userAuth.AuthParam = { challenge: randData, authType: [userAuth.UserAuthType.FACE], authTrustLevel: userAuth.AuthTrustLevel.ATL3, reuseUnlockResult: reuseUnlockResult, }; // 配置认证界面 const widgetParam: userAuth.WidgetParam = { title: '请进行身份认证', }; // 获取认证对象 const userAuthInstance = userAuth.getUserAuthInstance(authParam, widgetParam); console.info('get userAuth instance success'); // 订阅认证结果 userAuthInstance.on('result', { onResult(result) { console.info(`userAuthInstance callback result: ${JSON.stringify(result)}`); // 可在认证结束或其他业务需要场景，取消订阅认证结果 userAuthInstance.off('result'); } }); console.info('auth on success'); userAuthInstance.start(); console.info('auth start success');} catch (error) { const err: BusinessError = error as BusinessError; console.error(`auth catch error. Code is ${err?.code}, message is ${err?.message}`);}
复制代码
认证过程中取消认证
1.指定用户认证相关参数 AuthParam（包括挑战值、认证类型 UserAuthType 列表和认证等级 AuthTrustLevel），获取认证对象 UserAuthInstance，并调用 UserAuthInstance.start 发起认证。
2.通过使用已经成功发起认证的 UserAuthInstance 对象调用 UserAuthInstance.cancel 接口取消本次认证。
示例代码为发起认证可信等级≥ATL3 的人脸+锁屏密码认证后，取消认证请求：
import { BusinessError } from '@kit.BasicServicesKit';import { cryptoFramework } from '@kit.CryptoArchitectureKit';import { userAuth } from '@kit.UserAuthenticationKit';
try { const rand = cryptoFramework.createRandom(); const len: number = 16; const randData: Uint8Array = rand?.generateRandomSync(len)?.data; // 设置认证参数 const authParam: userAuth.AuthParam = { challenge: randData, authType: [userAuth.UserAuthType.PIN, userAuth.UserAuthType.FACE], authTrustLevel: userAuth.AuthTrustLevel.ATL3, }; // 配置认证界面 const widgetParam: userAuth.WidgetParam = { title: '请进行身份认证', }; // 获取认证对象 const userAuthInstance = 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) { const err: BusinessError = error as BusinessError; console.error(`auth catch error. Code is ${err?.code}, message is ${err?.message}`);}
复制代码
切换自定义认证
针对需要切换自定义认证方式的场景，发起认证请求的方式请参考发起认证，但在传入的 widgetParam 需包含字段 navigationButtonText。
当前示例仅展示如何配置界面、选择切换到自定义认证界面，具体拉起的页面及对应页面的实现，请开发者自行实现，代码插入位置可参考注释提示。
import { BusinessError } from '@kit.BasicServicesKit';import { cryptoFramework } from '@kit.CryptoArchitectureKit';import { userAuth } from '@kit.UserAuthenticationKit';
try { const rand = cryptoFramework.createRandom(); const len: number = 16; const randData: Uint8Array = rand?.generateRandomSync(len)?.data; const authParam: userAuth.AuthParam = { challenge: randData, authType: [userAuth.UserAuthType.FACE], authTrustLevel: userAuth.AuthTrustLevel.ATL3, }; // 配置认证界面需设置navigationButtonText const widgetParam: userAuth.WidgetParam = { title: '请验证身份', navigationButtonText: '使用密码', }; // 获取认证对象 const userAuthInstance = userAuth.getUserAuthInstance(authParam, widgetParam); console.log('get userAuth instance success'); // 订阅认证结果 userAuthInstance.on('result', { onResult(result) { // 若收到ResultCode值为12500000，代表操作成功 console.log('userAuthInstance callback result = ' + JSON.stringify(result)); // 若收到ResultCode值为12500011,说明用户点击了导航按钮想切换自定义认证方式 if (result.result == 12500011) { //请开发者自行完成拉起自定义认证界面的实现 } } }); console.log('auth on success'); userAuthInstance.start(); console.log('auth start success');} catch (error) { const err: BusinessError = error as BusinessError; console.error(`auth catch error. Code is ${err?.code}, message is ${err?.message}`);}
复制代码
查询用户注册凭据的状态
指定认证类型（UserAuthType），调用 getEnrolledState 接口查询用户注册凭据的状态。
以查询用户人脸注册凭据的状态为例：
import { BusinessError } from '@kit.BasicServicesKit';import { userAuth } from '@kit.UserAuthenticationKit';
try { let enrolledState = userAuth.getEnrolledState(userAuth.UserAuthType.FACE); console.info(`get current enrolled state success, enrolledState: ${JSON.stringify(enrolledState)}`);} catch (error) { const err: BusinessError = error as BusinessError; console.error(`get current enrolled state failed, Code is ${err?.code}, message is ${err?.message}`);}
复制代码
了解更多详情>>
访问用户认证服务联盟官网
获取用户认证服务开发指导文档
评论