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```js 13import userIAM_userAuth from '@ohos.userIAM.userAuth'; 14``` 15 16## AuthResultInfo<sup>9+</sup> 17 18Defines the authentication result. 19 20**System capability**: SystemCapability.UserIAM.UserAuth.Core 21 22| Name | Type | Mandatory| Description | 23| ------------ | ---------- | ---- | -------------------- | 24| result | number | Yes | Authentication result. | 25| token | Uint8Array | No | Token that has passed the user identity authentication.| 26| remainAttempts | number | No | Number of remaining authentication attempts.| 27| lockoutDuration | number | No | Lock duration of the authentication operation, in milliseconds.| 28 29## TipInfo<sup>9+</sup> 30 31Defines the authentication tip information. 32 33**System capability**: SystemCapability.UserIAM.UserAuth.Core 34 35| Name | Type | Mandatory| Description | 36| ------------ | ---------- | ---- | -------------------- | 37| module | number | Yes | ID of the module that sends the tip information. | 38| tip | number | Yes | Tip to be given during the authentication process. | 39 40## EventInfo<sup>9+</sup> 41 42Enumerates the authentication event information types. 43 44**System capability**: SystemCapability.UserIAM.UserAuth.Core 45 46| Value | Description | 47| --------- | ----------------------- | 48| [AuthResultInfo](#authresultinfo9) | Authentication result. | 49| [TipInfo](#tipinfo9) | Authentication tip information. | 50 51## AuthEventKey<sup>9+</sup> 52 53Defines the keyword of the authentication event type. It is used as a parameter of [on](#on9). 54 55| Value | Description | 56| ---------- | ----------------------- | 57| "result" | If the first parameter of [on](#on9) is **result**, the [callback](#callback9) returns the authentication result.| 58| "tip" | If the first parameter of [on](#on9) is **tip**, the [callback](#callback9) returns the authentication tip information.| 59 60## AuthEvent<sup>9+</sup> 61 62Provides an asynchronous callback to return the authentication event information. 63 64### callback<sup>9+</sup> 65 66callback(result : EventInfo) : void 67 68Called to return the authentication result or authentication tip information. 69 70**System capability**: SystemCapability.UserIAM.UserAuth.Core 71 72**Parameters** 73 74| Name | Type | Mandatory| Description | 75| --------- | -------------------------- | ---- | ------------------------------ | 76| result | [EventInfo](#eventinfo9) | Yes | Authentication result or tip information. | 77 78**Example** 79 80```js 81import userIAM_userAuth from '@ohos.userIAM.userAuth'; 82 83let challenge = new Uint8Array([1, 2, 3, 4, 5, 6, 7, 8]); 84let authType = userIAM_userAuth.UserAuthType.FACE; 85let authTrustLevel = userIAM_userAuth.AuthTrustLevel.ATL1; 86// Obtain the authentication result through a callback. 87try { 88 let auth = userIAM_userAuth.getAuthInstance(challenge, authType, authTrustLevel); 89 auth.on("result", { 90 callback: (result: userIAM_userAuth.AuthResultInfo) => { 91 console.log("authV9 result " + result.result); 92 console.log("authV9 token " + result.token); 93 console.log("authV9 remainAttempts " + result.remainAttempts); 94 console.log("authV9 lockoutDuration " + result.lockoutDuration); 95 } 96 }); 97 auth.start(); 98 console.log("authV9 start success"); 99} catch (error) { 100 console.log("authV9 error = " + error); 101 // do error 102} 103// Obtain the authentication tip information through a callback. 104try { 105 let auth = userIAM_userAuth.getAuthInstance(challenge, authType, authTrustLevel); 106 auth.on("tip", { 107 callback : (result : userIAM_userAuth.TipInfo) => { 108 switch (result.tip) { 109 case userIAM_userAuth.FaceTips.FACE_AUTH_TIP_TOO_BRIGHT: 110 // Do something; 111 case userIAM_userAuth.FaceTips.FACE_AUTH_TIP_TOO_DARK: 112 // Do something. 113 default: 114 // Do others. 115 } 116 } 117 }); 118 auth.start(); 119 console.log("authV9 start success"); 120} catch (error) { 121 console.log("authV9 error = " + error); 122 // do error 123} 124``` 125 126## AuthInstance<sup>9+</sup> 127 128Implements user authentication. 129 130### on<sup>9+</sup> 131 132on : (name : AuthEventKey, callback : AuthEvent) => void 133 134Subscribes to the user authentication events of the specified type. 135 136> **NOTE**<br> 137> Use the [AuthInstance](#authinstance9) instance obtained to invoke this API to subscribe to events. 138 139**System capability**: SystemCapability.UserIAM.UserAuth.Core 140 141**Parameters** 142 143| Name | Type | Mandatory| Description | 144| --------- | -------------------------- | ---- | ------------------------- | 145| 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.| 146| callback | [AuthEvent](#authevent9) | Yes | Callback invoked to return the authentication result or tip information.| 147 148For details about the error codes, see [User Authentication Error Codes](../errorcodes/errorcode-useriam.md). 149 150**Error codes** 151 152| ID| Error Message| 153| -------- | ------- | 154| 401 | Incorrect parameters. | 155| 12500002 | General operation error. | 156 157**Example** 158 159```js 160import userIAM_userAuth from '@ohos.userIAM.userAuth'; 161 162let challenge = new Uint8Array([1, 2, 3, 4, 5, 6, 7, 8]); 163let authType = userIAM_userAuth.UserAuthType.FACE; 164let authTrustLevel = userIAM_userAuth.AuthTrustLevel.ATL1; 165try { 166 let auth = userIAM_userAuth.getAuthInstance(challenge, authType, authTrustLevel); 167 // Subscribe to the authentication result. 168 auth.on("result", { 169 callback: (result: userIAM_userAuth.AuthResultInfo) => { 170 console.log("authV9 result " + result.result); 171 console.log("authV9 token " + result.token); 172 console.log("authV9 remainAttempts " + result.remainAttempts); 173 console.log("authV9 lockoutDuration " + result.lockoutDuration); 174 } 175 }); 176 // Subscribe to authentication tip information. 177 auth.on("tip", { 178 callback : (result : userIAM_userAuth.TipInfo) => { 179 switch (result.tip) { 180 case userIAM_userAuth.FaceTips.FACE_AUTH_TIP_TOO_BRIGHT: 181 // Do something; 182 case userIAM_userAuth.FaceTips.FACE_AUTH_TIP_TOO_DARK: 183 // Do something. 184 default: 185 // Do others. 186 } 187 } 188 }); 189 auth.start(); 190 console.log("authV9 start success"); 191} catch (error) { 192 console.log("authV9 error = " + error); 193 // do error 194} 195``` 196 197### off<sup>9+</sup> 198 199off : (name : AuthEventKey) => void 200 201Unsubscribes from the user authentication events of the specific type. 202 203> **NOTE**<br> 204> Use the [AuthInstance](#authinstance9) instance obtained to invoke this API to unsubscribe from events. 205 206**System capability**: SystemCapability.UserIAM.UserAuth.Core 207 208| Name | Type | Mandatory| Description | 209| --------- | -------------------------- | ---- | ------------------------- | 210| 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.| 211 212For details about the error codes, see [User Authentication Error Codes](../errorcodes/errorcode-useriam.md). 213 214**Error codes** 215 216| ID| Error Message| 217| -------- | ------- | 218| 401 | Incorrect parameters. | 219| 12500002 | General operation error. | 220 221**Example** 222 223```js 224import userIAM_userAuth from '@ohos.userIAM.userAuth'; 225 226let challenge = new Uint8Array([1, 2, 3, 4, 5, 6, 7, 8]); 227let authType = userIAM_userAuth.UserAuthType.FACE; 228let authTrustLevel = userIAM_userAuth.AuthTrustLevel.ATL1; 229let auth; 230try { 231 auth = userIAM_userAuth.getAuthInstance(challenge, authType, authTrustLevel); 232 console.log("get auth instance success"); 233} catch (error) { 234 console.log("get auth instance failed" + error); 235} 236 237try { 238 // Subscribe to the authentication result. 239 auth.on("result", { 240 callback: (result: userIAM_userAuth.AuthResultInfo) => { 241 console.log("authV9 result " + result.result); 242 console.log("authV9 token " + result.token); 243 console.log("authV9 remainAttempts " + result.remainAttempts); 244 console.log("authV9 lockoutDuration " + result.lockoutDuration); 245 } 246 }); 247 console.log("subscribe authentication event success"); 248} catch (error) { 249 console.log("subscribe authentication event failed " + error); 250} 251// Unsubscribe from the authentication result. 252try { 253 auth.off("result"); 254 console.info("cancel subscribe authentication event success"); 255} catch (error) { 256 console.info("cancel subscribe authentication event failed, error = " + error); 257} 258``` 259 260### start<sup>9+</sup> 261 262start : () => void 263 264Starts authentication. 265 266> **NOTE**<br> 267> Use the [AuthInstance](#authinstance9) instance obtained to invoke this API. 268 269**Required permissions**: ohos.permission.ACCESS_BIOMETRIC 270 271**System capability**: SystemCapability.UserIAM.UserAuth.Core 272 273For details about the error codes, see [User Authentication Error Codes](../errorcodes/errorcode-useriam.md). 274 275**Error codes** 276 277| ID| Error Message| 278| -------- | ------- | 279| 201 | Permission verification failed. | 280| 401 | Incorrect parameters. | 281| 12500001 | Authentication failed. | 282| 12500002 | General operation error. | 283| 12500003 | The operation is canceled. | 284| 12500004 | The operation is time-out. | 285| 12500005 | The authentication type is not supported. | 286| 12500006 | The authentication trust level is not supported. | 287| 12500007 | The authentication task is busy. | 288| 12500009 | The authenticator is locked. | 289| 12500010 | The type of credential has not been enrolled. | 290 291**Example** 292 293```js 294import userIAM_userAuth from '@ohos.userIAM.userAuth'; 295 296let challenge = new Uint8Array([1, 2, 3, 4, 5, 6, 7, 8]); 297let authType = userIAM_userAuth.UserAuthType.FACE; 298let authTrustLevel = userIAM_userAuth.AuthTrustLevel.ATL1; 299 300try { 301 let auth = userIAM_userAuth.getAuthInstance(challenge, authType, authTrustLevel); 302 auth.start(); 303 console.info("authV9 start auth success"); 304} catch (error) { 305 console.info("authV9 start auth failed, error = " + error); 306} 307``` 308 309### cancel<sup>9+</sup> 310 311cancel : () => void 312 313Cancels this authentication. 314 315> **NOTE**<br> 316> Use the [AuthInstance](#authinstance9) instance obtained to invoke this API. The [AuthInstance](#authinstance9) instance must be the one being authenticated. 317 318**Required permissions**: ohos.permission.ACCESS_BIOMETRIC 319 320**System capability**: SystemCapability.UserIAM.UserAuth.Core 321 322For details about the error codes, see [User Authentication Error Codes](../errorcodes/errorcode-useriam.md). 323 324**Error codes** 325 326| ID| Error Message| 327| -------- | ------- | 328| 201 | Permission verification failed. | 329| 401 | Incorrect parameters. | 330| 12500002 | General operation error. | 331 332**Example** 333 334```js 335import userIAM_userAuth from '@ohos.userIAM.userAuth'; 336 337let challenge = new Uint8Array([1, 2, 3, 4, 5, 6, 7, 8]); 338let authType = userIAM_userAuth.UserAuthType.FACE; 339let authTrustLevel = userIAM_userAuth.AuthTrustLevel.ATL1; 340 341try { 342 let auth = userIAM_userAuth.getAuthInstance(challenge, authType, authTrustLevel); 343 auth.cancel(); 344 console.info("cancel auth success"); 345} catch (error) { 346 console.info("cancel auth failed, error = " + error); 347} 348``` 349 350## userIAM_userAuth.getAuthInstance<sup>9+</sup> 351 352getAuthInstance(challenge : Uint8Array, authType : UserAuthType, authTrustLevel : AuthTrustLevel): AuthInstance 353 354Obtains an **AuthInstance** instance for user authentication. 355 356> **NOTE**<br> 357> An **AuthInstance** instance can be used for an authentication only once. 358 359**System capability**: SystemCapability.UserIAM.UserAuth.Core 360 361**Parameters** 362 363| Name | Type | Mandatory| Description | 364| -------------- | ---------------------------------------- | ---- | ------------------------ | 365| challenge | Uint8Array | Yes | Challenge value. The maximum length is 32 bytes. The value can be **null**. | 366| authType | [UserAuthType](#userauthtype8) | Yes | Authentication type. Only **FACE** is supported.| 367| authTrustLevel | [AuthTrustLevel](#authtrustlevel8) | Yes | Authentication trust level. | 368 369**Return value** 370 371| Type | Description | 372| ----------------------------------------- | ------------ | 373| [AuthInstance](#authinstance9) | **Authenticator** instance obtained.| 374 375For details about the error codes, see [User Authentication Error Codes](../errorcodes/errorcode-useriam.md). 376 377**Error codes** 378 379| ID| Error Message| 380| -------- | ------- | 381| 401 | Incorrect parameters. | 382| 12500002 | General operation error. | 383| 12500005 | The authentication type is not supported. | 384| 12500006 | The authentication trust level is not supported. | 385 386**Example** 387 388```js 389import userIAM_userAuth from '@ohos.userIAM.userAuth'; 390 391let challenge = new Uint8Array([1, 2, 3, 4, 5, 6, 7, 8]); 392let authType = userIAM_userAuth.UserAuthType.FACE; 393let authTrustLevel = userIAM_userAuth.AuthTrustLevel.ATL1; 394 395try { 396 let auth = userIAM_userAuth.getAuthInstance(challenge, authType, authTrustLevel); 397 console.info("get auth instance success"); 398} catch (error) { 399 console.info("get auth instance success failed, error = " + error); 400} 401``` 402 403## userIAM_userAuth.getAvailableStatus<sup>9+</sup> 404 405getAvailableStatus(authType : UserAuthType, authTrustLevel : AuthTrustLevel): void 406 407Checks whether the specified authentication capability is supported. 408 409**Required permissions**: ohos.permission.ACCESS_BIOMETRIC 410 411**System capability**: SystemCapability.UserIAM.UserAuth.Core 412 413**Parameters** 414 415| Name | Type | Mandatory| Description | 416| -------------- | ---------------------------------- | ---- | -------------------------- | 417| authType | [UserAuthType](#userauthtype8) | Yes | Authentication type. Only **FACE** is supported.| 418| authTrustLevel | [AuthTrustLevel](#authtrustlevel8) | Yes | Authentication trust level. | 419 420For details about the error codes, see [User Authentication Error Codes](../errorcodes/errorcode-useriam.md). 421 422**Error codes** 423 424| ID| Error Message| 425| -------- | ------- | 426| 201 | Permission verification failed. | 427| 401 | Incorrect parameters. | 428| 12500002 | General operation error. | 429| 12500005 | The authentication type is not supported. | 430| 12500006 | The authentication trust level is not supported. | 431| 12500010 | The type of credential has not been enrolled. | 432 433**Example** 434 435```js 436import userIAM_userAuth from '@ohos.userIAM.userAuth'; 437 438try { 439 userIAM_userAuth.getAvailableStatus(userIAM_userAuth.UserAuthType.FACE, userIAM_userAuth.AuthTrustLevel.ATL1); 440 console.info("current auth trust level is supported"); 441} catch (error) { 442 console.info("current auth trust level is not supported, error = " + error); 443} 444``` 445 446## UserAuthResultCode<sup>9+</sup> 447 448Enumerates the authentication result codes. 449 450**System capability**: SystemCapability.UserIAM.UserAuth.Core 451 452| Name | Value | Description | 453| ----------------------- | ------ | -------------------- | 454| SUCCESS | 12500000 | The authentication is successful. | 455| FAIL | 12500001 | The authentication failed. | 456| GENERAL_ERROR | 12500002 | A general operation error occurred. | 457| CANCELED | 12500003 | The authentication is canceled. | 458| TIMEOUT | 12500004 | The authentication timed out. | 459| TYPE_NOT_SUPPORT | 12500005 | The authentication type is not supported. | 460| TRUST_LEVEL_NOT_SUPPORT | 12500006 | The authentication trust level is not supported. | 461| BUSY | 12500007 | Indicates the busy state. | 462| LOCKED | 12500009 | The authentication executor is locked. | 463| NOT_ENROLLED | 12500010 | The user has not entered the authentication information.| 464 465## UserAuth<sup>8+</sup> 466 467Provides APIs to manage an **Authenticator** object. 468 469### constructor<sup>(deprecated)</sup> 470 471constructor() 472 473A constructor used to create an authenticator instance. 474 475> **NOTE**<br> 476> This API is supported since API version 8 and deprecated since API version 9. You are advised to use [getAuthInstance](#useriam_userauthgetauthinstance9). 477 478**System capability**: SystemCapability.UserIAM.UserAuth.Core 479 480**Return value** 481 482| Type | Description | 483| ---------------------- | -------------------- | 484| [UserAuth](#userauth8) | **Authenticator** instance obtained.| 485 486**Example** 487 488```js 489import userIAM_userAuth from '@ohos.userIAM.userAuth'; 490 491let auth = new userIAM_userAuth.UserAuth(); 492``` 493 494### getVersion<sup>(deprecated)</sup> 495 496getVersion() : number 497 498Obtains the version of this authenticator. 499 500> **NOTE**<br> 501> This API is supported since API version 8 and deprecated since API version 9. 502 503**Required permissions**: ohos.permission.ACCESS_BIOMETRIC 504 505**System capability**: SystemCapability.UserIAM.UserAuth.Core 506 507**Return value** 508 509| Type | Description | 510| ------ | ---------------------- | 511| number | Authenticator version obtained.| 512 513**Example** 514 515```js 516import userIAM_userAuth from '@ohos.userIAM.userAuth'; 517 518let auth = new userIAM_userAuth.UserAuth(); 519let version = auth.getVersion(); 520console.info("auth version = " + version); 521``` 522 523### getAvailableStatus<sup>(deprecated)</sup> 524 525getAvailableStatus(authType : UserAuthType, authTrustLevel : AuthTrustLevel) : number 526 527Checks whether the specified authentication capability is supported. 528 529> **NOTE**<br> 530> This API is supported since API version 8 and deprecated since API version 9. You are advised to use [getAvailableStatus](#useriam_userauthgetavailablestatus9). 531 532**Required permissions**: ohos.permission.ACCESS_BIOMETRIC 533 534**System capability**: SystemCapability.UserIAM.UserAuth.Core 535 536**Parameters** 537 538| Name | Type | Mandatory| Description | 539| -------------- | ---------------------------------- | ---- | -------------------------- | 540| authType | [UserAuthType](#userauthtype8) | Yes | Authentication type. Only **FACE** is supported.| 541| authTrustLevel | [AuthTrustLevel](#authtrustlevel8) | Yes | Authentication trust level. | 542 543**Return value** 544 545| Type | Description | 546| ------ | ------------------------------------------------------------ | 547| number | Query result. If the authentication capability is supported, **SUCCESS** is returned. Otherwise, a [ResultCode](#resultcodedeprecated) is returned.| 548 549**Example** 550 551```js 552import userIAM_userAuth from '@ohos.userIAM.userAuth'; 553 554let auth = new userIAM_userAuth.UserAuth(); 555let checkCode = auth.getAvailableStatus(userIAM_userAuth.UserAuthType.FACE, userIAM_userAuth.AuthTrustLevel.ATL1); 556if (checkCode == userIAM_userAuth.ResultCode.SUCCESS) { 557 console.info("check auth support success"); 558} else { 559 console.error("check auth support fail, code = " + checkCode); 560} 561``` 562 563### auth<sup>(deprecated)</sup> 564 565auth(challenge: Uint8Array, authType: UserAuthType, authTrustLevel: AuthTrustLevel, callback: IUserAuthCallback): Uint8Array 566 567Performs user authentication. This API uses a callback to return the result. 568 569> **NOTE**<br> 570> This API is supported since API version 8 and deprecated since API version 9. You are advised to use [start](#start9). 571 572**Required permissions**: ohos.permission.ACCESS_BIOMETRIC 573 574**System capability**: SystemCapability.UserIAM.UserAuth.Core 575 576**Parameters** 577 578| Name | Type | Mandatory| Description | 579| -------------- | ---------------------------------------- | ---- | ------------------------ | 580| challenge | Uint8Array | Yes | Challenge value, which can be null. | 581| authType | [UserAuthType](#userauthtype8) | Yes | Authentication type. Only **FACE** is supported.| 582| authTrustLevel | [AuthTrustLevel](#authtrustlevel8) | Yes | Authentication trust level. | 583| callback | [IUserAuthCallback](#iuserauthcallbackdeprecated) | Yes | Callback used to return the result. | 584 585**Return value** 586 587| Type | Description | 588| ---------- | ------------------------------------------------------------ | 589| Uint8Array | Context ID, which is used as the input parameter of [cancelAuth](#cancelauthdeprecated).| 590 591**Example** 592 593```js 594import userIAM_userAuth from '@ohos.userIAM.userAuth'; 595 596let auth = new userIAM_userAuth.UserAuth(); 597auth.auth(null, userIAM_userAuth.UserAuthType.FACE, userIAM_userAuth.AuthTrustLevel.ATL1, { 598 onResult: (result, extraInfo) => { 599 try { 600 console.info("auth onResult result = " + result); 601 console.info("auth onResult extraInfo = " + JSON.stringify(extraInfo)); 602 if (result == userIAM_userAuth.ResultCode.SUCCESS) { 603 // Add the logic to be executed when the authentication is successful. 604 } else { 605 // Add the logic to be executed when the authentication fails. 606 } 607 } catch (e) { 608 console.info("auth onResult error = " + e); 609 } 610 } 611}); 612``` 613 614### cancelAuth<sup>(deprecated)</sup> 615 616cancelAuth(contextID : Uint8Array) : number 617 618Cancels an authentication based on the context ID. 619 620> **NOTE**<br> 621> This API is supported since API version 8 and deprecated since API version 9. You are advised to use [cancel](#cancel9). 622 623**Required permissions**: ohos.permission.ACCESS_BIOMETRIC 624 625**System capability**: SystemCapability.UserIAM.UserAuth.Core 626 627**Parameters** 628 629| Name | Type | Mandatory| Description | 630| --------- | ---------- | ---- | ------------------------------------------ | 631| contextID | Uint8Array | Yes | Context ID, which is obtained by [auth](#authdeprecated).| 632 633**Return value** 634 635| Type | Description | 636| ------ | ------------------------ | 637| number | Returns **SUCCESS** if the cancellation is successful. Returns a [ResultCode](#resultcodedeprecated) otherwise.| 638 639**Example** 640 641```js 642import userIAM_userAuth from '@ohos.userIAM.userAuth'; 643 644// contextId can be obtained by auth(). In this example, it is defined here. 645let contextId = new Uint8Array([0, 1, 2, 3, 4, 5, 6, 7]); 646let auth = new userIAM_userAuth.UserAuth(); 647let cancelCode = auth.cancelAuth(contextId); 648if (cancelCode == userIAM_userAuth.ResultCode.SUCCESS) { 649 console.info("cancel auth success"); 650} else { 651 console.error("cancel auth fail"); 652} 653``` 654 655## IUserAuthCallback<sup>(deprecated)</sup> 656 657Provides callbacks to return the authentication result. 658 659> **NOTE**<br> 660> This object is supported since API version 8 and deprecated since API version 9. You are advised to use [AuthEvent](#authevent9). 661 662### onResult<sup>(deprecated)</sup> 663 664onResult: (result : number, extraInfo : AuthResult) => void 665 666Called to return the authentication result. 667 668> **NOTE**<br> 669> This API is supported since API version 8 and deprecated since API version 9. You are advised to use [callback](#callback9). 670 671**System capability**: SystemCapability.UserIAM.UserAuth.Core 672 673**Parameters** 674 675| Name | Type | Mandatory| Description | 676| --------- | -------------------------- | ---- | ------------------------------------------------ | 677| result | number | Yes | Authentication result. For details, see [ResultCode](#resultcodedeprecated).| 678| 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**.| 679 680**Example** 681 682```js 683import userIAM_userAuth from '@ohos.userIAM.userAuth'; 684 685let auth = new userIAM_userAuth.UserAuth(); 686auth.auth(null, userIAM_userAuth.UserAuthType.FACE, userIAM_userAuth.AuthTrustLevel.ATL1, { 687 onResult: (result, extraInfo) => { 688 try { 689 console.info("auth onResult result = " + result); 690 console.info("auth onResult extraInfo = " + JSON.stringify(extraInfo)); 691 if (result == userIAM_userAuth.ResultCode.SUCCESS) { 692 // Add the logic to be executed when the authentication is successful. 693 } else { 694 // Add the logic to be executed when the authentication fails. 695 } 696 } catch (e) { 697 console.info("auth onResult error = " + e); 698 } 699 } 700}); 701``` 702 703### onAcquireInfo<sup>(deprecated)</sup> 704 705onAcquireInfo ?: (module : number, acquire : number, extraInfo : any) => void 706 707Called to acquire authentication tip information. This API is optional. 708 709> **NOTE**<br> 710> This API is supported since API version 8 and deprecated since API version 9. You are advised to use [callback](#callback9). 711 712**System capability**: SystemCapability.UserIAM.UserAuth.Core 713 714**Parameters** 715 716| Name | Type | Mandatory| Description | 717| --------- | ------ | ---- | ------------------------------ | 718| module | number | Yes | ID of the module that sends the tip information. | 719| acquire | number | Yes | Authentication tip information.| 720| extraInfo | any | Yes | Reserved field. | 721 722**Example** 723 724```js 725import userIAM_userAuth from '@ohos.userIAM.userAuth'; 726 727let auth = new userIAM_userAuth.UserAuth(); 728auth.auth(null, userIAM_userAuth.UserAuthType.FACE, userIAM_userAuth.AuthTrustLevel.ATL1, { 729 onAcquireInfo: (module, acquire, extraInfo) => { 730 try { 731 console.info("auth onAcquireInfo module = " + module); 732 console.info("auth onAcquireInfo acquire = " + acquire); 733 console.info("auth onAcquireInfo extraInfo = " + JSON.stringify(extraInfo)); 734 } catch (e) { 735 console.info("auth onAcquireInfo error = " + e); 736 } 737 } 738}); 739``` 740 741## AuthResult<sup>(deprecated)</sup> 742 743Represents the authentication result object. 744 745> **NOTE**<br> 746> This object is supported since API version 8 and deprecated since API version 9. You are advised to use [AuthResultInfo](#authresultinfo9). 747 748**System capability**: SystemCapability.UserIAM.UserAuth.Core 749 750| Name | Type | Mandatory| Description | 751| ------------ | ---------- | ---- | -------------------| 752| token | Uint8Array | No | Authentication token information.| 753| remainTimes | number | No | Number of remaining authentication operations.| 754| freezingTime | number | No | Time for which the authentication operation is frozen.| 755 756## ResultCode<sup>(deprecated)</sup> 757 758Enumerates the authentication result codes. 759 760> **NOTE**<br> 761> This object is deprecated since API version 9. You are advised to use [UserAuthResultCode](#userauthresultcode9). 762 763**System capability**: SystemCapability.UserIAM.UserAuth.Core 764 765| Name | Value| Description | 766| ----------------------- | ------ | -------------------- | 767| SUCCESS | 0 | The operation is successful. | 768| FAIL | 1 | The authentication failed. | 769| GENERAL_ERROR | 2 | A general operation error occurred. | 770| CANCELED | 3 | The authentication is canceled. | 771| TIMEOUT | 4 | The authentication timed out. | 772| TYPE_NOT_SUPPORT | 5 | The authentication type is not supported. | 773| TRUST_LEVEL_NOT_SUPPORT | 6 | The authentication trust level is not supported. | 774| BUSY | 7 | Indicates the busy state. | 775| INVALID_PARAMETERS | 8 | Invalid parameters are detected. | 776| LOCKED | 9 | The authentication executor is locked. | 777| NOT_ENROLLED | 10 | The user has not entered the authentication information.| 778 779## FaceTips<sup>8+</sup> 780 781Enumerates the tip codes used during the facial authentication process. 782 783**System capability**: SystemCapability.UserIAM.UserAuth.Core 784 785| Name | Value | Description | 786| ----------------------------- | ------ | ------------------------------------ | 787| FACE_AUTH_TIP_TOO_BRIGHT | 1 | The obtained facial image is too bright due to high illumination. | 788| FACE_AUTH_TIP_TOO_DARK | 2 | The obtained facial image is too dark due to low illumination. | 789| FACE_AUTH_TIP_TOO_CLOSE | 3 | The face is too close to the device. | 790| FACE_AUTH_TIP_TOO_FAR | 4 | The face is too far away from the device. | 791| FACE_AUTH_TIP_TOO_HIGH | 5 | Only the upper part of the face is captured because the device is angled too high. | 792| FACE_AUTH_TIP_TOO_LOW | 6 | Only the lower part of the face is captured because the device is angled too low. | 793| FACE_AUTH_TIP_TOO_RIGHT | 7 | Only the right part of the face is captured because the device is deviated to the right. | 794| FACE_AUTH_TIP_TOO_LEFT | 8 | Only the left part of the face is captured because the device is deviated to the left. | 795| FACE_AUTH_TIP_TOO_MUCH_MOTION | 9 | The face moves too fast during facial information collection.| 796| FACE_AUTH_TIP_POOR_GAZE | 10 | The face is not facing the camera. | 797| FACE_AUTH_TIP_NOT_DETECTED | 11 | No face is detected. | 798 799 800## FingerprintTips<sup>8+</sup> 801 802Enumerates the tip codes used during the fingerprint authentication process. 803 804**System capability**: SystemCapability.UserIAM.UserAuth.Core 805 806| Name | Value | Description | 807| --------------------------------- | ------ | -------------------------------------------------- | 808| FINGERPRINT_AUTH_TIP_GOOD | 0 | The obtained fingerprint image is in good condition. | 809| FINGERPRINT_AUTH_TIP_DIRTY | 1 | Large fingerprint image noise is detected due to suspicious or detected dirt on the sensor.| 810| FINGERPRINT_AUTH_TIP_INSUFFICIENT | 2 | The noise of the fingerprint image is too large to be processed. | 811| FINGERPRINT_AUTH_TIP_PARTIAL | 3 | Incomplete fingerprint image is detected. | 812| FINGERPRINT_AUTH_TIP_TOO_FAST | 4 | The fingerprint image is incomplete due to fast movement. | 813| FINGERPRINT_AUTH_TIP_TOO_SLOW | 5 | Failed to obtain the fingerprint image because the finger seldom moves. | 814 815 816## UserAuthType<sup>8+</sup> 817 818Enumerates the identity authentication types. 819 820**System capability**: SystemCapability.UserIAM.UserAuth.Core 821 822| Name | Value | Description | 823| ----------- | ------ | ---------- | 824| FACE | 2 | Facial authentication.| 825| FINGERPRINT | 4 | Fingerprint authentication.| 826 827## AuthTrustLevel<sup>8+</sup> 828 829Enumerates the trust levels of the authentication result. 830 831**System capability**: SystemCapability.UserIAM.UserAuth.Core 832 833| Name| Value | Description | 834| ---- | ------ | ------------------------- | 835| ATL1 | 10000 | Trust level 1.| 836| ATL2 | 20000 | Trust level 2.| 837| ATL3 | 30000 | Trust level 3.| 838| ATL4 | 40000 | Trust level 4.| 839 840## userIAM_userAuth.getAuthenticator<sup>(deprecated)</sup> 841 842getAuthenticator(): Authenticator 843 844Obtains an **Authenticator** instance for user authentication. 845 846> **NOTE**<br> 847> This API is deprecated since API version 8. You are advised to use [constructor](#constructordeprecated). 848 849**System capability**: SystemCapability.UserIAM.UserAuth.Core 850 851**Return value** 852 853| Type | Description | 854| ----------------------------------------- | ------------ | 855| [Authenticator](#authenticatordeprecated) | **Authenticator** instance obtained.| 856 857**Example** 858 ```js 859 let authenticator = userIAM_userAuth.getAuthenticator(); 860 ``` 861 862## Authenticator<sup>(deprecated)</sup> 863 864Defines the **Authenticator** object. 865 866> **NOTE**<br> 867> This object is deprecated since API version 8. You are advised to use [UserAuth](#userauth8). 868 869### execute<sup>(deprecated)</sup> 870 871execute(type: AuthType, level: SecureLevel, callback: AsyncCallback<number>): void 872 873Performs user authentication. This API uses asynchronous callback to return the result. 874 875> **NOTE**<br> 876> This API is deprecated since API version 8. You are advised to use [auth](#authdeprecated). 877 878**Required permissions**: ohos.permission.ACCESS_BIOMETRIC 879 880**System capability**: SystemCapability.UserIAM.UserAuth.Core 881 882**Parameters** 883 884| Name | Type | Mandatory| Description | 885| -------- | --------------------------- | ---- | -------------------------- | 886| type | AuthType | Yes | Authentication type. Only **FACE_ONLY** is supported.<br>**ALL** is reserved and not supported by the current version.| 887| 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.| 888| callback | AsyncCallback<number> | Yes | Callback used to return the result. | 889 890Parameters returned in callback 891 892| Type | Description | 893| ------ | ------------------------------------------------------------ | 894| number | Authentication result. For details, see [AuthenticationResult](#authenticationresultdeprecated).| 895 896**Example** 897 898```js 899let authenticator = userIAM_userAuth.getAuthenticator(); 900authenticator.execute("FACE_ONLY", "S2", (error, code)=>{ 901 if (code === userIAM_userAuth.ResultCode.SUCCESS) { 902 console.info("auth success"); 903 return; 904 } 905 console.error("auth fail, code = " + code); 906}); 907``` 908 909 910### execute<sup>(deprecated)</sup> 911 912execute(type : AuthType, level : SecureLevel): Promise<number> 913 914Performs user authentication. This API uses a promise to return the result. 915 916> **NOTE**<br> 917> This API is deprecated since API version 8. You are advised to use [auth](#authdeprecated). 918 919**Required permissions**: ohos.permission.ACCESS_BIOMETRIC 920 921**System capability**: SystemCapability.UserIAM.UserAuth.Core 922 923**Parameters** 924 925| Name| Type | Mandatory| Description | 926| ------ | ------ | ---- | ------------------------------------------------------------ | 927| type | AuthType | Yes | Authentication type. Only **FACE_ONLY** is supported.<br>**ALL** is reserved and not supported by the current version.| 928| 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.| 929 930**Return value** 931 932| Type | Description | 933| --------------------- | ------------------------------------------------------------ | 934| Promise<number> | Promise used to return the authentication result, which is a number. For details, see [AuthenticationResult](#authenticationresultdeprecated).| 935 936**Example** 937 938```js 939let authenticator = userIAM_userAuth.getAuthenticator(); 940authenticator.execute("FACE_ONLY", "S2").then((code)=>{ 941 console.info("auth success"); 942}).catch((error)=>{ 943 console.error("auth fail, code = " + error); 944}); 945``` 946 947## AuthenticationResult<sup>(deprecated)</sup> 948 949Enumerates the authentication results. 950 951> **NOTE**<br> 952> This object is discarded since API version 8. You are advised to use [ResultCode](#resultcodedeprecated). 953 954**System capability**: SystemCapability.UserIAM.UserAuth.Core 955 956| Name | Value | Description | 957| ------------------ | ------ | -------------------------- | 958| NO_SUPPORT | -1 | The device does not support the current authentication mode.| 959| SUCCESS | 0 | The authentication is successful. | 960| COMPARE_FAILURE | 1 | The feature comparison failed. | 961| CANCELED | 2 | The authentication was canceled by the user. | 962| TIMEOUT | 3 | The authentication has timed out. | 963| CAMERA_FAIL | 4 | The camera failed to start. | 964| BUSY | 5 | The authentication service is not available. Try again later. | 965| INVALID_PARAMETERS | 6 | The authentication parameters are invalid. | 966| LOCKED | 7 | The user account is locked because the number of authentication failures has reached the threshold.| 967| NOT_ENROLLED | 8 | No authentication credential is registered. | 968| GENERAL_ERROR | 100 | Other errors. | 969