1# @ohos.userIAM.userAuth (用户认证) 2 3提供用户认证能力，可应用于设备解锁、支付、应用登录等身份认证场景。 4 5> **说明：** 6> 本模块首批接口从API version 6开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。 7 8 9## 导入模块 10 11```ts 12import userIAM_userAuth from '@ohos.userIAM.userAuth'; 13``` 14 15## WindowModeType<sup>10+</sup> 16 17用户认证界面的显示类型。 18 19**系统能力**：SystemCapability.UserIAM.UserAuth.Core 20 21**系统接口**: 此接口为系统接口。 22 23| 名称 | 值 | 说明 | 24| ---------- | ---- | ---------- | 25| DIALOG_BOX | 1 | 弹框类型。 | 26| FULLSCREEN | 2 | 全屏类型。 | 27 28## AuthParam<sup>10+</sup> 29 30用户认证相关参数。 31 32**系统能力**：SystemCapability.UserIAM.UserAuth.Core 33 34| 名称 | 类型 | 必填 | 说明 | 35| -------------- | ---------------------------------- | ---- | ------------------------------------------------------------ | 36| challenge | Uint8Array | 是 | 挑战值，用来防重放攻击。最大长度为32字节，可传Uint8Array([])。 | 37| authType | [UserAuthType](#userauthtype8)[] | 是 | 认证类型列表，用来指定用户认证界面提供的认证方法。 | 38| authTrustLevel | [AuthTrustLevel](#authtrustlevel8) | 是 | 认证信任等级。 | 39 40## WidgetParam<sup>10+</sup> 41 42用户认证界面配置相关参数。 43 44**系统能力**：SystemCapability.UserIAM.UserAuth.Core 45 46| 名称 | 类型 | 必填 | 说明 | 47| -------------------- | ----------------------------------- | ---- | ------------------------------------------------------------ | 48| title | string | 是 | 用户认证界面的标题，最大长度为500字符。 | 49| navigationButtonText | string | 否 | 导航按键的说明文本，最大长度为60字符。仅在单指纹、单人脸场景下支持。 | 50| windowMode | [WindowModeType](#windowmodetype10) | 否 | 代表用户认证界面的显示类型，默认值为WindowModeType.DIALOG_BOX。<br>**系统接口**: 此接口为系统接口。 | 51 52## UserAuthResult<sup>10+</sup> 53 54用户认证结果。当认证结果为成功时，返回认证类型和认证通过的令牌信息。 55 56**系统能力**：SystemCapability.UserIAM.UserAuth.Core 57 58| 名称 | 类型 | 必填 | 说明 | 59| -------- | ------------------------------ | ---- | ------------------------------------------------------------ | 60| result | number | 是 | 用户认证结果。若结果为成功返回0，若失败返回相应错误码，错误码详细介绍请参见[用户认证错误码](../errorcodes/errorcode-useriam.md)。 | 61| token | Uint8Array | 否 | 当认证结果为成功时，返回认证通过的令牌信息。 | 62| authType | [UserAuthType](#userauthtype8) | 否 | 当认证结果为成功时，返回认证类型。 | 63 64 65## IAuthCallback<sup>10+</sup> 66 67返回认证结果的回调对象。 68 69### onResult<sup>10+</sup> 70 71onResult(result: UserAuthResult): void 72 73回调函数，返回认证结果。 74 75**系统能力**：SystemCapability.UserIAM.UserAuth.Core 76 77**参数：** 78 79| 参数名 | 类型 | 必填 | 说明 | 80| ------ | ----------------------------------- | ---- | ---------- | 81| result | [UserAuthResult](#userauthresult10) | 是 | 认证结果。 | 82 83**示例：** 84 85```ts 86import userAuth from '@ohos.userIAM.userAuth'; 87 88const authParam : userAuth.AuthParam = { 89 challenge: new Uint8Array([49, 49, 49, 49, 49, 49]), 90 authType: [userAuth.UserAuthType.PIN], 91 authTrustLevel: userAuth.AuthTrustLevel.ATL1, 92}; 93const widgetParam :userAuth.WidgetParam = { 94 title: '请输入密码', 95}; 96try { 97 let userAuthInstance = userAuth.getUserAuthInstance(authParam, widgetParam); 98 console.log('get userAuth instance success'); 99 userAuthInstance.on('result', { 100 onResult (result) { 101 console.log('userAuthInstance callback result = ' + JSON.stringify(result)); 102 } 103 }); 104 console.log('auth on success'); 105} catch (error) { 106 console.log('auth catch error: ' + JSON.stringify(error)); 107} 108``` 109 110## UserAuthInstance<sup>10+</sup> 111 112用于执行用户身份认证，并支持使用统一用户身份认证组件。 113使用以下接口前，都需要先通过[getUserAuthInstance](#getuserauthinstance10)方法获取UserAuthInstance对象。 114 115### on<sup>10+</sup> 116 117on(type: 'result', callback: IAuthCallback): void 118 119订阅用户身份认证结果。 120 121**系统能力**：SystemCapability.UserIAM.UserAuth.Core 122 123**参数：** 124 125| 参数名 | 类型 | 必填 | 说明 | 126| -------- | --------------------------------- | ---- | ------------------------------------------ | 127| type | 'result' | 是 | 订阅事件类型，表明该事件用来返回认证结果。 | 128| callback | [IAuthCallback](#iauthcallback10) | 是 | 认证接口的回调函数，用于返回认证结果。 | 129 130**错误码：** 131 132以下错误码的详细介绍请参见[用户认证错误码](../errorcodes/errorcode-useriam.md)。 133 134| 错误码ID | 错误信息 | 135| -------- | ------------------------ | 136| 401 | Incorrect parameters. | 137| 12500002 | General operation error. | 138 139**示例：** 140 141```ts 142import userAuth from '@ohos.userIAM.userAuth'; 143 144const authParam : userAuth.AuthParam = { 145 challenge: new Uint8Array([49, 49, 49, 49, 49, 49]), 146 authType: [userAuth.UserAuthType.PIN], 147 authTrustLevel: userAuth.AuthTrustLevel.ATL1, 148}; 149const widgetParam :userAuth.WidgetParam = { 150 title: '请输入密码', 151}; 152try { 153 let userAuthInstance = userAuth.getUserAuthInstance(authParam, widgetParam); 154 console.log('get userAuth instance success'); 155 userAuthInstance.on('result', { 156 onResult (result) { 157 console.log('userAuthInstance callback result = ' + JSON.stringify(result)); 158 } 159 }); 160 console.log('auth on success'); 161} catch (error) { 162 console.log('auth catch error: ' + JSON.stringify(error)); 163} 164``` 165 166### off<sup>10+</sup> 167 168off(type: 'result', callback?: IAuthCallback): void 169 170取消订阅用户身份认证结果。 171 172> **说明**：需要使用已经成功订阅事件的[UserAuthInstance](#userauthinstance10)对象调用该接口进行取消订阅。 173 174**系统能力**：SystemCapability.UserIAM.UserAuth.Core 175 176**参数：** 177 178| 参数名 | 类型 | 必填 | 说明 | 179| -------- | --------------------------------- | ---- | ------------------------------------------ | 180| type | 'result' | 是 | 订阅事件类型，表明该事件用来返回认证结果。 | 181| callback | [IAuthCallback](#iauthcallback10) | 否 | 认证接口的回调函数，用于返回认证结果。 | 182 183**错误码：** 184 185以下错误码的详细介绍请参见[用户认证错误码](../errorcodes/errorcode-useriam.md)。 186 187| 错误码ID | 错误信息 | 188| -------- | ------------------------ | 189| 401 | Incorrect parameters. | 190| 12500002 | General operation error. | 191 192**示例：** 193 194```ts 195import userAuth from '@ohos.userIAM.userAuth'; 196 197const authParam : userAuth.AuthParam = { 198 challenge: new Uint8Array([49, 49, 49, 49, 49, 49]), 199 authType: [userAuth.UserAuthType.PIN], 200 authTrustLevel: userAuth.AuthTrustLevel.ATL1, 201}; 202const widgetParam :userAuth.WidgetParam = { 203 title: '请输入密码', 204}; 205try { 206 let userAuthInstance = userAuth.getUserAuthInstance(authParam, widgetParam); 207 console.log('get userAuth instance success'); 208 userAuthInstance.off('result', { 209 onResult (result) { 210 console.log('auth off result: ' + JSON.stringify(result)); 211 } 212 }); 213 console.log('auth off success'); 214} catch (error) { 215 console.log('auth catch error: ' + JSON.stringify(error)); 216} 217``` 218 219### start<sup>10+</sup> 220 221start(): void 222 223开始认证。 224 225**需要权限**：ohos.permission.ACCESS_BIOMETRIC 226 227**系统能力**：SystemCapability.UserIAM.UserAuth.Core 228 229**错误码：** 230 231以下错误码的详细介绍请参见[用户认证错误码](../errorcodes/errorcode-useriam.md)。 232 233| 错误码ID | 错误信息 | 234| -------- | ------------------------------------------------ | 235| 201 | Permission verification failed. | 236| 401 | Incorrect parameters. | 237| 12500001 | Authentication failed. | 238| 12500002 | General operation error. | 239| 12500003 | The operation is canceled. | 240| 12500004 | The operation is time-out. | 241| 12500005 | The authentication type is not supported. | 242| 12500006 | The authentication trust level is not supported. | 243| 12500007 | The authentication task is busy. | 244| 12500009 | The authenticator is locked. | 245| 12500010 | The type of credential has not been enrolled. | 246| 12500011 | The authentication is canceled from widget's navigation button. | 247 248**示例：** 249 250```ts 251import userAuth from '@ohos.userIAM.userAuth'; 252 253const authParam : userAuth.AuthParam = { 254 challenge: new Uint8Array([49, 49, 49, 49, 49, 49]), 255 authType: [userAuth.UserAuthType.PIN], 256 authTrustLevel: userAuth.AuthTrustLevel.ATL1, 257}; 258const widgetParam :userAuth.WidgetParam = { 259 title: '请输入密码', 260}; 261try { 262 let userAuthInstance = userAuth.getUserAuthInstance(authParam, widgetParam); 263 console.log('get userAuth instance success'); 264 userAuthInstance.start(); 265 console.log('auth start success'); 266} catch (error) { 267 console.log('auth catch error: ' + JSON.stringify(error)); 268} 269``` 270 271### cancel<sup>10+</sup> 272 273cancel(): void 274 275取消认证。 276 277> **说明**：此时UserAuthInstance需要是正在进行认证的对象。 278 279**需要权限**：ohos.permission.ACCESS_BIOMETRIC 280 281**系统能力**：SystemCapability.UserIAM.UserAuth.Core 282 283**错误码：** 284 285| 错误码ID | 错误信息 | 286| -------- | ------------------------------- | 287| 201 | Permission verification failed. | 288| 401 | Incorrect parameters. | 289| 12500002 | General operation error. | 290 291**示例：** 292 293```ts 294import userAuth from '@ohos.userIAM.userAuth'; 295 296const authParam : userAuth.AuthParam = { 297 challenge: new Uint8Array([49, 49, 49, 49, 49, 49]), 298 authType: [userAuth.UserAuthType.PIN], 299 authTrustLevel: userAuth.AuthTrustLevel.ATL1, 300}; 301const widgetParam :userAuth.WidgetParam = { 302 title: '请输入密码', 303}; 304try { 305 let userAuthInstance = userAuth.getUserAuthInstance(authParam, widgetParam); 306 console.log('get userAuth instance success'); 307 userAuthInstance.cancel(); 308 console.log('auth cancel success'); 309} catch (error) { 310 console.log('auth catch error: ' + JSON.stringify(error)); 311} 312``` 313 314## getUserAuthInstance<sup>10+</sup> 315 316getUserAuthInstance(authParam: AuthParam, widgetParam: WidgetParam): UserAuthInstance 317 318获取[UserAuthInstance](#userauthinstance10)对象，用于执行用户身份认证，并支持使用统一用户身份认证组件。 319 320> **说明：** 321> 每个UserAuthInstance只能进行一次认证，若需要再次进行认证则需重新获取UserAuthInstance。 322 323**系统能力**：SystemCapability.UserIAM.UserAuth.Core 324 325**参数：** 326 327| 参数名 | 类型 | 必填 | 说明 | 328| ----------- | ----------------------------- | ---- | -------------------------- | 329| authParam | [AuthParam](#authparam10) | 是 | 用户认证相关参数。 | 330| widgetParam | [WidgetParam](#widgetparam10) | 是 | 用户认证界面配置相关参数。 | 331 332**返回值：** 333 334| 类型 | 说明 | 335| --------------------------------------- | -------------------------- | 336| [UserAuthInstance](#userauthinstance10) | 支持用户界面的认证器对象。 | 337 338**错误码：** 339 340以下错误码的详细介绍请参见[用户认证错误码](../errorcodes/errorcode-useriam.md)。 341 342| 错误码ID | 错误信息 | 343| -------- | ------------------------------------------------ | 344| 401 | Incorrect parameters. | 345| 12500002 | General operation error. | 346| 12500005 | The authentication type is not supported. | 347| 12500006 | The authentication trust level is not supported. | 348 349**示例：** 350 351```ts 352import userAuth from '@ohos.userIAM.userAuth'; 353 354const authParam : userAuth.AuthParam = { 355 challenge: new Uint8Array([49, 49, 49, 49, 49, 49]), 356 authType: [userAuth.UserAuthType.PIN], 357 authTrustLevel: userAuth.AuthTrustLevel.ATL1, 358}; 359const widgetParam :userAuth.WidgetParam = { 360 title: '请输入密码', 361}; 362try { 363 let userAuthInstance = userAuth.getUserAuthInstance(authParam, widgetParam); 364 console.log('get userAuth instance success'); 365} catch (error) { 366 console.log('auth catch error: ' + JSON.stringify(error)); 367} 368``` 369 370## NoticeType<sup>10+</sup> 371 372用户身份认证的通知类型。 373 374**系统能力**：SystemCapability.UserIAM.UserAuth.Core 375 376**系统接口**: 此接口为系统接口。 377 378| 名称 | 值 | 说明 | 379| ------------- | ---- | -------------------- | 380| WIDGET_NOTICE | 1 | 表示来自组件的通知。 | 381 382## sendNotice<sup>10+</sup> 383 384sendNotice(noticeType: NoticeType, eventData: string): void 385 386在使用统一身份认证组件进行用户身份认证时，用于接收来自统一身份认证组件的通知。 387 388**需要权限**：ohos.permission.SUPPORT_USER_AUTH 389 390**系统能力**：SystemCapability.UserIAM.UserAuth.Core 391 392**系统接口**: 此接口为系统接口。 393 394**参数：** 395 396| 参数名 | 类型 | 必填 | 说明 | 397| ---------- | --------------------------- | ---- | ---------- | 398| noticeType | [NoticeType](#noticetype10) | 是 | 通知类型。 | 399| eventData | string | 是 | 事件数据。 | 400 401**错误码：** 402 403以下错误码的详细介绍请参见[用户认证错误码](../errorcodes/errorcode-useriam.md)。 404 405| 错误码ID | 错误信息 | 406| -------- | --------------------------------------- | 407| 201 | Permission verification failed. | 408| 202 | The caller is not a system application. | 409| 401 | Incorrect parameters. | 410| 12500002 | General operation error. | 411 412**示例：** 413 414```ts 415import userAuth from '@ohos.userIAM.userAuth'; 416 417interface EventData { 418 widgetContextId: number; 419 event: string; 420 version: string; 421 payload: PayLoad; 422} 423interface PayLoad { 424 type: Object[]; 425} 426try { 427 const eventData : EventData = { 428 widgetContextId: 123456, 429 event: 'EVENT_AUTH_TYPE_READY', 430 version: '1', 431 payload: { 432 type: ['pin'] 433 } as PayLoad, 434 }; 435 const jsonEventData = JSON.stringify(eventData); 436 let noticeType = userAuth.NoticeType.WIDGET_NOTICE; 437 userAuth.sendNotice(noticeType, jsonEventData); 438 console.log('sendNotice success'); 439} catch (error) { 440 console.log('sendNotice catch error: ' + JSON.stringify(error)); 441} 442``` 443 444## UserAuthWidgetMgr<sup>10+</sup> 445 446组件管理接口，可将用身份认证组件注册到UserAuthWidgetMgr中，由UserAuthWidgetMgr进行管理、调度。 447 448### on<sup>10+</sup> 449 450on(type: 'command', callback: IAuthWidgetCallback): void 451 452身份认证组件订阅来自用户认证框架的命令。 453 454**系统能力**：SystemCapability.UserIAM.UserAuth.Core 455 456**系统接口**: 此接口为系统接口。 457 458**参数：** 459 460| 参数名 | 类型 | 必填 | 说明 | 461| -------- | --------------------------------------------- | ---- | ------------------------------------------------------------ | 462| type | 'command' | 是 | 订阅事件类型，表明该事件用于用户认证框架向身份认证组件发送命令。 | 463| callback | [IAuthWidgetCallback](#iauthwidgetcallback10) | 是 | 组件管理接口的回调函数，用于用户认证框架向身份认证组件发送命令。 | 464 465**错误码：** 466 467以下错误码的详细介绍请参见[用户认证错误码](../errorcodes/errorcode-useriam.md)。 468 469| 错误码ID | 错误信息 | 470| -------- | ------------------------ | 471| 401 | Incorrect parameters. | 472| 12500002 | General operation error. | 473 474**示例：** 475 476```ts 477import userAuth from '@ohos.userIAM.userAuth'; 478 479const userAuthWidgetMgrVersion = 1; 480try { 481 let userAuthWidgetMgr = userAuth.getUserAuthWidgetMgr(userAuthWidgetMgrVersion); 482 console.log('get userAuthWidgetMgr instance success'); 483 userAuthWidgetMgr.on('command', { 484 sendCommand(cmdData) { 485 console.log('The cmdData is ' + cmdData); 486 } 487 }) 488 console.log('subscribe authentication event success'); 489} catch (error) { 490 console.log('userAuth widgetMgr catch error: ' + JSON.stringify(error)); 491} 492``` 493 494### off<sup>10+</sup> 495 496off(type: 'command', callback?: IAuthWidgetCallback): void 497 498身份认证组件取消订阅来自用户认证框架的命令。 499 500**系统能力**：SystemCapability.UserIAM.UserAuth.Core 501 502**系统接口**: 此接口为系统接口。 503 504**参数：** 505 506| 参数名 | 类型 | 必填 | 说明 | 507| -------- | --------------------------------------------- | ---- | ------------------------------------------------------------ | 508| type | 'command' | 是 | 订阅事件类型，表明该事件用于用户认证框架向身份认证组件发送命令。 | 509| callback | [IAuthWidgetCallback](#iauthwidgetcallback10) | 否 | 组件管理接口的回调函数，用于用户认证框架向身份认证组件发送命令。 | 510 511**错误码：** 512 513以下错误码的详细介绍请参见[用户认证错误码](../errorcodes/errorcode-useriam.md)。 514 515| 错误码ID | 错误信息 | 516| -------- | ------------------------ | 517| 401 | Incorrect parameters. | 518| 12500002 | General operation error. | 519 520**示例：** 521 522```ts 523import userAuth from '@ohos.userIAM.userAuth'; 524 525const userAuthWidgetMgrVersion = 1; 526try { 527 let userAuthWidgetMgr = userAuth.getUserAuthWidgetMgr(userAuthWidgetMgrVersion); 528 console.log('get userAuthWidgetMgr instance success'); 529 userAuthWidgetMgr.off('command', { 530 sendCommand(cmdData) { 531 console.log('The cmdData is ' + cmdData); 532 } 533 }) 534 console.log('cancel subscribe authentication event success'); 535} catch (error) { 536 console.log('userAuth widgetMgr catch error: ' + JSON.stringify(error)); 537} 538``` 539 540## getUserAuthWidgetMgr<sup>10+</sup> 541 542getUserAuthWidgetMgr(version: number): UserAuthWidgetMgr 543 544获取UserAuthWidgetMgr对象，用于执行用户身份认证。 545 546> **说明：** 547> 每个UserAuthInstance只能进行一次认证，若需要再次进行认证则需重新获取UserAuthInstance。 548 549**需要权限**：ohos.permission.SUPPORT_USER_AUTH 550 551**系统能力**：SystemCapability.UserIAM.UserAuth.Core 552 553**系统接口**: 此接口为系统接口。 554 555**参数：** 556 557| 参数名 | 类型 | 必填 | 说明 | 558| ------- | ------ | ---- | -------------------- | 559| version | number | 是 | 表示认证组件的版本。 | 560 561**返回值：** 562 563| 类型 | 说明 | 564| ----------------------------------------- | ------------ | 565| [UserAuthWidgetMgr](#userauthwidgetmgr10) | 认证器对象。 | 566 567**错误码：** 568 569以下错误码的详细介绍请参见[用户认证错误码](../errorcodes/errorcode-useriam.md)。 570 571| 错误码ID | 错误信息 | 572| -------- | --------------------------------------- | 573| 201 | Permission verification failed. | 574| 202 | The caller is not a system application. | 575| 401 | Incorrect parameters. | 576| 12500002 | General operation error. | 577 578**示例：** 579 580```ts 581import userAuth from '@ohos.userIAM.userAuth'; 582 583let userAuthWidgetMgrVersion = 1; 584try { 585 let userAuthWidgetMgr = userAuth.getUserAuthWidgetMgr(userAuthWidgetMgrVersion); 586 console.log('get userAuthWidgetMgr instance success'); 587} catch (error) { 588 console.log('userAuth widgetMgr catch error: ' + JSON.stringify(error)); 589} 590``` 591 592## IAuthWidgetCallback<sup>10+</sup> 593 594认证组件通过该回调获取用户认证框架发送的命令。 595 596### sendCommand<sup>10+</sup> 597 598sendCommand(cmdData: string): void 599 600回调函数，用于用户认证框架向组件发送命令。 601 602**系统能力**：SystemCapability.UserIAM.UserAuth.Core 603 604**系统接口**: 此接口为系统接口。 605 606**参数：** 607 608| 参数名 | 类型 | 必填 | 说明 | 609| ------- | ------ | ---- | ---------------------------------- | 610| cmdData | string | 是 | 用户身份认证框架向组件发送的命令。 | 611 612**示例：** 613 614```ts 615import userAuth from '@ohos.userIAM.userAuth'; 616 617const userAuthWidgetMgrVersion = 1; 618try { 619 let userAuthWidgetMgr = userAuth.getUserAuthWidgetMgr(userAuthWidgetMgrVersion); 620 console.log('get userAuthWidgetMgr instance success'); 621 userAuthWidgetMgr.on('command', { 622 sendCommand(cmdData) { 623 console.log('The cmdData is ' + cmdData); 624 } 625 }) 626 console.log('subscribe authentication event success'); 627} catch (error) { 628 console.log('userAuth widgetMgr catch error: ' + JSON.stringify(error)); 629} 630``` 631 632## AuthResultInfo<sup>9+</sup> 633 634表示认证结果信息。 635 636**系统能力**：以下各项对应的系统能力均为SystemCapability.UserIAM.UserAuth.Core 637 638| 名称 | 类型 | 必填 | 说明 | 639| ------------ | ---------- | ---- | -------------------- | 640| result | number | 是 | 认证结果。 | 641| token | Uint8Array | 否 | 用户身份认证通过的凭证。 | 642| remainAttempts | number | 否 | 剩余的认证尝试次数。 | 643| lockoutDuration | number | 否 | 认证操作的锁定时长，时间单位为毫秒ms。 | 644 645## TipInfo<sup>9+</sup> 646 647表示认证过程中的提示信息。 648 649**系统能力**：以下各项对应的系统能力均为SystemCapability.UserIAM.UserAuth.Core。 650 651| 名称 | 类型 | 必填 | 说明 | 652| ------------ | ---------- | ---- | -------------------- | 653| module | number | 是 | 发送提示信息的模块标识。 | 654| tip | number | 是 | 认证过程提示信息。 | 655 656## EventInfo<sup>9+</sup> 657 658表示认证过程中事件信息的类型。 659 660**系统能力**：以下各项对应的系统能力均为SystemCapability.UserIAM.UserAuth.Core。 661 662| 取值类型 | 说明 | 663| --------- | ----------------------- | 664| [AuthResultInfo](#authresultinfo9) | 获取到的认证结果信息。 | 665| [TipInfo](#tipinfo9) | 认证过程中的提示信息。 | 666 667## AuthEventKey<sup>9+</sup> 668 669表示认证事件类型的关键字，作为[on](#ondeprecated)接口的的参数。 670 671**系统能力**：以下各项对应的系统能力均为SystemCapability.UserIAM.UserAuth.Core。 672 673| 取值类型 | 说明 | 674| ---------- | ----------------------- | 675| "result" | [on](#ondeprecated)接口第一个参数为"result"时，[callback](#callback9)回调返回认证的结果信息。 | 676| "tip" | [on](#ondeprecated)接口第一个参数为"tip"时，[callback](#callback9)回调返回认证操作中的提示信息。 | 677 678## AuthEvent<sup>9+</sup> 679 680认证接口的异步回调对象。 681 682### callback<sup>9+</sup> 683 684callback(result : EventInfo) : void 685 686通过该回调获取认证结果信息或认证过程中的提示信息。 687 688**系统能力**：SystemCapability.UserIAM.UserAuth.Core 689 690**参数：** 691 692| 参数名 | 类型 | 必填 | 说明 | 693| --------- | -------------------------- | ---- | ------------------------------ | 694| result | [EventInfo](#eventinfo9) | 是 | 返回的认证结果信息或提示信息。 | 695 696**示例：** 697 698```ts 699import userIAM_userAuth from '@ohos.userIAM.userAuth'; 700 701let challenge = new Uint8Array([1, 2, 3, 4, 5, 6, 7, 8]); 702let authType = userIAM_userAuth.UserAuthType.FACE; 703let authTrustLevel = userIAM_userAuth.AuthTrustLevel.ATL1; 704// 通过callback获取认证结果 705try { 706 let auth = userIAM_userAuth.getAuthInstance(challenge, authType, authTrustLevel); 707 auth.on('result', { 708 callback: (result: userIAM_userAuth.AuthResultInfo) => { 709 console.log('authV9 result ' + result.result); 710 console.log('authV9 token ' + result.token); 711 console.log('authV9 remainAttempts ' + result.remainAttempts); 712 console.log('authV9 lockoutDuration ' + result.lockoutDuration); 713 } 714 } as userIAM_userAuth.AuthEvent); 715 auth.start(); 716 console.log('authV9 start success'); 717} catch (error) { 718 console.log('authV9 error = ' + error); 719 // do error 720} 721// 通过callback获取认证过程中的提示信息 722try { 723 let auth = userIAM_userAuth.getAuthInstance(challenge, authType, authTrustLevel); 724 auth.on('tip', { 725 callback : (result : userIAM_userAuth.TipInfo) => { 726 switch (result.tip) { 727 case userIAM_userAuth.FaceTips.FACE_AUTH_TIP_TOO_BRIGHT: 728 // do something; 729 case userIAM_userAuth.FaceTips.FACE_AUTH_TIP_TOO_DARK: 730 // do something; 731 default: 732 // do others 733 } 734 } 735 } as userIAM_userAuth.AuthEvent); 736 auth.start(); 737 console.log('authV9 start success'); 738} catch (error) { 739 console.log('authV9 error = ' + error); 740 // do error 741} 742``` 743 744## AuthInstance<sup>(deprecated)</sup> 745 746执行用户认证的对象。 747 748> **说明：** 749> 从 API version 9 开始支持，从 API version 10 开始废弃，请使用[UserAuthInstance](#userauthinstance10)替代。 750 751### on<sup>(deprecated)</sup> 752 753on : (name : AuthEventKey, callback : AuthEvent) => void 754 755订阅指定类型的用户认证事件。 756 757> **说明：** 758> 从 API version 9 开始支持，从 API version 10 开始废弃。 759 760> **说明：** 761> 使用获取到的[AuthInstance](#authinstancedeprecated)对象调用该接口进行订阅。 762 763**系统能力**：SystemCapability.UserIAM.UserAuth.Core 764 765**参数：** 766 767| 参数名 | 类型 | 必填 | 说明 | 768| --------- | -------------------------- | ---- | ------------------------- | 769| name | [AuthEventKey](#autheventkey9) | 是 | 表示认证事件类型，取值为"result"时，回调函数返回认证结果；取值为"tip"时，回调函数返回认证过程中的提示信息。 | 770| callback | [AuthEvent](#authevent9) | 是 | 认证接口的回调函数，用于返回认证结果或认证过程中的提示信息。 | 771 772**错误码：** 773 774以下错误码的详细介绍请参见[用户认证错误码](../errorcodes/errorcode-useriam.md)。 775 776| 错误码ID | 错误信息 | 777| -------- | ------- | 778| 401 | Incorrect parameters. | 779| 12500002 | General operation error. | 780 781**示例：** 782 783```ts 784import userIAM_userAuth from '@ohos.userIAM.userAuth'; 785 786let challenge = new Uint8Array([1, 2, 3, 4, 5, 6, 7, 8]); 787let authType = userIAM_userAuth.UserAuthType.FACE; 788let authTrustLevel = userIAM_userAuth.AuthTrustLevel.ATL1; 789try { 790 let auth = userIAM_userAuth.getAuthInstance(challenge, authType, authTrustLevel); 791 // 订阅认证结果 792 auth.on('result', { 793 callback: (result: userIAM_userAuth.AuthResultInfo) => { 794 console.log('authV9 result ' + result.result); 795 console.log('authV9 token ' + result.token); 796 console.log('authV9 remainAttempts ' + result.remainAttempts); 797 console.log('authV9 lockoutDuration ' + result.lockoutDuration); 798 } 799 }); 800 // 订阅认证过程中的提示信息 801 auth.on('tip', { 802 callback : (result : userIAM_userAuth.TipInfo) => { 803 switch (result.tip) { 804 case userIAM_userAuth.FaceTips.FACE_AUTH_TIP_TOO_BRIGHT: 805 // do something; 806 case userIAM_userAuth.FaceTips.FACE_AUTH_TIP_TOO_DARK: 807 // do something; 808 default: 809 // do others 810 } 811 } 812 } as userIAM_userAuth.AuthEvent); 813 auth.start(); 814 console.log('authV9 start success'); 815} catch (error) { 816 console.log('authV9 error = ' + error); 817 // do error 818} 819``` 820 821### off<sup>(deprecated)</sup> 822 823off : (name : AuthEventKey) => void 824 825取消订阅特定类型的认证事件。 826 827>**说明：** 828>从 API version 9 开始支持，从 API version 10 开始废弃。 829 830> **说明：** 831> 需要使用已经成功订阅事件的[AuthInstance](#authinstancedeprecated)对象调用该接口进行取消订阅。 832 833**系统能力**：SystemCapability.UserIAM.UserAuth.Core 834 835| 名称 | 类型 | 必填 | 说明 | 836| --------- | -------------------------- | ---- | ------------------------- | 837| name | [AuthEventKey](#autheventkey9) | 是 | 表示认证事件类型，取值为"result"时，取消订阅认证结果；取值为"tip"时，取消订阅认证过程中的提示信息。 | 838 839**错误码：** 840 841以下错误码的详细介绍请参见[用户认证错误码](../errorcodes/errorcode-useriam.md)。 842 843| 错误码ID | 错误信息 | 844| -------- | ------- | 845| 401 | Incorrect parameters. | 846| 12500002 | General operation error. | 847 848**示例：** 849 850```ts 851import userIAM_userAuth from '@ohos.userIAM.userAuth'; 852 853let challenge = new Uint8Array([1, 2, 3, 4, 5, 6, 7, 8]); 854let authType = userIAM_userAuth.UserAuthType.FACE; 855let authTrustLevel = userIAM_userAuth.AuthTrustLevel.ATL1; 856try { 857 let auth = userIAM_userAuth.getAuthInstance(challenge, authType, authTrustLevel); 858 // 订阅认证结果 859 auth.on('result', { 860 callback: (result: userIAM_userAuth.AuthResultInfo) => { 861 console.log('authV9 result ' + result.result); 862 console.log('authV9 token ' + result.token); 863 console.log('authV9 remainAttempts ' + result.remainAttempts); 864 console.log('authV9 lockoutDuration ' + result.lockoutDuration); 865 } 866 }); 867 // 取消订阅结果 868 auth.off('result'); 869 console.info('cancel subscribe authentication event success'); 870} catch (error) { 871 console.info('cancel subscribe authentication event failed, error =' + error); 872 // do error 873} 874``` 875 876### start<sup>(deprecated)</sup> 877 878start : () => void 879 880开始认证。 881 882> **说明：** 883> 从 API version 9 开始支持，从 API version 10 开始废弃。 884 885> **说明：** 886> 使用获取到的[AuthInstance](#authinstancedeprecated)对象调用该接口进行认证。 887 888**需要权限**：ohos.permission.ACCESS_BIOMETRIC 889 890**系统能力**：SystemCapability.UserIAM.UserAuth.Core 891 892**错误码：** 893 894以下错误码的详细介绍请参见[用户认证错误码](../errorcodes/errorcode-useriam.md)。 895 896| 错误码ID | 错误信息 | 897| -------- | ------- | 898| 201 | Permission verification failed. | 899| 401 | Incorrect parameters. | 900| 12500001 | Authentication failed. | 901| 12500002 | General operation error. | 902| 12500003 | The operation is canceled. | 903| 12500004 | The operation is time-out. | 904| 12500005 | The authentication type is not supported. | 905| 12500006 | The authentication trust level is not supported. | 906| 12500007 | The authentication task is busy. | 907| 12500009 | The authenticator is locked. | 908| 12500010 | The type of credential has not been enrolled. | 909 910**示例：** 911 912```ts 913import userIAM_userAuth from '@ohos.userIAM.userAuth'; 914 915let challenge = new Uint8Array([1, 2, 3, 4, 5, 6, 7, 8]); 916let authType = userIAM_userAuth.UserAuthType.FACE; 917let authTrustLevel = userIAM_userAuth.AuthTrustLevel.ATL1; 918 919try { 920 let auth = userIAM_userAuth.getAuthInstance(challenge, authType, authTrustLevel); 921 auth.start(); 922 console.info('authV9 start auth success'); 923} catch (error) { 924 console.info('authV9 start auth failed, error = ' + error); 925} 926``` 927 928### cancel<sup>(deprecated)</sup> 929 930cancel : () => void 931 932取消认证。 933 934> **说明：** 935> 从 API version 9 开始支持，从 API version 10 开始废弃。 936 937> **说明：** 938> 使用获取到的[AuthInstance](#authinstancedeprecated)对象调用该接口进行取消认证，此[AuthInstance](#authinstancedeprecated)需要是正在进行认证的对象。 939 940**需要权限**：ohos.permission.ACCESS_BIOMETRIC 941 942**系统能力**：SystemCapability.UserIAM.UserAuth.Core 943 944**错误码：** 945 946以下错误码的详细介绍请参见[用户认证错误码](../errorcodes/errorcode-useriam.md)。 947 948| 错误码ID | 错误信息 | 949| -------- | ------- | 950| 201 | Permission verification failed. | 951| 401 | Incorrect parameters. | 952| 12500002 | General operation error. | 953 954**示例：** 955 956```ts 957import userIAM_userAuth from '@ohos.userIAM.userAuth'; 958 959let challenge = new Uint8Array([1, 2, 3, 4, 5, 6, 7, 8]); 960let authType = userIAM_userAuth.UserAuthType.FACE; 961let authTrustLevel = userIAM_userAuth.AuthTrustLevel.ATL1; 962 963try { 964 let auth = userIAM_userAuth.getAuthInstance(challenge, authType, authTrustLevel); 965 auth.cancel(); 966 console.info('cancel auth success'); 967} catch (error) { 968 console.info('cancel auth failed, error = ' + error); 969} 970``` 971 972## userIAM_userAuth.getAuthInstance<sup>(deprecated)</sup> 973 974getAuthInstance(challenge : Uint8Array, authType : UserAuthType, authTrustLevel : AuthTrustLevel): AuthInstance 975 976获取AuthInstance对象，用于执行用户身份认证。 977 978> **说明：** 979> 从 API version 9 开始支持，从 API version 10 开始废弃，请使用[getUserAuthInstance](#getuserauthinstance10)替代。 980 981> **说明：** 982> 每个AuthInstance只能进行一次认证，若需要再次进行认证则需重新获取AuthInstance。 983 984**系统能力**：SystemCapability.UserIAM.UserAuth.Core 985 986**参数：** 987 988| 参数名 | 类型 | 必填 | 说明 | 989| -------------- | ---------------------------------------- | ---- | ------------------------ | 990| challenge | Uint8Array | 是 | 挑战值，最大长度为32字节，可以传Uint8Array([])。 | 991| authType | [UserAuthType](#userauthtype8) | 是 | 认证类型，当前支持FACE。 | 992| authTrustLevel | [AuthTrustLevel](#authtrustlevel8) | 是 | 认证信任等级。 | 993 994**返回值：** 995 996| 类型 | 说明 | 997| --------------------------------------- | ------------ | 998| [AuthInstance](#authinstancedeprecated) | 认证器对象。 | 999 1000**错误码：** 1001 1002以下错误码的详细介绍请参见[用户认证错误码](../errorcodes/errorcode-useriam.md)。 1003 1004| 错误码ID | 错误信息 | 1005| -------- | ------- | 1006| 401 | Incorrect parameters. | 1007| 12500002 | General operation error. | 1008| 12500005 | The authentication type is not supported. | 1009| 12500006 | The authentication trust level is not supported. | 1010 1011**示例：** 1012 1013```ts 1014import userIAM_userAuth from '@ohos.userIAM.userAuth'; 1015 1016let challenge = new Uint8Array([1, 2, 3, 4, 5, 6, 7, 8]); 1017let authType = userIAM_userAuth.UserAuthType.FACE; 1018let authTrustLevel = userIAM_userAuth.AuthTrustLevel.ATL1; 1019 1020try { 1021 let auth = userIAM_userAuth.getAuthInstance(challenge, authType, authTrustLevel); 1022 console.info('let auth instance success'); 1023} catch (error) { 1024 console.info('get auth instance success failed, error = ' + error); 1025} 1026``` 1027 1028## userIAM_userAuth.getAvailableStatus<sup>9+</sup> 1029 1030getAvailableStatus(authType : UserAuthType, authTrustLevel : AuthTrustLevel): void 1031 1032查询指定类型和等级的认证能力是否支持。 1033 1034**需要权限**：ohos.permission.ACCESS_BIOMETRIC 1035 1036**系统能力**：SystemCapability.UserIAM.UserAuth.Core 1037 1038**参数：** 1039 1040| 参数名 | 类型 | 必填 | 说明 | 1041| -------------- | ---------------------------------- | ---- | -------------------------- | 1042| authType | [UserAuthType](#userauthtype8) | 是 | 认证类型。 | 1043| authTrustLevel | [AuthTrustLevel](#authtrustlevel8) | 是 | 认证信任等级。 | 1044 1045**错误码：** 1046 1047以下错误码的详细介绍请参见[用户认证错误码](../errorcodes/errorcode-useriam.md)。 1048 1049| 错误码ID | 错误信息 | 1050| -------- | ------- | 1051| 201 | Permission verification failed. | 1052| 401 | Incorrect parameters. | 1053| 12500002 | General operation error. | 1054| 12500005 | The authentication type is not supported. | 1055| 12500006 | The authentication trust level is not supported. | 1056| 12500010 | The type of credential has not been enrolled. | 1057 1058**示例：** 1059 1060```ts 1061import userIAM_userAuth from '@ohos.userIAM.userAuth'; 1062 1063try { 1064 userIAM_userAuth.getAvailableStatus(userIAM_userAuth.UserAuthType.FACE, userIAM_userAuth.AuthTrustLevel.ATL1); 1065 console.info('current auth trust level is supported'); 1066} catch (error) { 1067 console.info('current auth trust level is not supported, error = ' + error); 1068} 1069``` 1070 1071## UserAuthResultCode<sup>9+</sup> 1072 1073表示返回码的枚举。 1074 1075**系统能力**：SystemCapability.UserIAM.UserAuth.Core 1076 1077| 名称 | 值 | 说明 | 1078| ----------------------- | ------ | -------------------- | 1079| SUCCESS | 12500000 | 执行成功。 | 1080| FAIL | 12500001 | 认证失败。 | 1081| GENERAL_ERROR | 12500002 | 操作通用错误。 | 1082| CANCELED | 12500003 | 操作取消。 | 1083| TIMEOUT | 12500004 | 操作超时。 | 1084| TYPE_NOT_SUPPORT | 12500005 | 不支持的认证类型。 | 1085| TRUST_LEVEL_NOT_SUPPORT | 12500006 | 不支持的认证等级。 | 1086| BUSY | 12500007 | 忙碌状态。 | 1087| LOCKED | 12500009 | 认证器已锁定。 | 1088| NOT_ENROLLED | 12500010 | 用户未录入认证信息。 | 1089| CANCELED_FROM_WIDGET<sup>10+</sup> | 12500011 | 当前的认证操作被用户从组件取消。返回这个错误码，表示使用应用自定义认证。 | 1090 1091## UserAuth<sup>(deprecated)</sup> 1092 1093认证器对象。 1094 1095### constructor<sup>(deprecated)</sup> 1096 1097constructor() 1098 1099创建认证器对象。 1100 1101> **说明：** 1102> 从 API version 8 开始支持，从 API version 9 开始废弃，请使用[getAuthInstance](#useriam_userauthgetauthinstancedeprecated)替代。 1103 1104**系统能力**：SystemCapability.UserIAM.UserAuth.Core 1105 1106**返回值：** 1107 1108| 类型 | 说明 | 1109| ---------------------- | -------------------- | 1110| [UserAuth](#userauthdeprecated) | 认证器对象。 | 1111 1112**示例：** 1113 1114```ts 1115import userIAM_userAuth from '@ohos.userIAM.userAuth'; 1116 1117let auth = new userIAM_userAuth.UserAuth(); 1118``` 1119 1120### getVersion<sup>(deprecated)</sup> 1121 1122getVersion() : number 1123 1124获取认证器的版本信息。 1125 1126> **说明：** 1127> 从 API version 8 开始支持，从 API version 9 开始废弃。 1128 1129**需要权限**：ohos.permission.ACCESS_BIOMETRIC 1130 1131**系统能力**：SystemCapability.UserIAM.UserAuth.Core 1132 1133**返回值：** 1134 1135| 类型 | 说明 | 1136| ------ | ---------------------- | 1137| number | 认证器版本信息。 | 1138 1139**示例：** 1140 1141```ts 1142import userIAM_userAuth from '@ohos.userIAM.userAuth'; 1143 1144let auth = new userIAM_userAuth.UserAuth(); 1145let version = auth.getVersion(); 1146console.info('auth version = ' + version); 1147``` 1148 1149### getAvailableStatus<sup>(deprecated)</sup> 1150 1151getAvailableStatus(authType : UserAuthType, authTrustLevel : AuthTrustLevel) : number 1152 1153查询指定类型和等级的认证能力是否支持。 1154 1155> **说明：** 1156> 从 API version 8 开始支持，从 API version 9 开始废弃，请使用[getAvailableStatus](#useriam_userauthgetavailablestatus9)替代。 1157 1158**需要权限**：ohos.permission.ACCESS_BIOMETRIC 1159 1160**系统能力**：SystemCapability.UserIAM.UserAuth.Core 1161 1162**参数：** 1163 1164| 参数名 | 类型 | 必填 | 说明 | 1165| -------------- | ---------------------------------- | ---- | -------------------------- | 1166| authType | [UserAuthType](#userauthtype8) | 是 | 认证类型，当前只支持FACE。 | 1167| authTrustLevel | [AuthTrustLevel](#authtrustlevel8) | 是 | 认证信任等级。 | 1168 1169**返回值：** 1170 1171| 类型 | 说明 | 1172| ------ | ------------------------------------------------------------ | 1173| number | 查询结果，结果为SUCCESS时表示支持，其他返回值参见[ResultCode](#resultcodedeprecated)。 | 1174 1175**示例：** 1176 1177```ts 1178import userIAM_userAuth from '@ohos.userIAM.userAuth'; 1179 1180let auth = new userIAM_userAuth.UserAuth(); 1181let checkCode = auth.getAvailableStatus(userIAM_userAuth.UserAuthType.FACE, userIAM_userAuth.AuthTrustLevel.ATL1); 1182if (checkCode == userIAM_userAuth.ResultCode.SUCCESS) { 1183 console.info('check auth support success'); 1184} else { 1185 console.error('check auth support fail, code = ' + checkCode); 1186} 1187``` 1188 1189### auth<sup>(deprecated)</sup> 1190 1191auth(challenge: Uint8Array, authType: UserAuthType, authTrustLevel: AuthTrustLevel, callback: IUserAuthCallback): Uint8Array 1192 1193执行用户认证，使用回调函数返回结果。 1194 1195> **说明：** 1196> 从 API version 8 开始支持，从 API version 9 开始废弃，建议使用[start](#startdeprecated)代替。 1197 1198**需要权限**：ohos.permission.ACCESS_BIOMETRIC 1199 1200**系统能力**：SystemCapability.UserIAM.UserAuth.Core 1201 1202**参数：** 1203 1204| 参数名 | 类型 | 必填 | 说明 | 1205| -------------- | ---------------------------------------- | ---- | ------------------------ | 1206| challenge | Uint8Array | 是 | 挑战值，可以传Uint8Array([])。 | 1207| authType | [UserAuthType](#userauthtype8) | 是 | 认证类型，当前支持FACE。 | 1208| authTrustLevel | [AuthTrustLevel](#authtrustlevel8) | 是 | 认证信任等级。 | 1209| callback | [IUserAuthCallback](#iuserauthcallbackdeprecated) | 是 | 回调函数。 | 1210 1211**返回值：** 1212 1213| 类型 | 说明 | 1214| ---------- | ------------------------------------------------------------ | 1215| Uint8Array | ContextId，作为取消认证[cancelAuth](#cancelauthdeprecated)接口的入参。 | 1216 1217**示例：** 1218 1219```ts 1220import userIAM_userAuth from '@ohos.userIAM.userAuth'; 1221 1222let auth = new userIAM_userAuth.UserAuth(); 1223let challenge = new Uint8Array([]); 1224auth.auth(challenge, userIAM_userAuth.UserAuthType.FACE, userIAM_userAuth.AuthTrustLevel.ATL1, { 1225 onResult: (result, extraInfo) => { 1226 try { 1227 console.info('auth onResult result = ' + result); 1228 console.info('auth onResult extraInfo = ' + JSON.stringify(extraInfo)); 1229 if (result == userIAM_userAuth.ResultCode.SUCCESS) { 1230 // 此处添加认证成功逻辑 1231 } else { 1232 // 此处添加认证失败逻辑 1233 } 1234 } catch (e) { 1235 console.info('auth onResult error = ' + e); 1236 } 1237 } 1238}); 1239``` 1240 1241### cancelAuth<sup>(deprecated)</sup> 1242 1243cancelAuth(contextID : Uint8Array) : number 1244 1245表示通过contextID取消本次认证操作。 1246 1247> **说明：** 1248> 从 API version 8 开始支持，从 API version 9 开始废弃，建议使用[cancel](#canceldeprecated)代替。 1249 1250**需要权限**：ohos.permission.ACCESS_BIOMETRIC 1251 1252**系统能力**：SystemCapability.UserIAM.UserAuth.Core 1253 1254**参数：** 1255 1256| 参数名 | 类型 | 必填 | 说明 | 1257| --------- | ---------- | ---- | ------------------------------------------ | 1258| contextID | Uint8Array | 是 | 上下文的标识，通过[auth](#authdeprecated)接口获取。 | 1259 1260**返回值：** 1261 1262| 类型 | 说明 | 1263| ------ | ------------------------ | 1264| number | 取消认证的结果，结果为SUCCESS时表示取消成功，其他返回值参见[ResultCode](#resultcodedeprecated)。 | 1265 1266**示例：** 1267 1268```ts 1269import userIAM_userAuth from '@ohos.userIAM.userAuth'; 1270 1271// contextId可通过auth接口获取，此处直接定义 1272let contextId = new Uint8Array([0, 1, 2, 3, 4, 5, 6, 7]); 1273let auth = new userIAM_userAuth.UserAuth(); 1274let cancelCode = auth.cancelAuth(contextId); 1275if (cancelCode == userIAM_userAuth.ResultCode.SUCCESS) { 1276 console.info('cancel auth success'); 1277} else { 1278 console.error('cancel auth fail'); 1279} 1280``` 1281 1282## IUserAuthCallback<sup>(deprecated)</sup> 1283 1284返回认证结果的回调对象。 1285 1286> **说明：** 1287> 从 API version 8 开始支持，从 API version 9 开始废弃，建议使用[AuthEvent](#authevent9)代替。 1288 1289### onResult<sup>(deprecated)</sup> 1290 1291onResult: (result : number, extraInfo : AuthResult) => void 1292 1293回调函数，返回认证结果。 1294 1295> **说明：** 1296> 从 API version 8 开始支持，从 API version 9 开始废弃，建议使用[callback](#callback9)代替。 1297 1298**系统能力**：SystemCapability.UserIAM.UserAuth.Core 1299 1300**参数：** 1301 1302| 参数名 | 类型 | 必填 | 说明 | 1303| --------- | -------------------------- | ---- | ------------------------------------------------ | 1304| result | number | 是 | 认证结果，参见[ResultCode](#resultcodedeprecated)。 | 1305| extraInfo | [AuthResult](#authresultdeprecated) | 是 | 扩展信息，不同情况下的具体信息，<br/>如果身份验证通过，则在extraInfo中返回用户认证令牌，<br/>如果身份验证失败，则在extraInfo中返回剩余的用户认证次数，<br/>如果身份验证执行器被锁定，则在extraInfo中返回冻结时间。 | 1306 1307**示例：** 1308 1309```ts 1310import userIAM_userAuth from '@ohos.userIAM.userAuth'; 1311 1312let auth = new userIAM_userAuth.UserAuth(); 1313let challenge = new Uint8Array([]); 1314auth.auth(challenge, userIAM_userAuth.UserAuthType.FACE, userIAM_userAuth.AuthTrustLevel.ATL1, { 1315 onResult: (result, extraInfo) => { 1316 try { 1317 console.info('auth onResult result = ' + result); 1318 console.info('auth onResult extraInfo = ' + JSON.stringify(extraInfo)); 1319 if (result == userIAM_userAuth.ResultCode.SUCCESS) { 1320 // 此处添加认证成功逻辑 1321 } else { 1322 // 此处添加认证失败逻辑 1323 } 1324 } catch (e) { 1325 console.info('auth onResult error = ' + e); 1326 } 1327 } 1328}); 1329``` 1330 1331### onAcquireInfo<sup>(deprecated)</sup> 1332 1333onAcquireInfo ?: (module : number, acquire : number, extraInfo : any) => void 1334 1335回调函数，返回认证过程中的提示信息，非必须实现。 1336 1337> **说明：** 1338> 从 API version 8 开始支持，从 API version 9 开始废弃，建议使用[callback](#callback9)代替。 1339 1340**系统能力**：SystemCapability.UserIAM.UserAuth.Core 1341 1342**参数：** 1343 1344| 参数名 | 类型 | 必填 | 说明 | 1345| --------- | ------ | ---- | ------------------------------ | 1346| module | number | 是 | 发送提示信息的模块标识。 | 1347| acquire | number | 是 | 认证执过程中的提示信息。 | 1348| extraInfo | any | 是 | 预留字段。 | 1349 1350**示例：** 1351 1352```ts 1353import userIAM_userAuth from '@ohos.userIAM.userAuth'; 1354 1355let auth = new userIAM_userAuth.UserAuth(); 1356let challenge = new Uint8Array([]); 1357auth.auth(challenge, userIAM_userAuth.UserAuthType.FACE, userIAM_userAuth.AuthTrustLevel.ATL1, { 1358 onResult: (result, extraInfo) => { 1359 try { 1360 console.info('auth onResult result = ' + result); 1361 console.info('auth onResult extraInfo = ' + JSON.stringify(extraInfo)); 1362 if (result == userIAM_userAuth.ResultCode.SUCCESS) { 1363 // 此处添加认证成功逻辑 1364 } else { 1365 // 此处添加认证失败逻辑 1366 } 1367 } catch (e) { 1368 console.info('auth onResult error = ' + e); 1369 } 1370 }, 1371 onAcquireInfo: (module, acquire, extraInfo : userIAM_userAuth.AuthResult) => { 1372 try { 1373 console.info('auth onAcquireInfo module = ' + module); 1374 console.info('auth onAcquireInfo acquire = ' + acquire); 1375 console.info('auth onAcquireInfo extraInfo = ' + JSON.stringify(extraInfo)); 1376 } catch (e) { 1377 console.info('auth onAcquireInfo error = ' + e); 1378 } 1379 } 1380}); 1381``` 1382 1383## AuthResult<sup>(deprecated)</sup> 1384 1385表示认证结果的对象。 1386 1387> **说明：** 1388> 从 API version 8 开始支持，从 API version 9 开始废弃，建议使用[AuthResultInfo](#authresultinfo9)代替。 1389 1390**系统能力**：SystemCapability.UserIAM.UserAuth.Core 1391 1392| 名称 | 类型 | 必填 | 说明 | 1393| ------------ | ---------- | ---- | -------------------| 1394| token | Uint8Array | 否 | 认证通过的令牌信息。 | 1395| remainTimes | number | 否 | 剩余的认证操作次数。 | 1396| freezingTime | number | 否 | 认证操作的冻结时间。 | 1397 1398## ResultCode<sup>(deprecated)</sup> 1399 1400表示返回码的枚举。 1401 1402> **说明：** 1403> 从 API version 9 开始废弃，建议使用[UserAuthResultCode](#userauthresultcode9)代替。 1404 1405**系统能力**：SystemCapability.UserIAM.UserAuth.Core 1406 1407| 名称 | 值 | 说明 | 1408| ----------------------- | ------ | -------------------- | 1409| SUCCESS | 0 | 执行成功。 | 1410| FAIL | 1 | 认证失败。 | 1411| GENERAL_ERROR | 2 | 操作通用错误。 | 1412| CANCELED | 3 | 操作取消。 | 1413| TIMEOUT | 4 | 操作超时。 | 1414| TYPE_NOT_SUPPORT | 5 | 不支持的认证类型。 | 1415| TRUST_LEVEL_NOT_SUPPORT | 6 | 不支持的认证等级。 | 1416| BUSY | 7 | 忙碌状态。 | 1417| INVALID_PARAMETERS | 8 | 无效参数。 | 1418| LOCKED | 9 | 认证器已锁定。 | 1419| NOT_ENROLLED | 10 | 用户未录入认证信息。 | 1420 1421## FaceTips<sup>8+</sup> 1422 1423表示人脸认证过程中提示码的枚举。 1424 1425**系统能力**：SystemCapability.UserIAM.UserAuth.Core 1426 1427| 名称 | 值 | 说明 | 1428| ----------------------------- | ------ | ------------------------------------ | 1429| FACE_AUTH_TIP_TOO_BRIGHT | 1 | 光线太强，获取的图像太亮。 | 1430| FACE_AUTH_TIP_TOO_DARK | 2 | 光线太暗，获取的图像太暗。 | 1431| FACE_AUTH_TIP_TOO_CLOSE | 3 | 人脸距离设备过近。 | 1432| FACE_AUTH_TIP_TOO_FAR | 4 | 人脸距离设备过远。 | 1433| FACE_AUTH_TIP_TOO_HIGH | 5 | 设备太高，仅获取到人脸上部。 | 1434| FACE_AUTH_TIP_TOO_LOW | 6 | 设备太低，仅获取到人脸下部。 | 1435| FACE_AUTH_TIP_TOO_RIGHT | 7 | 设备太靠右，仅获取到人脸右部。 | 1436| FACE_AUTH_TIP_TOO_LEFT | 8 | 设备太靠左，仅获取到人脸左部。 | 1437| FACE_AUTH_TIP_TOO_MUCH_MOTION | 9 | 在图像采集过程中，用户人脸移动太快。 | 1438| FACE_AUTH_TIP_POOR_GAZE | 10 | 没有正视摄像头。 | 1439| FACE_AUTH_TIP_NOT_DETECTED | 11 | 没有检测到人脸信息。 | 1440 1441 1442## FingerprintTips<sup>8+</sup> 1443 1444表示指纹认证过程中提示码的枚举。 1445 1446**系统能力**：SystemCapability.UserIAM.UserAuth.Core 1447 1448| 名称 | 值 | 说明 | 1449| --------------------------------- | ------ | -------------------------------------------------- | 1450| FINGERPRINT_AUTH_TIP_GOOD | 0 | 获取的指纹图像良好。 | 1451| FINGERPRINT_AUTH_TIP_DIRTY | 1 | 由于传感器上可疑或检测到的污垢，指纹图像噪音过大。 | 1452| FINGERPRINT_AUTH_TIP_INSUFFICIENT | 2 | 由于检测到的情况，指纹图像噪声太大，无法处理。 | 1453| FINGERPRINT_AUTH_TIP_PARTIAL | 3 | 仅检测到部分指纹图像。 | 1454| FINGERPRINT_AUTH_TIP_TOO_FAST | 4 | 快速移动，指纹图像不完整。 | 1455| FINGERPRINT_AUTH_TIP_TOO_SLOW | 5 | 缺少运动，指纹图像无法读取。 | 1456 1457 1458## UserAuthType<sup>8+</sup> 1459 1460表示身份认证的凭据类型枚举。 1461 1462**系统能力**：SystemCapability.UserIAM.UserAuth.Core 1463 1464| 名称 | 值 | 说明 | 1465| ----------- | ---- | ---------- | 1466| PIN<sup>10+</sup> | 1 | 口令认证。 | 1467| FACE | 2 | 人脸认证。 | 1468| FINGERPRINT | 4 | 指纹认证。 | 1469 1470## AuthTrustLevel<sup>8+</sup> 1471 1472表示认证结果的信任等级枚举。 1473 1474**系统能力**：SystemCapability.UserIAM.UserAuth.Core 1475 1476| 名称 | 值 | 说明 | 1477| ---- | ----- | ------------------------------------------------------------ | 1478| ATL1 | 10000 | 认证结果的信任等级级别1，代表该认证方案能够识别用户个体，有一定的活体检测能力。常用的业务场景有业务风控、一般个人数据查询等。 | 1479| ATL2 | 20000 | 认证结果的信任等级级别2，代表该认证方案能够精确识别用户个体，有一定的活体检测能力。常用的业务场景有维持设备解锁状态，应用登录等。 | 1480| ATL3 | 30000 | 认证结果的信任等级级别3，代表该认证方案能够精确识别用户个体，有较强的活体检测能力。常用的业务场景有设备解锁等。 | 1481| ATL4 | 40000 | 认证结果的信任等级级别4，代表该认证方案能够高精度的识别用户个体，有很强的活体检测能力。常用的业务场景有小额支付等。 | 1482 1483## userIAM_userAuth.getAuthenticator<sup>(deprecated)</sup> 1484 1485getAuthenticator(): Authenticator 1486 1487获取Authenticator对象，用于执行用户身份认证。 1488 1489> **说明：** 1490> 从 API version 8 开始废弃，建议使用[constructor](#constructordeprecated)替代。 1491 1492**系统能力**：SystemCapability.UserIAM.UserAuth.Core 1493 1494**返回值：** 1495 1496| 类型 | 说明 | 1497| ----------------------------------------- | ------------ | 1498| [Authenticator](#authenticatordeprecated) | 认证器对象。 | 1499 1500**示例：** 1501 ```ts 1502 import userIAM_userAuth from '@ohos.userIAM.userAuth'; 1503 1504 let authenticator = userIAM_userAuth.getAuthenticator(); 1505 ``` 1506 1507## Authenticator<sup>(deprecated)</sup> 1508 1509认证器对象。 1510 1511> **说明：** 1512> 从 API version 8 开始废弃，建议使用[UserAuth](#userauthdeprecated)替代。 1513 1514### execute<sup>(deprecated)</sup> 1515 1516execute(type: AuthType, level: SecureLevel, callback: AsyncCallback<number>): void 1517 1518执行用户认证，使用callback方式作为异步方法。 1519 1520> **说明：** 1521> 从 API version 8 开始废弃，建议使用[auth](#authdeprecated)替代。 1522 1523**需要权限**：ohos.permission.ACCESS_BIOMETRIC 1524 1525**系统能力**：SystemCapability.UserIAM.UserAuth.Core 1526 1527**参数：** 1528 1529| 参数名 | 类型 | 必填 | 说明 | 1530| -------- | --------------------------- | ---- | -------------------------- | 1531| type | AuthType | 是 | 认证类型，当前只支持"FACE_ONLY"。<br/>ALL为预留参数，当前版本暂不支持ALL类型的认证。 | 1532| level | SecureLevel | 是 | 安全级别，对应认证的安全级别，有效值为"S1"（最低）、"S2"、"S3"、"S4"（最高）。<br/>具备3D人脸识别能力的设备支持"S3"及以下安全级别的认证。<br/>具备2D人脸识别能力的设备支持"S2"及以下安全级别的认证。 | 1533| callback | AsyncCallback<number> | 是 | 回调函数。 | 1534 1535callback返回值： 1536 1537| 类型 | 说明 | 1538| ------ | ------------------------------------------------------------ | 1539| number | 表示认证结果，参见[AuthenticationResult](#authenticationresultdeprecated)。 | 1540 1541**示例：** 1542 1543```ts 1544import userIAM_userAuth from '@ohos.userIAM.userAuth'; 1545 1546let authenticator = userIAM_userAuth.getAuthenticator(); 1547authenticator.execute('FACE_ONLY', 'S2', (error, code)=>{ 1548 if (code === userIAM_userAuth.ResultCode.SUCCESS) { 1549 console.info('auth success'); 1550 return; 1551 } 1552 console.error('auth fail, code = ' + code); 1553}); 1554``` 1555 1556 1557### execute<sup>(deprecated)</sup> 1558 1559execute(type : AuthType, level : SecureLevel): Promise<number> 1560 1561执行用户认证，使用promise方式作为异步方法。 1562 1563> **说明：** 1564> 从 API version 8 开始废弃，建议使用[auth](#authdeprecated)替代。 1565 1566**需要权限**：ohos.permission.ACCESS_BIOMETRIC 1567 1568**系统能力**：SystemCapability.UserIAM.UserAuth.Core 1569 1570**参数：** 1571 1572| 参数名 | 类型 | 必填 | 说明 | 1573| ------ | ------ | ---- | ------------------------------------------------------------ | 1574| type | AuthType | 是 | 认证类型，当前只支持"FACE_ONLY"。<br/>ALL为预留参数，当前版本暂不支持ALL类型的认证。 | 1575| level | SecureLevel | 是 | 安全级别，对应认证的安全级别，有效值为"S1"（最低）、"S2"、"S3"、"S4"（最高）。<br/>具备3D人脸识别能力的设备支持"S3"及以下安全级别的认证。<br/>具备2D人脸识别能力的设备支持"S2"及以下安全级别的认证。 | 1576 1577**返回值：** 1578 1579| 类型 | 说明 | 1580| --------------------- | ------------------------------------------------------------ | 1581| Promise<number> | 返回携带一个number的Promise。number 为认证结果，参见[AuthenticationResult](#authenticationresultdeprecated)。 | 1582 1583**示例：** 1584 1585```ts 1586import userIAM_userAuth from '@ohos.userIAM.userAuth'; 1587 1588try { 1589 let authenticator = userIAM_userAuth.getAuthenticator(); 1590 authenticator.execute('FACE_ONLY', 'S2').then((code)=>{ 1591 console.info('auth success'); 1592 }) 1593} catch (error) { 1594 console.error('auth fail, code = ' + error); 1595} 1596``` 1597 1598## AuthenticationResult<sup>(deprecated)</sup> 1599 1600表示认证结果的枚举。 1601 1602> **说明：** 1603> 从 API version 8 开始废弃，建议使用[ResultCode](#resultcodedeprecated)替代。 1604 1605**系统能力**：SystemCapability.UserIAM.UserAuth.Core 1606 1607| 名称 | 值 | 说明 | 1608| ------------------ | ------ | -------------------------- | 1609| NO_SUPPORT | -1 | 设备不支持当前的认证方式。 | 1610| SUCCESS | 0 | 认证成功。 | 1611| COMPARE_FAILURE | 1 | 比对失败。 | 1612| CANCELED | 2 | 用户取消认证。 | 1613| TIMEOUT | 3 | 认证超时。 | 1614| CAMERA_FAIL | 4 | 开启相机失败。 | 1615| BUSY | 5 | 认证服务忙，请稍后重试。 | 1616| INVALID_PARAMETERS | 6 | 认证参数无效。 | 1617| LOCKED | 7 | 认证失败次数过多，已锁定。 | 1618| NOT_ENROLLED | 8 | 未录入认证凭据。 | 1619| GENERAL_ERROR | 100 | 其他错误。 | 1620