一、开发者准备
应用在开发用户身份认证功能时，需要先了解以下流程，并根据实际需求参考对应指导开发。
- 查询设备支持的用户身份认证能力。
- 发起身份认证请求，获取身份认证结果。
- 校验和使用认证结果：请参考通用密钥库二次认证密钥访问控制。
- （可选）认证过程中取消认证。
- （可选）切换自定义认证。
1.1 申请权限
在开发具备用户身份认证的应用前，需要先申请权限ohos.permission.ACCESS_BIOMETRIC，应用才能使用生物特征识别能力（如人脸、指纹）进行身份认证。
该权限授权方式为system_grant（系统授权），开发者只需要在module.json5配置文件的requestPermissions标签中声明权限，即可获取系统授权。
二、查询支持的认证能力
不同的设备对于认证能力（人脸、指纹、口令）的支持性各有差异，开发者在发起认证前应当先查询当前设备支持的用户认证能力。
2.1 接口说明
具体参数、返回值、错误码等描述，请参考对应的userAuth.getAvailableStatus。
| 接口名称 | 功能描述 |
|---|---|
| getAvailableStatus(authType : UserAuthType, authTrustLevel : AuthTrustLevel): void | 根据指定的认证类型、认证等级，检测当前设备是否支持相应的认证能力。 |
2.2 开发步骤
- 申请权限：ohos.permission.ACCESS_BIOMETRIC。
- 指定认证类型（UserAuthType）和认证等级（AuthTrustLevel），调用getAvailableStatus接口查询当前的设备是否支持相应的认证能力。
认证可信等级的详细介绍请参见认证可信等级划分原则。
以查询设备是否支持认证可信等级≥ATL3的人脸认证功能为例：
obtainingSupported(){try{// 查询认证能力是否支持userAuth.getAvailableStatus(userAuth.UserAuthType.FACE,userAuth.AuthTrustLevel.ATL3);Logger.info('current auth trust level is supported.');returntrue;}catch(error){consterr:BusinessError=error as BusinessError;Logger.error(`current auth trust level is not supported,code is ${err?.code},message is ${err?.message}`);returnfalse;}}示例2：
发起用户认证，采用认证可信等级≥ATL3的人脸+认证类型相关+复用设备解锁最大有效时长认证，获取认证结果。
initiatingUserAuthentication2(){// 设置认证参数let reuseUnlockResult:userAuth.ReuseUnlockResult={reuseMode:userAuth.ReuseMode.AUTH_TYPE_RELEVANT,reuseDuration:userAuth.MAX_ALLOWABLE_REUSE_DURATION,};try{constrandData=getRandData();if(!randData){return;}constauthParam:userAuth.AuthParam={challenge:randData,authType:[userAuth.UserAuthType.PIN,userAuth.UserAuthType.FACE,userAuth.UserAuthType.FINGERPRINT],authTrustLevel:userAuth.AuthTrustLevel.ATL3,reuseUnlockResult:reuseUnlockResult,};// 配置认证界面constwidgetParam:userAuth.WidgetParam={title:resourceToString($r('app.string.title')),};// 获取认证对象constuserAuthInstance=userAuth.getUserAuthInstance(authParam,widgetParam);Logger.info('get userAuth instance successfully.');// 订阅认证结果userAuthInstance.on('result',{onResult:(result:userAuth.UserAuthResult)=>{try{Logger.info('userAuthInstance callback.');this.result[ResultIndex.EXAMPLE_2]=(`${result.result}`);// 可在认证结束或其他业务需要场景，取消订阅认证结果。userAuthInstance.off('result');}catch(error){consterr:BusinessError=error as BusinessError;Logger.error(`onResult failed,code:${err?.code},Message:${err?.message}`);}}});// 启动认证userAuthInstance.start();Logger.info('auth start successfully.');}catch(error){consterr:BusinessError=error as BusinessError;Logger.error(`auth failed,code is ${err?.code},message is ${err?.message}`);}}三、实战
效果图
设备录入面容进行人脸识别效果
设备没有录入面容进行人脸识别效果
示例代码
TestUserAuthInstance2.ets
import{userAuth}from'@kit.UserAuthenticationKit';import{promptAction}from'@kit.ArkUI';import{BusinessError}from'@kit.BasicServicesKit';import{cryptoFramework}from'@kit.CryptoArchitectureKit';import{JSON}from'@kit.ArkTS';functiongetRandData():Uint8Array|null{try{constrand=cryptoFramework.createRandom();constlen:number=16;let randData:Uint8Array|null=null;let retryCount=0;while(retryCount<3){randData=rand?.generateRandomSync(len)?.data;if(randData){break;}retryCount++;}returnrandData;}catch(error){consterr:BusinessError=error as BusinessError;console.error(`getRandData error,code is ${err?.code},message is ${err?.message}`);returnnull;}}@Entry @ComponentstructTestUserAuthInstance2{@State message:string='请面容解锁后查看下面的信息';@State lookData:boolean=false;@State result:string[]=newArray(8).fill('wait');/** * 以查询设备是否支持认证可信等级≥ATL3的人脸认证功能为例 * * @returns */obtainingSupported(){try{// 查询认证能力是否支持userAuth.getAvailableStatus(userAuth.UserAuthType.FACE,userAuth.AuthTrustLevel.ATL3);console.info('当前设备 支持 current auth trust level is supported.');returntrue;}catch(error){consterr:BusinessError=error as BusinessError;console.error(`当前设备 不支持 current auth trust level is not supported,code is ${err?.code},message is ${err?.message}`);returnfalse;}}/** * 发起用户认证，采用认证可信等级≥ATL3的人脸+指纹+锁屏口令认证，获取认证结果。 */initiatingUserAuthentication1(){try{constrandData=getRandData();if(!randData){return;}// 设置认证参数constauthParam:userAuth.AuthParam={challenge:randData,// authType: [userAuth.UserAuthType.PIN, userAuth.UserAuthType.FACE, userAuth.UserAuthType.FINGERPRINT],authType:[userAuth.UserAuthType.FACE],authTrustLevel:userAuth.AuthTrustLevel.ATL3,};// 配置认证界面constwidgetParam:userAuth.WidgetParam={title:"面容解锁",};// 获取认证对象constuserAuthInstance=userAuth.getUserAuthInstance(authParam,widgetParam);console.info('获取认证对象 get userAuth instance successfully.');// 订阅认证结果userAuthInstance.on('result',{onResult:(result:userAuth.UserAuthResult)=>{try{console.info('订阅认证结果 userAuthInstance callback.'+JSON.stringify(result));//认证结果。包含认证结果码、认证令牌（成功时）、认证类型和凭据状态等信息。应用应检查result.result字段判断认证是否成功：//// - 若result.result为SUCCESS(12500000)，表示认证通过，可使用result.token进行后续操作。//// - 若result.result为其他值，表示认证不通过，应根据具体错误码进行处理。if(result.result===12500000){this.lookData=true}else{this.lookData=true}// 可在认证结束或其他业务需要场景，取消订阅认证结果。userAuthInstance.off('result');}catch(error){consterr:BusinessError=error as BusinessError;console.error(`认证失败 onResult failed,code:${err?.code},Message:${err?.message}`);}}});// 启动认证userAuthInstance.start();console.info('启动认证 auth start successfully.');}catch(error){consterr:BusinessError=error as BusinessError;console.error(`启动认证 auth failed,code is ${err?.code},message is ${err?.message}`);}}build(){Column({space:30}){Text(this.message).margin({top:50}).fontSize($r('app.float.text_size_18fp')).onClick(()=>{let obtainingSupported=this.obtainingSupported();if(obtainingSupported){this.initiatingUserAuthentication1()}else{promptAction.openToast({message:"当前设备不支持面容解锁",duration:5000})}})Text("个人信息相关数据").fontSize(20).fontColor(Color.Black).visibility(this.lookData?Visibility.Visible:Visibility.None)}.height('100%').width('100%')}}entry里module.json5，申请权限
"requestPermissions":[{"name":"ohos.permission.ACCESS_BIOMETRIC","reason":"$string:reason"}]
