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