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<!--RP1--> 27 28<!--RP1End--> 29 30- 标注1：用户认证界面的标题（WidgetParam.title），最大长度为500字符。应用可在此配置符合场景的字符串。 31 32- 标注2：导航按键上显示的文本（WidgetParam.navigationButtonText），最大长度为60字符。API 10-17仅在单指纹、单人脸场景下支持配置。从API 18开始，增加支持人脸+指纹场景。 33 34 当生物认证失败后，将出现该按钮，点击后从生物认证切换到应用自定义认证。 35 36<!--Del--> 37- 如图所示，认证控件的显示形式（WidgetParam.windowMode）为弹窗。 38 39 认证控件分为弹窗、全屏两种显示形式，如下图所示，左侧为默认的弹窗样式，右侧为全屏样式。 40 41 当前仅系统应用可以选择和使用全屏类型的认证界面。 42 43  44<!--DelEnd--> 45 46当前支持使用认证控件的认证类型包括： 47 48- 锁屏密码认证 49 50- 人脸认证 51 52- 指纹认证 53 54- 人脸+锁屏密码认证 55 56- 指纹+锁屏密码认证 57 58- 人脸+指纹+锁屏密码认证 59 60- 人脸+自定义导航按键 61 62- 指纹+自定义导航按键 63 64- 人脸+指纹+自定义导航按键<sup>18+</sup> 65 66## 开发步骤 67 681. [申请权限](prerequisites.md#申请权限)：ohos.permission.ACCESS_BIOMETRIC。 69 702. 指定用户认证相关参数[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)获取认证对象。 71 723. 调用[UserAuthInstance.on](../../reference/apis-user-authentication-kit/js-apis-useriam-userauth.md#on10)接口订阅认证结果。 73 744. 调用[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）。 75 76**示例1：** 77 78 发起用户认证，采用认证可信等级≥ATL3的人脸+锁屏密码认证，获取认证结果： 79 80```ts 81// API version 10 82import { BusinessError } from '@kit.BasicServicesKit'; 83import { cryptoFramework } from '@kit.CryptoArchitectureKit'; 84import { userAuth } from '@kit.UserAuthenticationKit'; 85 86try { 87 const rand = cryptoFramework.createRandom(); 88 const len: number = 16; // Generate a 16-byte random number. 89 const randData: Uint8Array = rand?.generateRandomSync(len)?.data; 90 // 设置认证参数。 91 const authParam: userAuth.AuthParam = { 92 challenge: randData, 93 authType: [userAuth.UserAuthType.PIN, userAuth.UserAuthType.FACE], 94 authTrustLevel: userAuth.AuthTrustLevel.ATL3, 95 }; 96 // 配置认证界面。 97 const widgetParam: userAuth.WidgetParam = { 98 title: '请进行身份认证', 99 }; 100 // 获取认证对象。 101 const userAuthInstance = userAuth.getUserAuthInstance(authParam, widgetParam); 102 console.info('get userAuth instance success'); 103 // 订阅认证结果。 104 userAuthInstance.on('result', { 105 onResult(result) { 106 console.info(`userAuthInstance callback result: ${JSON.stringify(result)}`); 107 // 可在认证结束或其他业务需要场景，取消订阅认证结果。 108 userAuthInstance.off('result'); 109 } 110 }); 111 console.info('auth on success'); 112 userAuthInstance.start(); 113 console.info('auth start success'); 114} catch (error) { 115 const err: BusinessError = error as BusinessError; 116 console.error(`auth catch error. Code is ${err?.code}, message is ${err?.message}`); 117} 118``` 119**示例2：** 120 121发起用户认证，采用认证可信等级≥ATL3的人脸 + 认证类型相关 + 复用设备解锁最大有效时长认证，获取认证结果： 122 123```ts 124// API version 10 125import { BusinessError } from '@kit.BasicServicesKit'; 126import { cryptoFramework } from '@kit.CryptoArchitectureKit'; 127import { userAuth } from '@kit.UserAuthenticationKit'; 128 129// 设置认证参数。 130let reuseUnlockResult: userAuth.ReuseUnlockResult = { 131 reuseMode: userAuth.ReuseMode.AUTH_TYPE_RELEVANT, 132 reuseDuration: userAuth.MAX_ALLOWABLE_REUSE_DURATION, 133} 134try { 135 const rand = cryptoFramework.createRandom(); 136 const len: number = 16; 137 const randData: Uint8Array = rand?.generateRandomSync(len)?.data; 138 const authParam: userAuth.AuthParam = { 139 challenge: randData, 140 authType: [userAuth.UserAuthType.FACE], 141 authTrustLevel: userAuth.AuthTrustLevel.ATL3, 142 reuseUnlockResult: reuseUnlockResult, 143 }; 144 // 配置认证界面。 145 const widgetParam: userAuth.WidgetParam = { 146 title: '请进行身份认证', 147 }; 148 // 获取认证对象。 149 const userAuthInstance = userAuth.getUserAuthInstance(authParam, widgetParam); 150 console.info('get userAuth instance success'); 151 // 订阅认证结果。 152 userAuthInstance.on('result', { 153 onResult(result) { 154 console.info(`userAuthInstance callback result: ${JSON.stringify(result)}`); 155 // 可在认证结束或其他业务需要场景，取消订阅认证结果。 156 userAuthInstance.off('result'); 157 } 158 }); 159 console.info('auth on success'); 160 userAuthInstance.start(); 161 console.info('auth start success'); 162} catch (error) { 163 const err: BusinessError = error as BusinessError; 164 console.error(`auth catch error. Code is ${err?.code}, message is ${err?.message}`); 165} 166``` 167**示例3：** 168 169发起用户认证，采用认证可信等级≥ATL3的人脸 + 任意应用认证类型相关 + 复用任意应用最大有效时长认证，获取认证结果： 170 171```ts 172// API version 14 173import { BusinessError } from '@kit.BasicServicesKit'; 174import { cryptoFramework } from '@kit.CryptoArchitectureKit'; 175import { userAuth } from '@kit.UserAuthenticationKit'; 176 177// 设置认证参数。 178let reuseUnlockResult: userAuth.ReuseUnlockResult = { 179 reuseMode: userAuth.ReuseMode.CALLER_IRRELEVANT_AUTH_TYPE_RELEVANT, 180 reuseDuration: userAuth.MAX_ALLOWABLE_REUSE_DURATION, 181} 182try { 183 const rand = cryptoFramework.createRandom(); 184 const len: number = 16; 185 const randData: Uint8Array = rand?.generateRandomSync(len)?.data; 186 const authParam: userAuth.AuthParam = { 187 challenge: randData, 188 authType: [userAuth.UserAuthType.FACE], 189 authTrustLevel: userAuth.AuthTrustLevel.ATL3, 190 reuseUnlockResult: reuseUnlockResult, 191 }; 192 // 配置认证界面。 193 const widgetParam: userAuth.WidgetParam = { 194 title: '请进行身份认证', 195 }; 196 // 获取认证对象。 197 const userAuthInstance = userAuth.getUserAuthInstance(authParam, widgetParam); 198 console.info('get userAuth instance success'); 199 // 订阅认证结果。 200 userAuthInstance.on('result', { 201 onResult(result) { 202 console.info(`userAuthInstance callback result: ${JSON.stringify(result)}`); 203 // 可在认证结束或其他业务需要场景，取消订阅认证结果。 204 userAuthInstance.off('result'); 205 } 206 }); 207 console.info('auth on success'); 208 userAuthInstance.start(); 209 console.info('auth start success'); 210} catch (error) { 211 const err: BusinessError = error as BusinessError; 212 console.error(`auth catch error. Code is ${err?.code}, message is ${err?.message}`); 213} 214``` 215 216**示例4：** 217 218以模应用方式进行用户身份认证： 219 220```ts 221// API version 16 222import { BusinessError } from '@kit.BasicServicesKit'; 223import { cryptoFramework } from '@kit.CryptoArchitectureKit'; 224import { userAuth } from '@kit.UserAuthenticationKit'; 225 226try { 227 const rand = cryptoFramework.createRandom(); 228 const len: number = 16; 229 const randData: Uint8Array = rand?.generateRandomSync(len)?.data; 230 const authParam: userAuth.AuthParam = { 231 challenge: randData, 232 authType: [userAuth.UserAuthType.PIN], 233 authTrustLevel: userAuth.AuthTrustLevel.ATL3, 234 }; 235 const widgetParam: userAuth.WidgetParam = { 236 title: '请输入密码', 237 uiContext: this.getUIContext().getHostContext(), 238 }; 239 const userAuthInstance = userAuth.getUserAuthInstance(authParam, widgetParam); 240 console.info('get userAuth instance success'); 241 // 需要调用UserAuthInstance的start()接口，启动认证后，才能通过onResult获取到认证结果。 242 userAuthInstance.on('result', { 243 onResult (result) { 244 console.info(`userAuthInstance callback result = ${JSON.stringify(result)}`); 245 } 246 }); 247 console.info('auth on success'); 248} catch (error) { 249 const err: BusinessError = error as BusinessError; 250 console.error(`auth catch error. Code is ${err?.code}, message is ${err?.message}`); 251} 252```
