1# 发起认证 2 3应用发起身份认证请求，获取身份认证结果，从而访问受保护的系统/服务/应用的功能和数据（包括用户个人数据）。 4 5## 接口说明 6 7具体参数、返回值、错误码等描述，请参考对应的[API文档](../../reference/apis-user-authentication-kit/js-apis-useriam-userauth.md#userauthgetuserauthinstance10)。 8 9| 接口名称 | 功能描述 | 10| -------- | -------- | 11| getUserAuthInstance(authParam: AuthParam, widgetParam: WidgetParam): UserAuthInstance | 获取UserAuthInstance对象，用于执行用户身份认证，并支持使用统一[用户身份认证控件](#用户身份认证控件介绍)。 | 12| on(type: 'result', callback: IAuthCallback): void | 订阅用户身份认证结果。 | 13| off(type: 'result', callback?: IAuthCallback): void | 取消订阅用户身份认证结果。 | 14| start(): void | 执行用户认证。 | 15 16## 用户身份认证控件介绍 17 18系统提供了统一的用户认证控件供应用调用，使用用户认证控件的优势： 19 20- 统一用户认证服务将通过该控件完成信息的识别和认证，再将认证结果返回给应用，整体过程安全可控，可以更好地保护用户的生物特征信息。 21 22- 统一固定的UI组件样式，便于用户识别。 23 24认证控件的样式如图所示，通过[WidgetParam](../../reference/apis-user-authentication-kit/js-apis-useriam-userauth.md#widgetparam10)配置对应参数。 25 26 27 28- 标注1：用户认证界面的标题（WidgetParam.title），最大长度为500字符。应用可在此配置符合场景的字符串。 29 30- 标注2：导航按键上显示的文本（WidgetParam.navigationButtonText），最大长度为60字符。仅在单指纹、单人脸场景下支持配置。 31 32 当生物认证失败后，将出现该按钮，点击后从生物认证切换到应用自定义认证。 33 34<!--Del--> 35- 如图所示，认证控件的显示形式（WidgetParam.windowMode）为弹窗。 36 37 认证控件分为弹窗、全屏两种显示形式，如下图所示，左侧为默认的弹窗样式，右侧为全屏样式。 38 39 当前仅系统应用可以选择和使用全屏类型的认证界面。 40 41  42<!--DelEnd--> 43 44当前支持使用认证控件的认证类型包括： 45 46- 锁屏密码认证 47 48- 人脸认证 49 50- 指纹认证 51 52- 人脸+锁屏密码认证 53 54- 指纹+锁屏密码认证 55 56- 人脸+指纹+锁屏密码认证 57 58> **说明：** 59> 当前仅在单指纹、单人脸场景下支持配置导航按键上显示的文本（WidgetParam.navigationButtonText）。 60 61 62## 开发步骤 63 641. [申请权限](prerequisites.md#申请权限)：ohos.permission.ACCESS_BIOMETRIC。 65 662. 指定用户认证相关参数[AuthParam](../../reference/apis-user-authentication-kit/js-apis-useriam-userauth.md#authparam10)（包括挑战值、认证类型[UserAuthType](../../reference/apis-user-authentication-kit/js-apis-useriam-userauth.md#userauthtype8)列表和认证等级[AuthTrustLevel](../../reference/apis-user-authentication-kit/js-apis-useriam-userauth.md#authtrustlevel8)）、配置认证控件界面[WidgetParam](../../reference/apis-user-authentication-kit/js-apis-useriam-userauth.md#widgetparam10)，调用[getUserAuthInstance](../../reference/apis-user-authentication-kit/js-apis-useriam-userauth.md#userauthgetuserauthinstance10)获取认证对象。 67 683. 调用[UserAuthInstance.on](../../reference/apis-user-authentication-kit/js-apis-useriam-userauth.md#on10)接口订阅认证结果。 69 704. 调用[UserAuthInstance.start](../../reference/apis-user-authentication-kit/js-apis-useriam-userauth.md#start10)接口发起认证，通过[IAuthCallback](../../reference/apis-user-authentication-kit/js-apis-useriam-userauth.md#iauthcallback10)回调返回认证结果[UserAuthResult](../../reference/apis-user-authentication-kit/js-apis-useriam-userauth.md#userauthresult10)。当认证成功时返回认证通过类型（[UserAuthType](../../reference/apis-user-authentication-kit/js-apis-useriam-userauth.md#userauthtype8)）和令牌信息（AuthToken）。 71 72**示例1：** 73 74 发起用户认证，采用认证可信等级≥ATL3的人脸+锁屏密码认证，获取认证结果： 75 76```ts 77// API version 10 78import { BusinessError } from '@kit.BasicServicesKit'; 79import { cryptoFramework } from '@kit.CryptoArchitectureKit'; 80import { userAuth } from '@kit.UserAuthenticationKit'; 81 82try { 83 const rand = cryptoFramework.createRandom(); 84 const len: number = 16; // Generate a 16-byte random number. 85 const randData: Uint8Array = rand?.generateRandomSync(len)?.data; 86 // 设置认证参数。 87 const authParam: userAuth.AuthParam = { 88 challenge: randData, 89 authType: [userAuth.UserAuthType.PIN, userAuth.UserAuthType.FACE], 90 authTrustLevel: userAuth.AuthTrustLevel.ATL3, 91 }; 92 // 配置认证界面。 93 const widgetParam: userAuth.WidgetParam = { 94 title: '请进行身份认证', 95 }; 96 // 获取认证对象。 97 const userAuthInstance = userAuth.getUserAuthInstance(authParam, widgetParam); 98 console.info('get userAuth instance success'); 99 // 订阅认证结果。 100 userAuthInstance.on('result', { 101 onResult(result) { 102 console.info(`userAuthInstance callback result: ${JSON.stringify(result)}`); 103 // 可在认证结束或其他业务需要场景，取消订阅认证结果。 104 userAuthInstance.off('result'); 105 } 106 }); 107 console.info('auth on success'); 108 userAuthInstance.start(); 109 console.info('auth start success'); 110} catch (error) { 111 const err: BusinessError = error as BusinessError; 112 console.error(`auth catch error. Code is ${err?.code}, message is ${err?.message}`); 113} 114``` 115**示例2：** 116 117发起用户认证，采用认证可信等级≥ATL3的人脸 + 认证类型相关 + 复用设备解锁最大有效时长认证，获取认证结果： 118 119```ts 120// API version 10 121import { BusinessError } from '@kit.BasicServicesKit'; 122import { cryptoFramework } from '@kit.CryptoArchitectureKit'; 123import { userAuth } from '@kit.UserAuthenticationKit'; 124 125// 设置认证参数。 126let reuseUnlockResult: userAuth.ReuseUnlockResult = { 127 reuseMode: userAuth.ReuseMode.AUTH_TYPE_RELEVANT, 128 reuseDuration: userAuth.MAX_ALLOWABLE_REUSE_DURATION, 129} 130try { 131 const rand = cryptoFramework.createRandom(); 132 const len: number = 16; 133 const randData: Uint8Array = rand?.generateRandomSync(len)?.data; 134 const authParam: userAuth.AuthParam = { 135 challenge: randData, 136 authType: [userAuth.UserAuthType.FACE], 137 authTrustLevel: userAuth.AuthTrustLevel.ATL3, 138 reuseUnlockResult: reuseUnlockResult, 139 }; 140 // 配置认证界面。 141 const widgetParam: userAuth.WidgetParam = { 142 title: '请进行身份认证', 143 }; 144 // 获取认证对象。 145 const userAuthInstance = userAuth.getUserAuthInstance(authParam, widgetParam); 146 console.info('get userAuth instance success'); 147 // 订阅认证结果。 148 userAuthInstance.on('result', { 149 onResult(result) { 150 console.info(`userAuthInstance callback result: ${JSON.stringify(result)}`); 151 // 可在认证结束或其他业务需要场景，取消订阅认证结果。 152 userAuthInstance.off('result'); 153 } 154 }); 155 console.info('auth on success'); 156 userAuthInstance.start(); 157 console.info('auth start success'); 158} catch (error) { 159 const err: BusinessError = error as BusinessError; 160 console.error(`auth catch error. Code is ${err?.code}, message is ${err?.message}`); 161} 162``` 163**示例3：** 164 165发起用户认证，采用认证可信等级≥ATL3的人脸 + 任意应用认证类型相关 + 复用任意应用最大有效时长认证，获取认证结果： 166 167```ts 168// API version 14 169import { BusinessError } from '@kit.BasicServicesKit'; 170import { cryptoFramework } from '@kit.CryptoArchitectureKit'; 171import { userAuth } from '@kit.UserAuthenticationKit'; 172 173// 设置认证参数。 174let reuseUnlockResult: userAuth.ReuseUnlockResult = { 175 reuseMode: userAuth.ReuseMode.CALLER_IRRELEVANT_AUTH_TYPE_RELEVANT, 176 reuseDuration: userAuth.MAX_ALLOWABLE_REUSE_DURATION, 177} 178try { 179 const rand = cryptoFramework.createRandom(); 180 const len: number = 16; 181 const randData: Uint8Array = rand?.generateRandomSync(len)?.data; 182 const authParam: userAuth.AuthParam = { 183 challenge: randData, 184 authType: [userAuth.UserAuthType.FACE], 185 authTrustLevel: userAuth.AuthTrustLevel.ATL3, 186 reuseUnlockResult: reuseUnlockResult, 187 }; 188 // 配置认证界面。 189 const widgetParam: userAuth.WidgetParam = { 190 title: '请进行身份认证', 191 }; 192 // 获取认证对象。 193 const userAuthInstance = userAuth.getUserAuthInstance(authParam, widgetParam); 194 console.info('get userAuth instance success'); 195 // 订阅认证结果。 196 userAuthInstance.on('result', { 197 onResult(result) { 198 console.info(`userAuthInstance callback result: ${JSON.stringify(result)}`); 199 // 可在认证结束或其他业务需要场景，取消订阅认证结果。 200 userAuthInstance.off('result'); 201 } 202 }); 203 console.info('auth on success'); 204 userAuthInstance.start(); 205 console.info('auth start success'); 206} catch (error) { 207 const err: BusinessError = error as BusinessError; 208 console.error(`auth catch error. Code is ${err?.code}, message is ${err?.message}`); 209} 210```
