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