1# @ohos.userIAM.userAuth (User Authentication) 2 3The **userIAM.userAuth** module provides user authentication capabilities in identity authentication scenarios, such as device unlocking, payment, and app login. 4 5> **NOTE** 6> 7> The initial APIs of this module are supported since API version 6. Newly added APIs will be marked with a superscript to indicate their earliest API version. 8 9 10## Modules to Import 11 12```ts 13import userIAM_userAuth from '@ohos.userIAM.userAuth'; 14``` 15 16## WindowModeType<sup>10+</sup> 17 18Enumerates the window types of the authentication widget. 19 20**System capability**: SystemCapability.UserIAM.UserAuth.Core 21 22**System API**: This is a system API. 23 24| Name | Value | Description | 25| ---------- | ---- | ---------- | 26| DIALOG_BOX | 1 | Dialog box.| 27| FULLSCREEN | 2 | Full screen.| 28 29## AuthParam<sup>10+</sup> 30 31Defines the user authentication parameters. 32 33**System capability**: SystemCapability.UserIAM.UserAuth.Core 34 35| Name | Type | Mandatory| Description | 36| -------------- | ---------------------------------- | ---- | ------------------------------------------------------------ | 37| challenge | Uint8Array | Yes | Challenge value, which is used to prevent replay attacks. It cannot exceed 32 bytes and can be passed in **Uint8Array([])** format.| 38| authType | [UserAuthType](#userauthtype8)[] | Yes | Authentication type list, which specifies the types of authentication provided on the user authentication page. | 39| authTrustLevel | [AuthTrustLevel](#authtrustlevel8) | Yes | Authentication trust level. | 40 41## WidgetParam<sup>10+</sup> 42 43Represents the information presented on the user authentication page. 44 45**System capability**: SystemCapability.UserIAM.UserAuth.Core 46 47| Name | Type | Mandatory| Description | 48| -------------------- | ----------------------------------- | ---- | ------------------------------------------------------------ | 49| title | string | Yes | Title of the user authentication page. It cannot exceed 500 characters. | 50| navigationButtonText | string | No | Text on the navigation button. It cannot exceed 60 characters. This parameter is valid only in fingerprint or facial authentication only.| 51| windowMode | [WindowModeType](#windowmodetype10) | No | Display format of the user authentication page. The default value is **WindowModeType.DIALOG_BOX**.<br>**System API**: This is a system API.| 52 53## UserAuthResult<sup>10+</sup> 54 55Defines the user authentication result. If the authentication is successful, the authentication type and token information are returned. 56 57**System capability**: SystemCapability.UserIAM.UserAuth.Core 58 59| Name | Type | Mandatory| Description | 60| -------- | ------------------------------ | ---- | ------------------------------------------------------------ | 61| result | number | Yes | User authentication result. If the operation is successful, **SUCCESS** is returned. If the operation fails, an error code is returned. For details, see [UserAuthResultCode](#userauthresultcode9).| 62| token | Uint8Array | No | Token that has passed the authentication. | 63| authType | [UserAuthType](#userauthtype8) | No | Type of the authentication. | 64 65 66## IAuthCallback<sup>10+</sup> 67 68Provides callbacks to return the authentication result. 69 70### onResult<sup>10+</sup> 71 72onResult(result: UserAuthResult): void 73 74Called to return the authentication result. If the authentication is successful, the token information can be obtained from **UserAuthResult**. 75 76**System capability**: SystemCapability.UserIAM.UserAuth.Core 77 78**Parameters** 79 80| Name| Type | Mandatory| Description | 81| ------ | ----------------------------------- | ---- | ---------- | 82| result | [UserAuthResult](#userauthresult10) | Yes | Authentication result.| 83 84**Example** 85 86```ts 87import userAuth from '@ohos.userIAM.userAuth'; 88 89const authParam : userAuth.AuthParam = { 90 challenge: new Uint8Array([49, 49, 49, 49, 49, 49]), 91 authType: [userAuth.UserAuthType.PIN], 92 authTrustLevel: userAuth.AuthTrustLevel.ATL1, 93}; 94const widgetParam :userAuth.WidgetParam = { 95 title:'Enter password', 96}; 97try { 98 let userAuthInstance = userAuth.getUserAuthInstance(authParam, widgetParam); 99 console.log('get userAuth instance success'); 100 // The authentication result is returned by onResult only after the authentication is started by start() of UserAuthInstance. 101 userAuthInstance.on('result', { 102 onResult (result) { 103 console.log('userAuthInstance callback result = ' + JSON.stringify(result)); 104 } 105 }); 106 console.log('auth on success'); 107} catch (error) { 108 console.error('auth catch error: ' + JSON.stringify(error)); 109} 110``` 111 112## UserAuthInstance<sup>10+</sup> 113 114Provides APIs for user authentication. The user authentication widget is supported. 115Before using the APIs, you need to obtain a **UserAuthInstance** instance by using [getUserAuthInstance](#getuserauthinstance10). 116 117### on<sup>10+</sup> 118 119on(type: 'result', callback: IAuthCallback): void 120 121Subscribes to the user authentication result. 122 123**System capability**: SystemCapability.UserIAM.UserAuth.Core 124 125**Parameters** 126 127| Name | Type | Mandatory| Description | 128| -------- | --------------------------------- | ---- | ------------------------------------------ | 129| type | 'result' | Yes | Event type. The value is **result**, which indicates the authentication result.| 130| callback | [IAuthCallback](#iauthcallback10) | Yes | Callback invoked to return the user authentication result. | 131 132**Error codes** 133 134For details about the error codes, see [User Authentication Error Codes](../errorcodes/errorcode-useriam.md). 135 136| ID| Error Message | 137| -------- | ------------------------ | 138| 401 | Incorrect parameters. | 139| 12500002 | General operation error. | 140 141**Example** 142 143```ts 144import userAuth from '@ohos.userIAM.userAuth'; 145 146const authParam : userAuth.AuthParam = { 147 challenge: new Uint8Array([49, 49, 49, 49, 49, 49]), 148 authType: [userAuth.UserAuthType.PIN], 149 authTrustLevel: userAuth.AuthTrustLevel.ATL1, 150}; 151const widgetParam :userAuth.WidgetParam = { 152 title:'Enter password', 153}; 154try { 155 let userAuthInstance = userAuth.getUserAuthInstance(authParam, widgetParam); 156 console.log('get userAuth instance success'); 157 // The authentication result is returned by onResult only after the authentication is started by start() of UserAuthInstance. 158 userAuthInstance.on('result', { 159 onResult (result) { 160 console.log('userAuthInstance callback result = ' + JSON.stringify(result)); 161 } 162 }); 163 console.log('auth on success'); 164} catch (error) { 165 console.error('auth catch error: ' + JSON.stringify(error)); 166} 167``` 168 169### off<sup>10+</sup> 170 171off(type: 'result', callback?: IAuthCallback): void 172 173Unsubscribes from the user authentication result. 174 175> **NOTE** 176> 177> The [UserAuthInstance](#userauthinstance10) instance used to call this API must be the one used to subscribe to the event. 178 179**System capability**: SystemCapability.UserIAM.UserAuth.Core 180 181**Parameters** 182 183| Name | Type | Mandatory| Description | 184| -------- | --------------------------------- | ---- | ------------------------------------------ | 185| type | 'result' | Yes | Event type. The value is **result**, which indicates the authentication result.| 186| callback | [IAuthCallback](#iauthcallback10) | No | Callback for the user authentication result. | 187 188**Error codes** 189 190For details about the error codes, see [User Authentication Error Codes](../errorcodes/errorcode-useriam.md). 191 192| ID| Error Message | 193| -------- | ------------------------ | 194| 401 | Incorrect parameters. | 195| 12500002 | General operation error. | 196 197**Example** 198 199```ts 200import userAuth from '@ohos.userIAM.userAuth'; 201 202const authParam : userAuth.AuthParam = { 203 challenge: new Uint8Array([49, 49, 49, 49, 49, 49]), 204 authType: [userAuth.UserAuthType.PIN], 205 authTrustLevel: userAuth.AuthTrustLevel.ATL1, 206}; 207const widgetParam :userAuth.WidgetParam = { 208 title:'Enter password', 209}; 210try { 211 let userAuthInstance = userAuth.getUserAuthInstance(authParam, widgetParam); 212 console.log('get userAuth instance success'); 213 userAuthInstance.off('result', { 214 onResult (result) { 215 console.log('auth off result: ' + JSON.stringify(result)); 216 } 217 }); 218 console.log('auth off success'); 219} catch (error) { 220 console.error('auth catch error: ' + JSON.stringify(error)); 221} 222``` 223 224### start<sup>10+</sup> 225 226start(): void 227 228Starts authentication. 229 230> **NOTE**<br> 231> A **UserAuthInstance** instance can be used for an authentication only once. 232 233**Required permissions**: ohos.permission.ACCESS_BIOMETRIC 234 235**System capability**: SystemCapability.UserIAM.UserAuth.Core 236 237**Error codes** 238 239For details about the error codes, see [User Authentication Error Codes](../errorcodes/errorcode-useriam.md). 240 241| ID| Error Message | 242| -------- | ------------------------------------------------ | 243| 201 | Permission verification failed. | 244| 401 | Incorrect parameters. | 245| 12500001 | Authentication failed. | 246| 12500002 | General operation error. | 247| 12500003 | The operation is canceled. | 248| 12500004 | The operation is time-out. | 249| 12500005 | The authentication type is not supported. | 250| 12500006 | The authentication trust level is not supported. | 251| 12500007 | The authentication task is busy. | 252| 12500009 | The authenticator is locked. | 253| 12500010 | The type of credential has not been enrolled. | 254| 12500011 | The authentication is canceled from widget's navigation button. | 255 256**Example** 257 258```ts 259import userAuth from '@ohos.userIAM.userAuth'; 260 261const authParam : userAuth.AuthParam = { 262 challenge: new Uint8Array([49, 49, 49, 49, 49, 49]), 263 authType: [userAuth.UserAuthType.PIN], 264 authTrustLevel: userAuth.AuthTrustLevel.ATL1, 265}; 266const widgetParam :userAuth.WidgetParam = { 267 title:'Enter password', 268}; 269try { 270 let userAuthInstance = userAuth.getUserAuthInstance(authParam, widgetParam); 271 console.log('get userAuth instance success'); 272 userAuthInstance.start(); 273 console.log('auth start success'); 274} catch (error) { 275 console.error('auth catch error: ' + JSON.stringify(error)); 276} 277``` 278 279### cancel<sup>10+</sup> 280 281cancel(): void 282 283Cancels this authentication. 284 285> **NOTE** 286> 287> **UserAuthInstance** must be the instance being authenticated. 288 289**Required permissions**: ohos.permission.ACCESS_BIOMETRIC 290 291**System capability**: SystemCapability.UserIAM.UserAuth.Core 292 293**Error codes** 294 295| ID| Error Message | 296| -------- | ------------------------------- | 297| 201 | Permission verification failed. | 298| 401 | Incorrect parameters. | 299| 12500002 | General operation error. | 300 301**Example** 302 303```ts 304import userAuth from '@ohos.userIAM.userAuth'; 305 306const authParam : userAuth.AuthParam = { 307 challenge: new Uint8Array([49, 49, 49, 49, 49, 49]), 308 authType: [userAuth.UserAuthType.PIN], 309 authTrustLevel: userAuth.AuthTrustLevel.ATL1, 310}; 311const widgetParam :userAuth.WidgetParam = { 312 title:'Enter password', 313}; 314try { 315 let userAuthInstance = userAuth.getUserAuthInstance(authParam, widgetParam); 316 console.log('get userAuth instance success'); 317 // The cancel() API can be called only after the authentication is started by start() of UserAuthInstance. 318 userAuthInstance.cancel(); 319 console.log('auth cancel success'); 320} catch (error) { 321 console.error('auth catch error: ' + JSON.stringify(error)); 322} 323``` 324 325## getUserAuthInstance<sup>10+</sup> 326 327getUserAuthInstance(authParam: AuthParam, widgetParam: WidgetParam): UserAuthInstance 328 329Obtains a [UserAuthInstance](#userauthinstance10) instance for user authentication. The user authentication widget is also supported. 330 331> **NOTE**<br> 332> A **UserAuthInstance** instance can be used for an authentication only once. 333 334**System capability**: SystemCapability.UserIAM.UserAuth.Core 335 336**Parameters** 337 338| Name | Type | Mandatory| Description | 339| ----------- | ----------------------------- | ---- | -------------------------- | 340| authParam | [AuthParam](#authparam10) | Yes | User authentication parameters. | 341| widgetParam | [WidgetParam](#widgetparam10) | Yes | Parameters on the user authentication page.| 342 343**Return value** 344 345| Type | Description | 346| --------------------------------------- | -------------------------- | 347| [UserAuthInstance](#userauthinstance10) | **UserAuthInstance** instance that supports UI.| 348 349**Error codes** 350 351For details about the error codes, see [User Authentication Error Codes](../errorcodes/errorcode-useriam.md). 352 353| ID| Error Message | 354| -------- | ------------------------------------------------ | 355| 401 | Incorrect parameters. | 356| 12500002 | General operation error. | 357| 12500005 | The authentication type is not supported. | 358| 12500006 | The authentication trust level is not supported. | 359 360**Example** 361 362```ts 363import userAuth from '@ohos.userIAM.userAuth'; 364 365const authParam : userAuth.AuthParam = { 366 challenge: new Uint8Array([49, 49, 49, 49, 49, 49]), 367 authType: [userAuth.UserAuthType.PIN], 368 authTrustLevel: userAuth.AuthTrustLevel.ATL1, 369}; 370const widgetParam :userAuth.WidgetParam = { 371 title:'Enter password', 372}; 373try { 374 let userAuthInstance = userAuth.getUserAuthInstance(authParam, widgetParam); 375 console.log('get userAuth instance success'); 376} catch (error) { 377 console.error('auth catch error: ' + JSON.stringify(error)); 378} 379``` 380 381## NoticeType<sup>10+</sup> 382 383Defines the type of the user authentication notification. 384 385**System capability**: SystemCapability.UserIAM.UserAuth.Core 386 387**System API**: This is a system API. 388 389| Name | Value | Description | 390| ------------- | ---- | -------------------- | 391| WIDGET_NOTICE | 1 | Notification from the user authentication widget.| 392 393## sendNotice<sup>10+</sup> 394 395sendNotice(noticeType: NoticeType, eventData: string): void 396 397Sends a notification from the user authentication widget. 398 399**Required permissions**: ohos.permission.SUPPORT_USER_AUTH 400 401**System capability**: SystemCapability.UserIAM.UserAuth.Core 402 403**System API**: This is a system API. 404 405**Parameters** 406 407| Name | Type | Mandatory| Description | 408| ---------- | --------------------------- | ---- | ---------- | 409| noticeType | [NoticeType](#noticetype10) | Yes | Notification type.| 410| eventData | string | Yes | Event data.| 411 412**Error codes** 413 414For details about the error codes, see [User Authentication Error Codes](../errorcodes/errorcode-useriam.md). 415 416| ID| Error Message | 417| -------- | --------------------------------------- | 418| 201 | Permission verification failed. | 419| 202 | The caller is not a system application. | 420| 401 | Incorrect parameters. | 421| 12500002 | General operation error. | 422 423**Example** 424 425```ts 426import userAuth from '@ohos.userIAM.userAuth'; 427 428interface EventData { 429 widgetContextId: number; 430 event: string; 431 version: string; 432 payload: PayLoad; 433} 434interface PayLoad { 435 type: Object[]; 436} 437try { 438 const eventData : EventData = { 439 widgetContextId: 123456, 440 event: 'EVENT_AUTH_TYPE_READY', 441 version: '1', 442 payload: { 443 type: ['pin'] 444 } as PayLoad, 445 }; 446 const jsonEventData = JSON.stringify(eventData); 447 let noticeType = userAuth.NoticeType.WIDGET_NOTICE; 448 userAuth.sendNotice(noticeType, jsonEventData); 449 console.log('sendNotice success'); 450} catch (error) { 451 console.error('sendNotice catch error: ' + JSON.stringify(error)); 452} 453``` 454 455## UserAuthWidgetMgr<sup>10+</sup> 456 457Provides APIs for managing the user authentication widget. You can use the APIs to register the user authentication widget with UserAuthWidgetMgr for management and scheduling. 458 459### on<sup>10+</sup> 460 461on(type: 'command', callback: IAuthWidgetCallback): void 462 463Subscribes to commands from the user authentication framework for the user authentication widget. 464 465**System capability**: SystemCapability.UserIAM.UserAuth.Core 466 467**System API**: This is a system API. 468 469**Parameters** 470 471| Name | Type | Mandatory| Description | 472| -------- | --------------------------------------------- | ---- | ------------------------------------------------------------ | 473| type | 'command' | Yes | Event type. The vlaue is **command**, which indicates the command sent from the user authentication framework to the user authentication widget. | 474| callback | [IAuthWidgetCallback](#iauthwidgetcallback10) | Yes | Callback invoked to return the command from the user authentication framework to the user authentication widget.| 475 476**Error codes** 477 478For details about the error codes, see [User Authentication Error Codes](../errorcodes/errorcode-useriam.md). 479 480| ID| Error Message | 481| -------- | ------------------------ | 482| 401 | Incorrect parameters. | 483| 12500002 | General operation error. | 484 485**Example** 486 487```ts 488import userAuth from '@ohos.userIAM.userAuth'; 489 490const userAuthWidgetMgrVersion = 1; 491try { 492 let userAuthWidgetMgr = userAuth.getUserAuthWidgetMgr(userAuthWidgetMgrVersion); 493 console.log('get userAuthWidgetMgr instance success'); 494 userAuthWidgetMgr.on('command', { 495 sendCommand(cmdData) { 496 console.log('The cmdData is ' + cmdData); 497 } 498 }) 499 console.log('subscribe authentication event success'); 500} catch (error) { 501 console.error('userAuth widgetMgr catch error: ' + JSON.stringify(error)); 502} 503``` 504 505### off<sup>10+</sup> 506 507off(type: 'command', callback?: IAuthWidgetCallback): void 508 509Unsubscribes from commands sent from the user authentication framework. 510 511**System capability**: SystemCapability.UserIAM.UserAuth.Core 512 513**System API**: This is a system API. 514 515**Parameters** 516 517| Name | Type | Mandatory| Description | 518| -------- | --------------------------------------------- | ---- | ------------------------------------------------------------ | 519| type | 'command' | Yes | Event type. The value is **command**, which indicates the command sent from the user authentication framework to the user authentication widget. | 520| callback | [IAuthWidgetCallback](#iauthwidgetcallback10) | No | Callback for the command sent from the user authentication framework to the user authentication widget.| 521 522**Error codes** 523 524For details about the error codes, see [User Authentication Error Codes](../errorcodes/errorcode-useriam.md). 525 526| ID| Error Message | 527| -------- | ------------------------ | 528| 401 | Incorrect parameters. | 529| 12500002 | General operation error. | 530 531**Example** 532 533```ts 534import userAuth from '@ohos.userIAM.userAuth'; 535 536const userAuthWidgetMgrVersion = 1; 537try { 538 let userAuthWidgetMgr = userAuth.getUserAuthWidgetMgr(userAuthWidgetMgrVersion); 539 console.log('get userAuthWidgetMgr instance success'); 540 userAuthWidgetMgr.off('command', { 541 sendCommand(cmdData) { 542 console.log('The cmdData is ' + cmdData); 543 } 544 }) 545 console.log('cancel subscribe authentication event success'); 546} catch (error) { 547 console.error('userAuth widgetMgr catch error: ' + JSON.stringify(error)); 548} 549``` 550 551## getUserAuthWidgetMgr<sup>10+</sup> 552 553getUserAuthWidgetMgr(version: number): UserAuthWidgetMgr 554 555Obtains a **UserAuthWidgetMgr** instance for user authentication. 556 557> **NOTE**<br> 558> A **UserAuthInstance** instance can be used for an authentication only once. 559 560**Required permissions**: ohos.permission.SUPPORT_USER_AUTH 561 562**System capability**: SystemCapability.UserIAM.UserAuth.Core 563 564**System API**: This is a system API. 565 566**Parameters** 567 568| Name | Type | Mandatory| Description | 569| ------- | ------ | ---- | -------------------- | 570| version | number | Yes | Version of the user authentication widget.| 571 572**Return value** 573 574| Type | Description | 575| ----------------------------------------- | ------------ | 576| [UserAuthWidgetMgr](#userauthwidgetmgr10) | **UserAuthWidgetMgr** instance obtained.| 577 578**Error codes** 579 580For details about the error codes, see [User Authentication Error Codes](../errorcodes/errorcode-useriam.md). 581 582| ID| Error Message | 583| -------- | --------------------------------------- | 584| 201 | Permission verification failed. | 585| 202 | The caller is not a system application. | 586| 401 | Incorrect parameters. | 587| 12500002 | General operation error. | 588 589**Example** 590 591```ts 592import userAuth from '@ohos.userIAM.userAuth'; 593 594let userAuthWidgetMgrVersion = 1; 595try { 596 let userAuthWidgetMgr = userAuth.getUserAuthWidgetMgr(userAuthWidgetMgrVersion); 597 console.log('get userAuthWidgetMgr instance success'); 598} catch (error) { 599 console.error('userAuth widgetMgr catch error: ' + JSON.stringify(error)); 600} 601``` 602 603## IAuthWidgetCallback<sup>10+</sup> 604 605Provides the callback for returning the commands sent from the user authentication framework to the user authentication widget. 606 607### sendCommand<sup>10+</sup> 608 609sendCommand(cmdData: string): void 610 611Called to return the command sent from the user authentication framework to the user authentication widget. 612 613**System capability**: SystemCapability.UserIAM.UserAuth.Core 614 615**System API**: This is a system API. 616 617**Parameters** 618 619| Name | Type | Mandatory| Description | 620| ------- | ------ | ---- | ---------------------------------- | 621| cmdData | string | Yes | Command sent from the user authentication framework to the user authentication widget.| 622 623**Example** 624 625```ts 626import userAuth from '@ohos.userIAM.userAuth'; 627 628const userAuthWidgetMgrVersion = 1; 629try { 630 let userAuthWidgetMgr = userAuth.getUserAuthWidgetMgr(userAuthWidgetMgrVersion); 631 console.log('get userAuthWidgetMgr instance success'); 632 userAuthWidgetMgr.on('command', { 633 sendCommand(cmdData) { 634 console.log('The cmdData is ' + cmdData); 635 } 636 }) 637 console.log('subscribe authentication event success'); 638} catch (error) { 639 console.error('userAuth widgetMgr catch error: ' + JSON.stringify(error)); 640} 641``` 642 643## AuthResultInfo<sup>9+</sup> 644 645Defines the authentication result. 646 647**System capability**: SystemCapability.UserIAM.UserAuth.Core 648 649| Name | Type | Mandatory| Description | 650| ------------ | ---------- | ---- | -------------------- | 651| result | number | Yes | Authentication result. | 652| token | Uint8Array | No | Token that has passed the user identity authentication.| 653| remainAttempts | number | No | Number of remaining authentication attempts.| 654| lockoutDuration | number | No | Lock duration of the authentication operation, in ms.| 655 656## TipInfo<sup>9+</sup> 657 658Defines the authentication tip information. 659 660**System capability**: SystemCapability.UserIAM.UserAuth.Core 661 662| Name | Type | Mandatory| Description | 663| ------------ | ---------- | ---- | -------------------- | 664| module | number | Yes | ID of the module that sends the tip information. | 665| tip | number | Yes | Tip to be given during the authentication process. | 666 667## EventInfo<sup>9+</sup> 668 669Enumerates the authentication event information types. 670 671**System capability**: SystemCapability.UserIAM.UserAuth.Core 672 673| Value | Description | 674| --------- | ----------------------- | 675| [AuthResultInfo](#authresultinfo9) | Authentication result. | 676| [TipInfo](#tipinfo9) | Authentication tip information. | 677 678## AuthEventKey<sup>9+</sup> 679 680Defines the keyword of the authentication event type. It is used as a parameter of [on](#ondeprecated). 681 682**System capability**: SystemCapability.UserIAM.UserAuth.Core 683 684| Value | Description | 685| ---------- | ----------------------- | 686| "result" | If the first parameter of [on](#ondeprecated) is **result**, the [callback](#callback9) returns the authentication result.| 687| "tip" | If the first parameter of [on](#ondeprecated) is **tip**, the [callback](#callback9) returns the authentication tip information.| 688 689## AuthEvent<sup>9+</sup> 690 691Provides an asynchronous callback to return the authentication event information. 692 693### callback<sup>9+</sup> 694 695callback(result : EventInfo) : void 696 697Called to return the authentication result or authentication tip information. 698 699**System capability**: SystemCapability.UserIAM.UserAuth.Core 700 701**Parameters** 702 703| Name | Type | Mandatory| Description | 704| --------- | -------------------------- | ---- | ------------------------------ | 705| result | [EventInfo](#eventinfo9) | Yes | Authentication result or tip information. | 706 707**Example** 708 709```ts 710import userIAM_userAuth from '@ohos.userIAM.userAuth'; 711 712let challenge = new Uint8Array([1, 2, 3, 4, 5, 6, 7, 8]); 713let authType = userIAM_userAuth.UserAuthType.FACE; 714let authTrustLevel = userIAM_userAuth.AuthTrustLevel.ATL1; 715// Obtain the authentication result through a callback. 716try { 717 let auth = userIAM_userAuth.getAuthInstance(challenge, authType, authTrustLevel); 718 auth.on('result', { 719 callback: (result: userIAM_userAuth.AuthResultInfo) => { 720 console.log('authV9 result ' + result.result); 721 console.log('authV9 token ' + result.token); 722 console.log('authV9 remainAttempts ' + result.remainAttempts); 723 console.log('authV9 lockoutDuration ' + result.lockoutDuration); 724 } 725 } as userIAM_userAuth.AuthEvent); 726 auth.start(); 727 console.log('authV9 start success'); 728} catch (error) { 729 console.error('authV9 error = ' + error); 730 // do error 731} 732// Obtain the authentication tip information through a callback. 733try { 734 let auth = userIAM_userAuth.getAuthInstance(challenge, authType, authTrustLevel); 735 auth.on('tip', { 736 callback : (result : userIAM_userAuth.TipInfo) => { 737 switch (result.tip) { 738 case userIAM_userAuth.FaceTips.FACE_AUTH_TIP_TOO_BRIGHT: 739 // Do something. 740 case userIAM_userAuth.FaceTips.FACE_AUTH_TIP_TOO_DARK: 741 // Do something. 742 default: 743 // Do others. 744 } 745 } 746 } as userIAM_userAuth.AuthEvent); 747 auth.start(); 748 console.log('authV9 start success'); 749} catch (error) { 750 console.error('authV9 error = ' + error); 751 // do error 752} 753``` 754 755## AuthInstance<sup>(deprecated)</sup> 756 757Implements user authentication. 758 759> **NOTE**<br> 760> This API is supported since API version 9 and deprecated since API version 10. Use [UserAuthInstance](#userauthinstance10) instead. 761 762### on<sup>(deprecated)</sup> 763 764on : (name : AuthEventKey, callback : AuthEvent) => void 765 766Subscribes to the user authentication events of the specified type. 767 768> **NOTE**<br> 769> - This API is supported since API version 9 and deprecated since API version 10. 770> - Use the [AuthInstance](#authinstancedeprecated) instance obtained to call this API. 771 772**System capability**: SystemCapability.UserIAM.UserAuth.Core 773 774**Parameters** 775 776| Name | Type | Mandatory| Description | 777| --------- | -------------------------- | ---- | ------------------------- | 778| name | [AuthEventKey](#autheventkey9) | Yes | Authentication event type. If the value is **result**, the callback returns the authentication result. If the value is **tip**, the callback returns the authentication tip information.| 779| callback | [AuthEvent](#authevent9) | Yes | Callback invoked to return the authentication result or tip information.| 780 781**Error codes** 782 783For details about the error codes, see [User Authentication Error Codes](../errorcodes/errorcode-useriam.md). 784 785| ID| Error Message| 786| -------- | ------- | 787| 401 | Incorrect parameters. | 788| 12500002 | General operation error. | 789 790**Example** 791 792```ts 793import userIAM_userAuth from '@ohos.userIAM.userAuth'; 794 795let challenge = new Uint8Array([1, 2, 3, 4, 5, 6, 7, 8]); 796let authType = userIAM_userAuth.UserAuthType.FACE; 797let authTrustLevel = userIAM_userAuth.AuthTrustLevel.ATL1; 798try { 799 let auth = userIAM_userAuth.getAuthInstance(challenge, authType, authTrustLevel); 800 // Subscribe to the authentication result. 801 auth.on('result', { 802 callback: (result: userIAM_userAuth.AuthResultInfo) => { 803 console.log('authV9 result ' + result.result); 804 console.log('authV9 token ' + result.token); 805 console.log('authV9 remainAttempts ' + result.remainAttempts); 806 console.log('authV9 lockoutDuration ' + result.lockoutDuration); 807 } 808 }); 809 // Subscribe to authentication tip information. 810 auth.on('tip', { 811 callback : (result : userIAM_userAuth.TipInfo) => { 812 switch (result.tip) { 813 case userIAM_userAuth.FaceTips.FACE_AUTH_TIP_TOO_BRIGHT: 814 // Do something. 815 case userIAM_userAuth.FaceTips.FACE_AUTH_TIP_TOO_DARK: 816 // Do something. 817 default: 818 // Do others. 819 } 820 } 821 } as userIAM_userAuth.AuthEvent); 822 auth.start(); 823 console.log('authV9 start success'); 824} catch (error) { 825 console.error('authV9 error = ' + error); 826 // do error 827} 828``` 829 830### off<sup>(deprecated)</sup> 831 832off : (name : AuthEventKey) => void 833 834Unsubscribes from the user authentication events of the specific type. 835 836> **NOTE**<br> 837> - This API is supported since API version 9 and deprecated since API version 10. 838> - The [AuthInstance](#authinstancedeprecated) instance used to call this API must be the one used to subscribe to the events. 839 840**System capability**: SystemCapability.UserIAM.UserAuth.Core 841 842| Name | Type | Mandatory| Description | 843| --------- | -------------------------- | ---- | ------------------------- | 844| name | [AuthEventKey](#autheventkey9) | Yes | Authentication event type. If the value is **result**, the authentication result is unsubscribed from. If the value is **tip**, the authentication tip information is unsubscribed from.| 845 846**Error codes** 847 848For details about the error codes, see [User Authentication Error Codes](../errorcodes/errorcode-useriam.md). 849 850| ID| Error Message| 851| -------- | ------- | 852| 401 | Incorrect parameters. | 853| 12500002 | General operation error. | 854 855**Example** 856 857```ts 858import userIAM_userAuth from '@ohos.userIAM.userAuth'; 859 860let challenge = new Uint8Array([1, 2, 3, 4, 5, 6, 7, 8]); 861let authType = userIAM_userAuth.UserAuthType.FACE; 862let authTrustLevel = userIAM_userAuth.AuthTrustLevel.ATL1; 863try { 864 let auth = userIAM_userAuth.getAuthInstance(challenge, authType, authTrustLevel); 865 // Subscribe to the authentication result. 866 auth.on('result', { 867 callback: (result: userIAM_userAuth.AuthResultInfo) => { 868 console.log('authV9 result ' + result.result); 869 console.log('authV9 token ' + result.token); 870 console.log('authV9 remainAttempts ' + result.remainAttempts); 871 console.log('authV9 lockoutDuration ' + result.lockoutDuration); 872 } 873 }); 874 // Unsubscription result. 875 auth.off('result'); 876 console.info('cancel subscribe authentication event success'); 877} catch (error) { 878 console.error('cancel subscribe authentication event failed, error =' + error); 879 // do error 880} 881``` 882 883### start<sup>(deprecated)</sup> 884 885start : () => void 886 887Starts authentication. 888 889> **NOTE**<br> 890> - This API is supported since API version 9 and deprecated since API version 10. 891> - Use the [AuthInstance](#authinstancedeprecated) instance obtained to call this API. 892 893**Required permissions**: ohos.permission.ACCESS_BIOMETRIC 894 895**System capability**: SystemCapability.UserIAM.UserAuth.Core 896 897**Error codes** 898 899For details about the error codes, see [User Authentication Error Codes](../errorcodes/errorcode-useriam.md). 900 901| ID| Error Message| 902| -------- | ------- | 903| 201 | Permission verification failed. | 904| 401 | Incorrect parameters. | 905| 12500001 | Authentication failed. | 906| 12500002 | General operation error. | 907| 12500003 | The operation is canceled. | 908| 12500004 | The operation is time-out. | 909| 12500005 | The authentication type is not supported. | 910| 12500006 | The authentication trust level is not supported. | 911| 12500007 | The authentication task is busy. | 912| 12500009 | The authenticator is locked. | 913| 12500010 | The type of credential has not been enrolled. | 914 915**Example** 916 917```ts 918import userIAM_userAuth from '@ohos.userIAM.userAuth'; 919 920let challenge = new Uint8Array([1, 2, 3, 4, 5, 6, 7, 8]); 921let authType = userIAM_userAuth.UserAuthType.FACE; 922let authTrustLevel = userIAM_userAuth.AuthTrustLevel.ATL1; 923 924try { 925 let auth = userIAM_userAuth.getAuthInstance(challenge, authType, authTrustLevel); 926 auth.start(); 927 console.info('authV9 start auth success'); 928} catch (error) { 929 console.error('authV9 start auth failed, error = ' + error); 930} 931``` 932 933### cancel<sup>(deprecated)</sup> 934 935cancel : () => void 936 937Cancels this authentication. 938 939> **NOTE**<br> 940> - This API is supported since API version 9 and deprecated since API version 10. 941> - Use the [AuthInstance](#authinstancedeprecated) instance obtained to call this API. The [AuthInstance](#authinstancedeprecated) instance must be the instance being authenticated. 942 943**Required permissions**: ohos.permission.ACCESS_BIOMETRIC 944 945**System capability**: SystemCapability.UserIAM.UserAuth.Core 946 947**Error codes** 948 949For details about the error codes, see [User Authentication Error Codes](../errorcodes/errorcode-useriam.md). 950 951| ID| Error Message| 952| -------- | ------- | 953| 201 | Permission verification failed. | 954| 401 | Incorrect parameters. | 955| 12500002 | General operation error. | 956 957**Example** 958 959```ts 960import userIAM_userAuth from '@ohos.userIAM.userAuth'; 961 962let challenge = new Uint8Array([1, 2, 3, 4, 5, 6, 7, 8]); 963let authType = userIAM_userAuth.UserAuthType.FACE; 964let authTrustLevel = userIAM_userAuth.AuthTrustLevel.ATL1; 965 966try { 967 let auth = userIAM_userAuth.getAuthInstance(challenge, authType, authTrustLevel); 968 auth.cancel(); 969 console.info('cancel auth success'); 970} catch (error) { 971 console.error('cancel auth failed, error = ' + error); 972} 973``` 974 975## userIAM_userAuth.getAuthInstance<sup>(deprecated)</sup> 976 977getAuthInstance(challenge : Uint8Array, authType : UserAuthType, authTrustLevel : AuthTrustLevel): AuthInstance 978 979Obtains an **AuthInstance** instance for user authentication. 980 981> **NOTE**<br> 982> - This API is supported since API version 9 and deprecated since API version 10. Use [getUserAuthInstance](#getuserauthinstance10) instead. 983> - An **AuthInstance** instance can be used for an authentication only once. 984 985 986**System capability**: SystemCapability.UserIAM.UserAuth.Core 987 988**Parameters** 989 990| Name | Type | Mandatory| Description | 991| -------------- | ---------------------------------------- | ---- | ------------------------ | 992| challenge | Uint8Array | Yes | Challenge value. It cannot exceed 32 bytes and can be passed in Uint8Array([]) format.| 993| authType | [UserAuthType](#userauthtype8) | Yes | Authentication type. Currently, **FACE** and **FINGERPRINT** are supported.| 994| authTrustLevel | [AuthTrustLevel](#authtrustlevel8) | Yes | Authentication trust level. | 995 996**Return value** 997 998| Type | Description | 999| --------------------------------------- | ------------ | 1000| [AuthInstance](#authinstancedeprecated) | **AuthInstance** instance obtained.| 1001 1002**Error codes** 1003 1004For details about the error codes, see [User Authentication Error Codes](../errorcodes/errorcode-useriam.md). 1005 1006| ID| Error Message| 1007| -------- | ------- | 1008| 401 | Incorrect parameters. | 1009| 12500002 | General operation error. | 1010| 12500005 | The authentication type is not supported. | 1011| 12500006 | The authentication trust level is not supported. | 1012 1013**Example** 1014 1015```ts 1016import userIAM_userAuth from '@ohos.userIAM.userAuth'; 1017 1018let challenge = new Uint8Array([1, 2, 3, 4, 5, 6, 7, 8]); 1019let authType = userIAM_userAuth.UserAuthType.FACE; 1020let authTrustLevel = userIAM_userAuth.AuthTrustLevel.ATL1; 1021 1022try { 1023 let auth = userIAM_userAuth.getAuthInstance(challenge, authType, authTrustLevel); 1024 console.info('let auth instance success'); 1025} catch (error) { 1026 console.error('get auth instance success failed, error = ' + error); 1027} 1028``` 1029 1030## userIAM_userAuth.getAvailableStatus<sup>9+</sup> 1031 1032getAvailableStatus(authType : UserAuthType, authTrustLevel : AuthTrustLevel): void 1033 1034Checks whether the specified authentication capability is supported. 1035 1036**Required permissions**: ohos.permission.ACCESS_BIOMETRIC 1037 1038**System capability**: SystemCapability.UserIAM.UserAuth.Core 1039 1040**Parameters** 1041 1042| Name | Type | Mandatory| Description | 1043| -------------- | ---------------------------------- | ---- | -------------------------- | 1044| authType | [UserAuthType](#userauthtype8) | Yes | Authentication type. PIN is supported since API version 11.| 1045| authTrustLevel | [AuthTrustLevel](#authtrustlevel8) | Yes | Authentication trust level. | 1046 1047**Error codes** 1048 1049For details about the error codes, see [User Authentication Error Codes](../errorcodes/errorcode-useriam.md). 1050 1051| ID| Error Message| 1052| -------- | ------- | 1053| 201 | Permission verification failed. | 1054| 401 | Incorrect parameters. | 1055| 12500002 | General operation error. | 1056| 12500005 | The authentication type is not supported. | 1057| 12500006 | The authentication trust level is not supported. | 1058| 12500010 | The type of credential has not been enrolled. | 1059 1060**Example** 1061 1062```ts 1063import userIAM_userAuth from '@ohos.userIAM.userAuth'; 1064 1065try { 1066 userIAM_userAuth.getAvailableStatus(userIAM_userAuth.UserAuthType.FACE, userIAM_userAuth.AuthTrustLevel.ATL1); 1067 console.info('current auth trust level is supported'); 1068} catch (error) { 1069 console.error('current auth trust level is not supported, error = ' + error); 1070} 1071``` 1072 1073## UserAuthResultCode<sup>9+</sup> 1074 1075Enumerates the authentication result codes. 1076 1077**System capability**: SystemCapability.UserIAM.UserAuth.Core 1078 1079| Name | Value | Description | 1080| ----------------------- | ------ | -------------------- | 1081| SUCCESS | 12500000 | The authentication is successful. | 1082| FAIL | 12500001 | The authentication failed. | 1083| GENERAL_ERROR | 12500002 | A general operation error occurred. | 1084| CANCELED | 12500003 | The authentication is canceled. | 1085| TIMEOUT | 12500004 | The authentication timed out. | 1086| TYPE_NOT_SUPPORT | 12500005 | The authentication type is not supported. | 1087| TRUST_LEVEL_NOT_SUPPORT | 12500006 | The authentication trust level is not supported. | 1088| BUSY | 12500007 | Indicates the busy state. | 1089| LOCKED | 12500009 | The authentication executor is locked. | 1090| NOT_ENROLLED | 12500010 | The user has not entered the authentication information.| 1091| CANCELED_FROM_WIDGET<sup>10+</sup> | 12500011 | The authentication is canceled by the user from the user authentication widget. If this error code is returned, the authentication is customized by the application.| 1092 1093## UserAuth<sup>(deprecated)</sup> 1094 1095Provides APIs for user authentication. 1096 1097### constructor<sup>(deprecated)</sup> 1098 1099constructor() 1100 1101A constructor used to create a **UserAuth** instance. 1102 1103> **NOTE**<br> 1104> This API is supported since API version 8 and deprecated since API version 9. Use [getAuthInstance](#useriam_userauthgetauthinstancedeprecated) instead. 1105 1106**System capability**: SystemCapability.UserIAM.UserAuth.Core 1107 1108**Example** 1109 1110```ts 1111import userIAM_userAuth from '@ohos.userIAM.userAuth'; 1112 1113let auth = new userIAM_userAuth.UserAuth(); 1114``` 1115 1116### getVersion<sup>(deprecated)</sup> 1117 1118getVersion() : number 1119 1120Obtains the version of this authenticator. 1121 1122> **NOTE**<br> 1123> This API is supported since API version 8 and deprecated since API version 9. 1124 1125**Required permissions**: ohos.permission.ACCESS_BIOMETRIC 1126 1127**System capability**: SystemCapability.UserIAM.UserAuth.Core 1128 1129**Return value** 1130 1131| Type | Description | 1132| ------ | ---------------------- | 1133| number | Authenticator version obtained.| 1134 1135**Example** 1136 1137```ts 1138import userIAM_userAuth from '@ohos.userIAM.userAuth'; 1139 1140let auth = new userIAM_userAuth.UserAuth(); 1141let version = auth.getVersion(); 1142console.info('auth version = ' + version); 1143``` 1144 1145### getAvailableStatus<sup>(deprecated)</sup> 1146 1147getAvailableStatus(authType : UserAuthType, authTrustLevel : AuthTrustLevel) : number 1148 1149Checks whether the specified authentication capability is supported. 1150 1151> **NOTE**<br> 1152> This API is supported since API version 8 and deprecated since API version 9. Use [getAvailableStatus](#useriam_userauthgetavailablestatus9) instead. 1153 1154**Required permissions**: ohos.permission.ACCESS_BIOMETRIC 1155 1156**System capability**: SystemCapability.UserIAM.UserAuth.Core 1157 1158**Parameters** 1159 1160| Name | Type | Mandatory| Description | 1161| -------------- | ---------------------------------- | ---- | -------------------------- | 1162| authType | [UserAuthType](#userauthtype8) | Yes | Authentication type. Currently, **FACE** and **FINGERPRINT** are supported.| 1163| authTrustLevel | [AuthTrustLevel](#authtrustlevel8) | Yes | Authentication trust level. | 1164 1165**Return value** 1166 1167| Type | Description | 1168| ------ | ------------------------------------------------------------ | 1169| number | Query result. If the authentication capability is supported, **SUCCESS** is returned. Otherwise, a [ResultCode](#resultcodedeprecated) is returned.| 1170 1171**Example** 1172 1173```ts 1174import userIAM_userAuth from '@ohos.userIAM.userAuth'; 1175 1176let auth = new userIAM_userAuth.UserAuth(); 1177let checkCode = auth.getAvailableStatus(userIAM_userAuth.UserAuthType.FACE, userIAM_userAuth.AuthTrustLevel.ATL1); 1178if (checkCode == userIAM_userAuth.ResultCode.SUCCESS) { 1179 console.info('check auth support success'); 1180} else { 1181 console.error('check auth support fail, code = ' + checkCode); 1182} 1183``` 1184 1185### auth<sup>(deprecated)</sup> 1186 1187auth(challenge: Uint8Array, authType: UserAuthType, authTrustLevel: AuthTrustLevel, callback: IUserAuthCallback): Uint8Array 1188 1189Starts user authentication. This API uses a callback to return the result. 1190 1191> **NOTE**<br> 1192> This API is supported since API version 8 and deprecated since API version 9. Use [start](#startdeprecated) instead. 1193 1194**Required permissions**: ohos.permission.ACCESS_BIOMETRIC 1195 1196**System capability**: SystemCapability.UserIAM.UserAuth.Core 1197 1198**Parameters** 1199 1200| Name | Type | Mandatory| Description | 1201| -------------- | ---------------------------------------- | ---- | ------------------------ | 1202| challenge | Uint8Array | Yes | Challenge value, which can be passed in Uint8Array([]) format.| 1203| authType | [UserAuthType](#userauthtype8) | Yes | Authentication type. Currently, **FACE** and **FINGERPRINT** are supported.| 1204| authTrustLevel | [AuthTrustLevel](#authtrustlevel8) | Yes | Authentication trust level. | 1205| callback | [IUserAuthCallback](#iuserauthcallbackdeprecated) | Yes | Callback invoked to return the result. | 1206 1207**Return value** 1208 1209| Type | Description | 1210| ---------- | ------------------------------------------------------------ | 1211| Uint8Array | Context ID, which is used as the input parameter of [cancelAuth](#cancelauthdeprecated).| 1212 1213**Example** 1214 1215```ts 1216import userIAM_userAuth from '@ohos.userIAM.userAuth'; 1217 1218let auth = new userIAM_userAuth.UserAuth(); 1219let challenge = new Uint8Array([]); 1220auth.auth(challenge, userIAM_userAuth.UserAuthType.FACE, userIAM_userAuth.AuthTrustLevel.ATL1, { 1221 onResult: (result, extraInfo) => { 1222 try { 1223 console.info('auth onResult result = ' + result); 1224 console.info('auth onResult extraInfo = ' + JSON.stringify(extraInfo)); 1225 if (result == userIAM_userAuth.ResultCode.SUCCESS) { 1226 // Add the logic to be executed when the authentication is successful. 1227 } else { 1228 // Add the logic to be executed when the authentication fails. 1229 } 1230 } catch (error) { 1231 console.error('auth onResult error = ' + error); 1232 } 1233 } 1234}); 1235``` 1236 1237### cancelAuth<sup>(deprecated)</sup> 1238 1239cancelAuth(contextID : Uint8Array) : number 1240 1241Cancels an authentication based on the context ID. 1242 1243> **NOTE**<br> 1244> This API is supported since API version 8 and deprecated since API version 9. Use [cancel](#canceldeprecated) instead. 1245 1246**Required permissions**: ohos.permission.ACCESS_BIOMETRIC 1247 1248**System capability**: SystemCapability.UserIAM.UserAuth.Core 1249 1250**Parameters** 1251 1252| Name | Type | Mandatory| Description | 1253| --------- | ---------- | ---- | ------------------------------------------ | 1254| contextID | Uint8Array | Yes | Context ID, which is obtained by [auth](#authdeprecated).| 1255 1256**Return value** 1257 1258| Type | Description | 1259| ------ | ------------------------ | 1260| number | Returns **SUCCESS** if the cancellation is successful. Returns a [ResultCode](#resultcodedeprecated) otherwise.| 1261 1262**Example** 1263 1264```ts 1265import userIAM_userAuth from '@ohos.userIAM.userAuth'; 1266 1267// contextId can be obtained by auth(). In this example, it is defined here. 1268let contextId = new Uint8Array([0, 1, 2, 3, 4, 5, 6, 7]); 1269let auth = new userIAM_userAuth.UserAuth(); 1270let cancelCode = auth.cancelAuth(contextId); 1271if (cancelCode == userIAM_userAuth.ResultCode.SUCCESS) { 1272 console.info('cancel auth success'); 1273} else { 1274 console.error('cancel auth fail'); 1275} 1276``` 1277 1278## IUserAuthCallback<sup>(deprecated)</sup> 1279 1280Provides callbacks to return the authentication result. 1281 1282> **NOTE**<br> 1283> This object is supported since API version 8 and deprecated since API version 9. Use [AuthEvent](#authevent9) instead. 1284 1285### onResult<sup>(deprecated)</sup> 1286 1287onResult: (result : number, extraInfo : AuthResult) => void 1288 1289Called to return the authentication result. 1290 1291> **NOTE**<br> 1292> This API is supported since API version 8 and deprecated since API version 9. Use [callback](#callback9) instead. 1293 1294**System capability**: SystemCapability.UserIAM.UserAuth.Core 1295 1296**Parameters** 1297 1298| Name | Type | Mandatory| Description | 1299| --------- | -------------------------- | ---- | ------------------------------------------------ | 1300| result | number | Yes | Authentication result. For details, see [ResultCode](#resultcodedeprecated).| 1301| extraInfo | [AuthResult](#authresultdeprecated) | Yes | Extended information, which varies depending on the authentication result.<br>If the authentication is successful, the user authentication token will be returned in **extraInfo**.<br>If the authentication fails, the remaining number of authentication times will be returned in **extraInfo**.<br>If the authentication executor is locked, the freeze time will be returned in **extraInfo**.| 1302 1303**Example** 1304 1305```ts 1306import userIAM_userAuth from '@ohos.userIAM.userAuth'; 1307 1308let auth = new userIAM_userAuth.UserAuth(); 1309let challenge = new Uint8Array([]); 1310auth.auth(challenge, userIAM_userAuth.UserAuthType.FACE, userIAM_userAuth.AuthTrustLevel.ATL1, { 1311 onResult: (result, extraInfo) => { 1312 try { 1313 console.info('auth onResult result = ' + result); 1314 console.info('auth onResult extraInfo = ' + JSON.stringify(extraInfo)); 1315 if (result == userIAM_userAuth.ResultCode.SUCCESS) { 1316 // Add the logic to be executed when the authentication is successful. 1317 } else { 1318 // Add the logic to be executed when the authentication fails. 1319 } 1320 } catch (error) { 1321 console.error('auth onResult error = ' + error); 1322 } 1323 } 1324}); 1325``` 1326 1327### onAcquireInfo<sup>(deprecated)</sup> 1328 1329onAcquireInfo ?: (module : number, acquire : number, extraInfo : any) => void 1330 1331Called to acquire authentication tip information. This API is optional. 1332 1333> **NOTE**<br> 1334> This API is supported since API version 8 and deprecated since API version 9. Use [callback](#callback9) instead. 1335 1336**System capability**: SystemCapability.UserIAM.UserAuth.Core 1337 1338**Parameters** 1339 1340| Name | Type | Mandatory| Description | 1341| --------- | ------ | ---- | ------------------------------ | 1342| module | number | Yes | ID of the module that sends the tip information. | 1343| acquire | number | Yes | Authentication tip information.| 1344| extraInfo | any | Yes | Reserved field. | 1345 1346**Example** 1347 1348```ts 1349import userIAM_userAuth from '@ohos.userIAM.userAuth'; 1350 1351let auth = new userIAM_userAuth.UserAuth(); 1352let challenge = new Uint8Array([]); 1353auth.auth(challenge, userIAM_userAuth.UserAuthType.FACE, userIAM_userAuth.AuthTrustLevel.ATL1, { 1354 onResult: (result, extraInfo) => { 1355 try { 1356 console.info('auth onResult result = ' + result); 1357 console.info('auth onResult extraInfo = ' + JSON.stringify(extraInfo)); 1358 if (result == userIAM_userAuth.ResultCode.SUCCESS) { 1359 // Add the logic to be executed when the authentication is successful. 1360 } else { 1361 // Add the logic to be executed when the authentication fails. 1362 } 1363 } catch (error) { 1364 console.error('auth onResult error = ' + error); 1365 } 1366 }, 1367 onAcquireInfo: (module, acquire, extraInfo : userIAM_userAuth.AuthResult) => { 1368 try { 1369 console.info('auth onAcquireInfo module = ' + module); 1370 console.info('auth onAcquireInfo acquire = ' + acquire); 1371 console.info('auth onAcquireInfo extraInfo = ' + JSON.stringify(extraInfo)); 1372 } catch (error) { 1373 console.error('auth onAcquireInfo error = ' + error); 1374 } 1375 } 1376}); 1377``` 1378 1379## AuthResult<sup>(deprecated)</sup> 1380 1381Represents the authentication result object. 1382 1383> **NOTE**<br> 1384> This object is supported since API version 8 and deprecated since API version 9. Use [AuthResultInfo](#authresultinfo9) instead. 1385 1386**System capability**: SystemCapability.UserIAM.UserAuth.Core 1387 1388| Name | Type | Mandatory| Description | 1389| ------------ | ---------- | ---- | -------------------| 1390| token | Uint8Array | No | Authentication token information.| 1391| remainTimes | number | No | Number of remaining authentication operations.| 1392| freezingTime | number | No | Time for which the authentication operation is frozen.| 1393 1394## ResultCode<sup>(deprecated)</sup> 1395 1396Enumerates the authentication result codes. 1397 1398> **NOTE**<br> 1399> This object is deprecated since API version 9. Use [UserAuthResultCode](#userauthresultcode9) instead. 1400 1401**System capability**: SystemCapability.UserIAM.UserAuth.Core 1402 1403| Name | Value| Description | 1404| ----------------------- | ------ | -------------------- | 1405| SUCCESS | 0 | The operation is successful. | 1406| FAIL | 1 | The authentication failed. | 1407| GENERAL_ERROR | 2 | A general operation error occurred. | 1408| CANCELED | 3 | The authentication is canceled. | 1409| TIMEOUT | 4 | The authentication timed out. | 1410| TYPE_NOT_SUPPORT | 5 | The authentication type is not supported. | 1411| TRUST_LEVEL_NOT_SUPPORT | 6 | The authentication trust level is not supported. | 1412| BUSY | 7 | Indicates the busy state. | 1413| INVALID_PARAMETERS | 8 | Invalid parameters are detected. | 1414| LOCKED | 9 | The authentication executor is locked. | 1415| NOT_ENROLLED | 10 | The user has not entered the authentication information.| 1416 1417## FaceTips<sup>8+</sup> 1418 1419Enumerates the tip codes used during the facial authentication process. 1420 1421**System capability**: SystemCapability.UserIAM.UserAuth.Core 1422 1423| Name | Value | Description | 1424| ----------------------------- | ------ | ------------------------------------ | 1425| FACE_AUTH_TIP_TOO_BRIGHT | 1 | The obtained facial image is too bright due to high illumination. | 1426| FACE_AUTH_TIP_TOO_DARK | 2 | The obtained facial image is too dark due to low illumination. | 1427| FACE_AUTH_TIP_TOO_CLOSE | 3 | The face is too close to the device. | 1428| FACE_AUTH_TIP_TOO_FAR | 4 | The face is too far away from the device. | 1429| FACE_AUTH_TIP_TOO_HIGH | 5 | Only the upper part of the face is captured because the device is angled too high. | 1430| FACE_AUTH_TIP_TOO_LOW | 6 | Only the lower part of the face is captured because the device is angled too low. | 1431| FACE_AUTH_TIP_TOO_RIGHT | 7 | Only the right part of the face is captured because the device is deviated to the right. | 1432| FACE_AUTH_TIP_TOO_LEFT | 8 | Only the left part of the face is captured because the device is deviated to the left. | 1433| FACE_AUTH_TIP_TOO_MUCH_MOTION | 9 | The face moves too fast during facial information collection.| 1434| FACE_AUTH_TIP_POOR_GAZE | 10 | The face is not facing the camera. | 1435| FACE_AUTH_TIP_NOT_DETECTED | 11 | No face is detected. | 1436 1437 1438## FingerprintTips<sup>8+</sup> 1439 1440Enumerates the tip codes used during the fingerprint authentication process. 1441 1442**System capability**: SystemCapability.UserIAM.UserAuth.Core 1443 1444| Name | Value | Description | 1445| --------------------------------- | ------ | -------------------------------------------------- | 1446| FINGERPRINT_AUTH_TIP_GOOD | 0 | The obtained fingerprint image is in good condition. | 1447| FINGERPRINT_AUTH_TIP_DIRTY | 1 | Large fingerprint image noise is detected due to suspicious or detected dirt on the sensor.| 1448| FINGERPRINT_AUTH_TIP_INSUFFICIENT | 2 | The noise of the fingerprint image is too large to be processed. | 1449| FINGERPRINT_AUTH_TIP_PARTIAL | 3 | Incomplete fingerprint image is detected. | 1450| FINGERPRINT_AUTH_TIP_TOO_FAST | 4 | The fingerprint image is incomplete due to fast movement. | 1451| FINGERPRINT_AUTH_TIP_TOO_SLOW | 5 | Failed to obtain the fingerprint image because the finger seldom moves. | 1452 1453 1454## UserAuthType<sup>8+</sup> 1455 1456Enumerates the identity authentication types. 1457 1458**System capability**: SystemCapability.UserIAM.UserAuth.Core 1459 1460| Name | Value | Description | 1461| ----------- | ---- | ---------- | 1462| PIN<sup>10+</sup> | 1 | PIN authentication.| 1463| FACE | 2 | Facial authentication.| 1464| FINGERPRINT | 4 | Fingerprint authentication.| 1465 1466## AuthTrustLevel<sup>8+</sup> 1467 1468Enumerates the trust levels of the authentication result. 1469 1470**System capability**: SystemCapability.UserIAM.UserAuth.Core 1471 1472| Name| Value | Description | 1473| ---- | ----- | ------------------------------------------------------------ | 1474| ATL1 | 10000 | Authentication trust level 1. The authentication of this level can identify individual users and provides limited liveness detection capabilities. It is usually used in service risk control and query of general personal data.| 1475| ATL2 | 20000 | Authentication trust level 2. The authentication of this level can accurately identify individual users and provides regular liveness detection capabilities. It is usually used in scenarios such as logins to apps and keeping a device in unlocked state. | 1476| ATL3 | 30000 | Authentication trust level 3. The authentication of this level can accurately identify individual users and provides strong liveness detection capabilities. It is usually used in scenarios such as unlocking a device.| 1477| ATL4 | 40000 | Authentication trust level 4. The authentication of this level can accurately identify individual users and provides powerful liveness detection capabilities. It is usually used in scenarios such as small-amount payment.| 1478 1479## userIAM_userAuth.getAuthenticator<sup>(deprecated)</sup> 1480 1481getAuthenticator(): Authenticator 1482 1483Obtains an **Authenticator** instance for user authentication. 1484 1485> **NOTE**<br> 1486> This API is deprecated since API version 8. Use [constructor](#constructordeprecated) instead. 1487 1488**System capability**: SystemCapability.UserIAM.UserAuth.Core 1489 1490**Return value** 1491 1492| Type | Description | 1493| ----------------------------------------- | ------------ | 1494| [Authenticator](#authenticatordeprecated) | **Authenticator** instance obtained.| 1495 1496**Example** 1497 ```ts 1498 import userIAM_userAuth from '@ohos.userIAM.userAuth'; 1499 1500 let authenticator = userIAM_userAuth.getAuthenticator(); 1501 ``` 1502 1503## Authenticator<sup>(deprecated)</sup> 1504 1505Defines the **Authenticator** object. 1506 1507> **NOTE**<br> 1508> This API is deprecated since API version 8. Use [UserAuth](#userauthdeprecated) instead. 1509 1510### execute<sup>(deprecated)</sup> 1511 1512execute(type: AuthType, level: SecureLevel, callback: AsyncCallback<number>): void 1513 1514Starts user authentication. This API uses an asynchronous callback to return the result. 1515 1516> **NOTE**<br> 1517> This API is deprecated since API version 8. Use [auth](#authdeprecated) instead. 1518 1519**Required permissions**: ohos.permission.ACCESS_BIOMETRIC 1520 1521**System capability**: SystemCapability.UserIAM.UserAuth.Core 1522 1523**Parameters** 1524 1525| Name | Type | Mandatory| Description | 1526| -------- | --------------------------- | ---- |-----------------------------------------------------------------------------------------------------------------------| 1527| type | AuthType | Yes | Authentication type. Currently, only **FACE_ONLY** is supported.<br>**ALL** is reserved and not supported by the current version. | 1528| level | SecureLevel | Yes | Security level of the authentication. It can be **S1** (lowest), **S2**, **S3**, or **S4** (highest).<br>Devices capable of 3D facial recognition support S3 and lower-level authentication.<br>Devices capable of 2D facial recognition support S2 and lower-level authentication.| 1529| callback | AsyncCallback<number> | Yes| Callback invoked to return the result. **number** indicates the [AuthenticationResult](#authenticationresultdeprecated).| 1530 1531**Example** 1532 1533```ts 1534import userIAM_userAuth from '@ohos.userIAM.userAuth'; 1535 1536let authenticator = userIAM_userAuth.getAuthenticator(); 1537authenticator.execute('FACE_ONLY', 'S2', (error, code)=>{ 1538 if (code === userIAM_userAuth.ResultCode.SUCCESS) { 1539 console.info('auth success'); 1540 return; 1541 } 1542 console.error('auth fail, code = ' + code); 1543}); 1544``` 1545 1546 1547### execute<sup>(deprecated)</sup> 1548 1549execute(type : AuthType, level : SecureLevel): Promise<number> 1550 1551Starts user authentication. This API uses a promise to return the result. 1552 1553> **NOTE**<br> 1554> This API is deprecated since API version 8. Use [auth](#authdeprecated) instead. 1555 1556**Required permissions**: ohos.permission.ACCESS_BIOMETRIC 1557 1558**System capability**: SystemCapability.UserIAM.UserAuth.Core 1559 1560**Parameters** 1561 1562| Name| Type | Mandatory| Description | 1563| ------ | ------ | ---- |-----------------------------------------------------------------------------------------------------------------------| 1564| type | AuthType | Yes | Authentication type. Currently, only **FACE_ONLY** is supported.<br>**ALL** is reserved and not supported by the current version. | 1565| level | SecureLevel | Yes | Security level of the authentication. It can be **S1** (lowest), **S2**, **S3**, or **S4** (highest).<br>Devices capable of 3D facial recognition support S3 and lower-level authentication.<br>Devices capable of 2D facial recognition support S2 and lower-level authentication.| 1566 1567**Return value** 1568 1569| Type | Description | 1570| --------------------- | ------------------------------------------------------------ | 1571| Promise<number> | Promise used to return the authentication result, which is a number. For details, see [AuthenticationResult](#authenticationresultdeprecated).| 1572 1573**Example** 1574 1575```ts 1576import userIAM_userAuth from '@ohos.userIAM.userAuth'; 1577 1578try { 1579 let authenticator = userIAM_userAuth.getAuthenticator(); 1580 authenticator.execute('FACE_ONLY', 'S2').then((code)=>{ 1581 console.info('auth success'); 1582 }) 1583} catch (error) { 1584 console.error('auth fail, code = ' + error); 1585} 1586``` 1587 1588## AuthenticationResult<sup>(deprecated)</sup> 1589 1590Enumerates the authentication results. 1591 1592> **NOTE**<br> 1593> This object is deprecated since API version 8. Use [ResultCode](#resultcodedeprecated) instead. 1594 1595**System capability**: SystemCapability.UserIAM.UserAuth.Core 1596 1597| Name | Value | Description | 1598| ------------------ | ------ | -------------------------- | 1599| NO_SUPPORT | -1 | The device does not support the current authentication mode.| 1600| SUCCESS | 0 | The authentication is successful. | 1601| COMPARE_FAILURE | 1 | The feature comparison failed. | 1602| CANCELED | 2 | The authentication was canceled by the user. | 1603| TIMEOUT | 3 | The authentication has timed out. | 1604| CAMERA_FAIL | 4 | The camera failed to start. | 1605| BUSY | 5 | The authentication service is not available. Try again later. | 1606| INVALID_PARAMETERS | 6 | The authentication parameters are invalid. | 1607| LOCKED | 7 | The user account is locked because the number of authentication failures has reached the threshold.| 1608| NOT_ENROLLED | 8 | No authentication credential is registered. | 1609| GENERAL_ERROR | 100 | Other errors. | 1610