1# @ohos.userIAM.userAuth (User Authentication) 2 3<!--Kit: User Authentication Kit--> 4<!--Subsystem: UserIAM--> 5<!--Owner: @WALL_EYE--> 6<!--SE: @lichangting518--> 7<!--TSE: @jane_lz--> 8 9The **userAuth** module provides APIs for user authentication, which applies to scenarios such as device unlocking, payment, and application login. 10 11> **NOTE**<br> 12> 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. 13 14 15## Modules to Import 16 17```ts 18import { userAuth } from '@kit.UserAuthenticationKit'; 19``` 20 21## Constant 22 23| Name | Value | Description | 24| ----------- | ---- | ---------- | 25| MAX_ALLOWABLE_REUSE_DURATION<sup>12+</sup> | 300000 | Maximum reuse duration of the unlock authentication result, in milliseconds. The value is **300000**.<br> **System capability**: SystemCapability.UserIAM.UserAuth.Core<br> **Atomic service API**: This API can be used in atomic services since API version 12.| 26 27## UserAuthTipCode<sup>20+</sup> 28 29Enumerates the intermediate authentication status. 30 31**Atomic service API**: This API can be used in atomic services since API version 20. 32 33**System capability**: SystemCapability.UserIAM.UserAuth.Core 34 35| Name | Value | Description | 36| ----------- | ---- | ---------- | 37| COMPARE_FAILURE | 1 | The authentication failed.| 38| TIMEOUT | 2 | The authentication has timed out.| 39| TEMPORARILY_LOCKED | 3 | The authentication is temporarily locked.| 40| PERMANENTLY_LOCKED | 4 | The authentication is permanently locked.| 41| WIDGET_LOADED | 5 | The user authentication widget has been loaded.| 42| WIDGET_RELEASED | 6 | The user authentication widget has been released.| 43 44## EnrolledState<sup>12+</sup> 45 46Represents the state of a credential enrolled. 47 48**Atomic service API**: This API can be used in atomic services since API version 12. 49 50**System capability**: SystemCapability.UserIAM.UserAuth.Core 51 52| Name | Type | Read-Only| Optional| Description | 53| ------------ | ---------- | ---- | ---- | -------------------- | 54| credentialDigest | number | No | No| Credential digest, which is randomly generated when a credential is added.| 55| credentialCount | number | No | No| Number of enrolled credentials. | 56 57## ReuseMode<sup>12+</sup> 58 59Enumerates the modes for reusing authentication results. 60 61**System capability**: SystemCapability.UserIAM.UserAuth.Core 62 63| Name | Value | Description | 64| ----------- | ---- | ---------- | 65| AUTH_TYPE_RELEVANT | 1 | The device unlock authentication result can be reused within the validity period if the authentication type matches any of the authentication types specified for this authentication.<br> **Atomic service API**: This API can be used in atomic services since API version 12.| 66| AUTH_TYPE_IRRELEVANT | 2 | The device unlock authentication result can be reused within the validity period regardless of the authentication type.<br>**Atomic service API**: This API can be used in atomic services since API version 12.| 67| CALLER_IRRELEVANT_AUTH_TYPE_RELEVANT<sup>14+</sup> | 3 | Any identity authentication result (including device unlock authentication result) can be reused within the validity period if the authentication type matches any of the authentication types specified for this authentication.<br>**Atomic service API**: This API can be used in atomic services since API version 14.| 68| CALLER_IRRELEVANT_AUTH_TYPE_IRRELEVANT<sup>14+</sup> | 4 | Any identity authentication result (including device unlock authentication result) can be reused within the validity period regardless of the authentication type.<br>**Atomic service API**: This API can be used in atomic services since API version 14.| 69 70## ReuseUnlockResult<sup>12+</sup> 71 72Represents information about the authentication result reuse. 73> **NOTE** 74> 75> If the credential changes within the reuse duration after a successful identity authentication (including device unlock authentication), the authentication result can still be reused and the actual **EnrolledState** is returned in the authentication result. If the credential used for the previous authentication has been deleted when the authentication result is used:<br>- If the deleted credential is face or fingerprint, the authentication result can still be reused, but **credentialCount** and **credentialDigest** in the **EnrolledState** returned are both **0**.<br>- If the deleted credential is a lock screen password, the reuse will fail. 76 77**Atomic service API**: This API can be used in atomic services since API version 12. 78 79**System capability**: SystemCapability.UserIAM.UserAuth.Core 80 81| Name | Type | Mandatory| Description | 82| ------------ | ---------- | ---- | -------------------- | 83| reuseMode | [ReuseMode](#reusemode12) | Yes | Authentication result reuse mode. | 84| reuseDuration | number | Yes | Period for which the authentication result can be reused. The value must be greater than 0 and less than [MAX_ALLOWABLE_REUSE_DURATION](#constant).| 85 86## userAuth.getEnrolledState<sup>12+</sup> 87 88getEnrolledState(authType : UserAuthType): EnrolledState 89 90Obtains the credential state. 91 92**Required permissions**: ohos.permission.ACCESS_BIOMETRIC 93 94**Atomic service API**: This API can be used in atomic services since API version 12. 95 96**System capability**: SystemCapability.UserIAM.UserAuth.Core 97 98**Parameters** 99 100| Name | Type | Mandatory| Description | 101| -------------- | ---------------------------------- | ---- | -------------------------- | 102| authType | [UserAuthType](#userauthtype8) | Yes | Authentication type.| 103 104**Return value** 105 106| Type | Description | 107| --------------------- | ------------------------------------------------------------ | 108| [EnrolledState](#enrolledstate12) | Credential state obtained if the operation is successful.| 109 110**Error codes** 111 112For details about the error codes, see [User Authentication Error Codes](errorcode-useriam.md). 113 114| ID| Error Message| 115| -------- | ------- | 116| 201 | Permission denied. | 117| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. | 118| 12500002 | General operation error. | 119| 12500005 | The authentication type is not supported. | 120| 12500010 | The type of credential has not been enrolled. | 121 122**Example** 123 124```ts 125import { userAuth } from '@kit.UserAuthenticationKit'; 126import { BusinessError } from '@kit.BasicServicesKit'; 127 128try { 129 let enrolledState = userAuth.getEnrolledState(userAuth.UserAuthType.FACE); 130 console.info(`get current enrolled state success, enrolledState = ${JSON.stringify(enrolledState)}`); 131} catch (error) { 132 const err: BusinessError = error as BusinessError; 133 console.error(`get current enrolled state failed, Code is ${err?.code}, message is ${err?.message}`); 134} 135``` 136 137## AuthParam<sup>10+</sup> 138 139Defines the user authentication parameters. 140 141**System capability**: SystemCapability.UserIAM.UserAuth.Core 142 143| Name | Type | Mandatory| Description | 144| -------------- | ---------------------------------- | ---- | ------------------------------------------------------------ | 145| challenge | Uint8Array | Yes | Random challenge value, which can be used to prevent replay attacks. It cannot exceed 32 bytes and can be passed in **Uint8Array([])** format.<br>**Atomic service API**: This API can be used in atomic services since API version 12.| 146| authType | [UserAuthType](#userauthtype8)[] | Yes | Authentication type list, which specifies the types of authentication provided on the user authentication page.<br>**Atomic service API**: This API can be used in atomic services since API version 12.| 147| authTrustLevel | [AuthTrustLevel](#authtrustlevel8) | Yes | Authentication trust level. For details, see [Principles for Classifying Biometric Authentication Trust Levels](../../security/UserAuthenticationKit/user-authentication-overview.md#principles-for-classifying-biometric-authentication-trust-levels).<br>**Atomic service API**: This API can be used in atomic services since API version 12.| 148| reuseUnlockResult<sup>12+</sup> | [ReuseUnlockResult](#reuseunlockresult12) | No |Information about the authentication result reuse.<br>**Atomic service API**: This API can be used in atomic services since API version 12.| 149| skipLockedBiometricAuth<sup>20+</sup> | boolean | No | Whether to skip the locked authentication mode and automatically switch to another authentication mode.<br>The value **true** means yes; the value **false** means the opposite. If no alternative mode is available, the user authentication widget is disabled and the error code indicating that the authentication is locked is returned.<br>**Atomic service API**: This API can be used in atomic services since API version 20.| 150 151## WidgetParam<sup>10+</sup> 152 153Represents the information presented on the user authentication page. 154 155**System capability**: SystemCapability.UserIAM.UserAuth.Core 156 157| Name | Type | Mandatory| Description | 158| -------------------- | ----------------------------------- | ---- | ------------------------------------------------------------ | 159| title | string | Yes | Title of the user authentication page. It cannot exceed 500 characters.<br> **Atomic service API**: This API can be used in atomic services since API version 12.| 160| navigationButtonText | string | No | Text on the navigation button. It cannot exceed 60 characters. It is supported in single fingerprint or facial authentication before API version 18. Since API version 18, it is also supported in combined facial and fingerprint authentication.<br> **Atomic service API**: This API can be used in atomic services since API version 12.| 161| uiContext<sup>18+</sup> | Context | No | Whether to display the authentication dialog box in modal application mode. This mode is applicable only to 2-in-1 devices. If this mode is not used or other types of devices are used, the authentication dialog box is displayed in modal system mode.<br> **Atomic service API**: This API can be used in atomic services since API version 18.| 162 163## UserAuthResult<sup>10+</sup> 164 165Represents the user authentication result. If the authentication is successful, the authentication type and token information are returned. 166 167**Atomic service API**: This API can be used in atomic services since API version 12. 168 169**System capability**: SystemCapability.UserIAM.UserAuth.Core 170 171| Name | Type | Mandatory| Description | 172| -------- | ------------------------------ | ---- | ------------------------------------------------------------ | 173| result | number | Yes | User authentication result. If the authentication is successful, **SUCCESS** is returned. Otherwise, an error code is returned. For details, see [UserAuthResultCode](#userauthresultcode9).| 174| token | Uint8Array | No | Authentication token information. | 175| authType | [UserAuthType](#userauthtype8) | No | Authentication type. | 176| enrolledState<sup>12+</sup> | [EnrolledState](#enrolledstate12) | No | Credential state.| 177 178## IAuthCallback<sup>10+</sup> 179 180Provides callbacks to return the authentication result. 181 182### onResult<sup>10+</sup> 183 184onResult(result: UserAuthResult): void 185 186Called to return the authentication result. If the authentication is successful, **UserAuthResult** contains the token information. 187 188**Atomic service API**: This API can be used in atomic services since API version 12. 189 190**System capability**: SystemCapability.UserIAM.UserAuth.Core 191 192**Parameters** 193 194| Name| Type | Mandatory| Description | 195| ------ | ----------------------------------- | ---- | ---------- | 196| result | [UserAuthResult](#userauthresult10) | Yes | Authentication result.| 197 198**Example 1** 199 200Initiate a lock screen password authentication request at ATL3 or higher. 201 202```ts 203import { BusinessError } from '@kit.BasicServicesKit'; 204import { cryptoFramework } from '@kit.CryptoArchitectureKit'; 205import { userAuth } from '@kit.UserAuthenticationKit'; 206 207try { 208 const rand = cryptoFramework.createRandom(); 209 const len: number = 16; 210 let randData: Uint8Array | null = null; 211 let retryCount = 0; 212 while(retryCount < 3){ 213 randData = rand?.generateRandomSync(len)?.data; 214 if(randData){ 215 break; 216 } 217 retryCount++; 218 } 219 if(!randData){ 220 return; 221 } 222 const authParam: userAuth.AuthParam = { 223 challenge: randData, 224 authType: [userAuth.UserAuthType.PIN], 225 authTrustLevel: userAuth.AuthTrustLevel.ATL3, 226 }; 227 const widgetParam: userAuth.WidgetParam = { 228 title:'Enter password', 229 }; 230 231 const userAuthInstance = userAuth.getUserAuthInstance(authParam, widgetParam); 232 console.info('get userAuth instance success'); 233 // The authentication result is returned by onResult only after the authentication is started by start() of UserAuthInstance. 234 userAuthInstance.on('result', { 235 onResult (result) { 236 console.info(`userAuthInstance callback result = ${JSON.stringify(result)}`); 237 } 238 }); 239 console.info('auth on success'); 240 userAuthInstance.start(); 241 console.info('auth start success'); 242} catch (error) { 243 const err: BusinessError = error as BusinessError; 244 console.error(`auth catch error. Code is ${err?.code}, message is ${err?.message}`); 245} 246``` 247 248**Example 2** 249 250Initiate a lock screen password authentication request at ATL3 or higher, and enable the authentication result to be reused for the same type of authentication within the specified time. 251 252```ts 253import { BusinessError } from '@kit.BasicServicesKit'; 254import { cryptoFramework } from '@kit.CryptoArchitectureKit'; 255import { userAuth } from '@kit.UserAuthenticationKit'; 256 257let reuseUnlockResult: userAuth.ReuseUnlockResult = { 258 reuseMode: userAuth.ReuseMode.AUTH_TYPE_RELEVANT, 259 reuseDuration: userAuth.MAX_ALLOWABLE_REUSE_DURATION, 260} 261try { 262 const rand = cryptoFramework.createRandom(); 263 const len: number = 16; 264 let randData: Uint8Array | null = null; 265 let retryCount = 0; 266 while(retryCount < 3){ 267 randData = rand?.generateRandomSync(len)?.data; 268 if(randData){ 269 break; 270 } 271 retryCount++; 272 } 273 if(!randData){ 274 return; 275 } 276 const authParam: userAuth.AuthParam = { 277 challenge: randData, 278 authType: [userAuth.UserAuthType.PIN], 279 authTrustLevel: userAuth.AuthTrustLevel.ATL3, 280 reuseUnlockResult: reuseUnlockResult, 281 }; 282 const widgetParam: userAuth.WidgetParam = { 283 title:'Enter password', 284 }; 285 const userAuthInstance = userAuth.getUserAuthInstance(authParam, widgetParam); 286 console.info('get userAuth instance success'); 287 // The authentication result is returned by onResult only after the authentication is started by start() of UserAuthInstance. 288 userAuthInstance.on('result', { 289 onResult (result) { 290 console.info(`userAuthInstance callback result = ${JSON.stringify(result)}`); 291 } 292 }); 293 console.info('auth on success'); 294 userAuthInstance.start(); 295 console.info('auth start success'); 296} catch (error) { 297 const err: BusinessError = error as BusinessError; 298 console.error(`auth catch error. Code is ${err?.code}, message is ${err?.message}`); 299} 300``` 301 302**Example 3** 303 304Initiate a lock screen authentication request at ATL3 or higher, and enable the authentication result to be reused for any type of authentication within the maximum reuse duration of any application. 305 306```ts 307import { BusinessError } from '@kit.BasicServicesKit'; 308import { cryptoFramework } from '@kit.CryptoArchitectureKit'; 309import { userAuth } from '@kit.UserAuthenticationKit'; 310 311let reuseUnlockResult: userAuth.ReuseUnlockResult = { 312 reuseMode: userAuth.ReuseMode.CALLER_IRRELEVANT_AUTH_TYPE_RELEVANT, 313 reuseDuration: userAuth.MAX_ALLOWABLE_REUSE_DURATION, 314} 315try { 316 const rand = cryptoFramework.createRandom(); 317 const len: number = 16; 318 let randData: Uint8Array | null = null; 319 let retryCount = 0; 320 while(retryCount < 3){ 321 randData = rand?.generateRandomSync(len)?.data; 322 if(randData){ 323 break; 324 } 325 retryCount++; 326 } 327 if(!randData){ 328 return; 329 } 330 const authParam: userAuth.AuthParam = { 331 challenge: randData, 332 authType: [userAuth.UserAuthType.PIN], 333 authTrustLevel: userAuth.AuthTrustLevel.ATL3, 334 reuseUnlockResult: reuseUnlockResult, 335 }; 336 const widgetParam: userAuth.WidgetParam = { 337 title:'Enter password', 338 }; 339 const userAuthInstance = userAuth.getUserAuthInstance(authParam, widgetParam); 340 console.info('get userAuth instance success'); 341 // The authentication result is returned by onResult only after the authentication is started by start() of UserAuthInstance. 342 userAuthInstance.on('result', { 343 onResult (result) { 344 console.info(`userAuthInstance callback result = ${JSON.stringify(result)}`); 345 } 346 }); 347 console.info('auth on success'); 348 userAuthInstance.start(); 349 console.info('auth start success'); 350} catch (error) { 351 const err: BusinessError = error as BusinessError; 352 console.error(`auth catch error. Code is ${err?.code}, message is ${err?.message}`); 353} 354``` 355 356## AuthTipInfo<sup>20+</sup> 357 358Represents the intermediate authentication status. 359 360**Atomic service API**: This API can be used in atomic services since API version 20. 361 362**System capability**: SystemCapability.UserIAM.UserAuth.Core 363 364| Name | Type | Read-Only| Optional| Description | 365| -------- | ------------------------------------ | ---- | ---- | ------------------------------------ | 366| tipType | [UserAuthType](#userauthtype8) | No | No | Authentication type of the intermediate status.| 367| tipCode | [UserAuthTipCode](#userauthtipcode20) | No | No | Intermediate status.| 368 369## AuthTipCallback<sup>20+</sup> 370 371type AuthTipCallback = (authTipInfo: AuthTipInfo) => void 372 373Defines the callback to return the intermediate authentication status. 374 375**Atomic service API**: This API can be used in atomic services since API version 20. 376 377**System capability**: SystemCapability.UserIAM.UserAuth.Core 378 379**Parameters** 380 381| Name| Type | Mandatory| Description | 382| ------ | -----------------------------------| ---- | ---------- | 383| authTipInfo | [AuthTipInfo](#authtipinfo20) | Yes | Intermediate authentication status.| 384 385**Example** 386 387```ts 388import { BusinessError } from '@kit.BasicServicesKit'; 389import { cryptoFramework } from '@kit.CryptoArchitectureKit'; 390import { userAuth } from '@kit.UserAuthenticationKit'; 391 392try { 393 const rand = cryptoFramework.createRandom(); 394 const len: number = 16; 395 let randData: Uint8Array | null = null; 396 let retryCount = 0; 397 while(retryCount < 3){ 398 randData = rand?.generateRandomSync(len)?.data; 399 if(randData){ 400 break; 401 } 402 retryCount++; 403 } 404 if(!randData){ 405 return; 406 } 407 const authParam: userAuth.AuthParam = { 408 challenge: randData, 409 authType: [userAuth.UserAuthType.PIN], 410 authTrustLevel: userAuth.AuthTrustLevel.ATL3, 411 }; 412 const widgetParam: userAuth.WidgetParam = { 413 title:'Enter password', 414 }; 415 416 const userAuthInstance = userAuth.getUserAuthInstance(authParam, widgetParam); 417 console.info('get userAuth instance success'); 418 // The intermediate authentication status is returned by onAuthTip only after the authentication is started by start() of UserAuthInstance. 419 userAuthInstance.on('authTip', (authTipInfo: userAuth.AuthTipInfo) => { 420 console.info(`userAuthInstance callback authTipInfo = ${JSON.stringify(authTipInfo)}`); 421 }); 422 console.info('auth on success'); 423 userAuthInstance.start(); 424 console.info('auth start success'); 425} catch (error) { 426 const err: BusinessError = error as BusinessError; 427 console.error(`auth catch error. Code is ${err?.code}, message is ${err?.message}`); 428} 429``` 430 431## UserAuthInstance<sup>10+</sup> 432 433Provides APIs for user authentication. The user authentication widget is supported. 434Before using the APIs of **UserAuthInstance**, you must obtain a **UserAuthInstance** instance by using [getUserAuthInstance](#userauthgetuserauthinstance10). 435 436### on<sup>10+</sup> 437 438on(type: 'result', callback: IAuthCallback): void 439 440Subscribes to the user authentication result. 441 442**Atomic service API**: This API can be used in atomic services since API version 12. 443 444**System capability**: SystemCapability.UserIAM.UserAuth.Core 445 446**Parameters** 447 448| Name | Type | Mandatory| Description | 449| -------- | --------------------------------- | ---- | ------------------------------------------ | 450| type | 'result' | Yes | Event type. The value is **result**, which indicates the authentication result.| 451| callback | [IAuthCallback](#iauthcallback10) | Yes | Callback used to return the user authentication result. | 452 453**Error codes** 454 455For details about the error codes, see [User Authentication Error Codes](errorcode-useriam.md). 456 457| ID| Error Message | 458| -------- | ------------------------ | 459| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. 3.Parameter verification failed. | 460| 12500002 | General operation error. | 461 462**Example 1** 463 464Perform user identity authentication in modal system mode. 465 466```ts 467import { BusinessError } from '@kit.BasicServicesKit'; 468import { cryptoFramework } from '@kit.CryptoArchitectureKit'; 469import { userAuth } from '@kit.UserAuthenticationKit'; 470 471try { 472 const rand = cryptoFramework.createRandom(); 473 const len: number = 16; 474 let randData: Uint8Array | null = null; 475 let retryCount = 0; 476 while(retryCount < 3){ 477 randData = rand?.generateRandomSync(len)?.data; 478 if(randData){ 479 break; 480 } 481 retryCount++; 482 } 483 if(!randData){ 484 return; 485 } 486 const authParam: userAuth.AuthParam = { 487 challenge: randData, 488 authType: [userAuth.UserAuthType.PIN], 489 authTrustLevel: userAuth.AuthTrustLevel.ATL3, 490 }; 491 const widgetParam: userAuth.WidgetParam = { 492 title:'Enter password', 493 }; 494 const userAuthInstance = userAuth.getUserAuthInstance(authParam, widgetParam); 495 console.info('get userAuth instance success'); 496 // The authentication result is returned by onResult only after the authentication is started by start() of UserAuthInstance. 497 userAuthInstance.on('result', { 498 onResult (result) { 499 console.info(`userAuthInstance callback result = ${JSON.stringify(result)}`); 500 } 501 }); 502 console.info('auth on success'); 503 userAuthInstance.start(); 504 console.info('auth start success'); 505} catch (error) { 506 const err: BusinessError = error as BusinessError; 507 console.error(`auth catch error. Code is ${err?.code}, message is ${err?.message}`); 508} 509``` 510 511**Example 2** 512 513Perform user identity authentication in modal application mode. 514 515```ts 516import { BusinessError } from '@kit.BasicServicesKit'; 517import { cryptoFramework } from '@kit.CryptoArchitectureKit'; 518import { userAuth } from '@kit.UserAuthenticationKit'; 519 520@Entry 521@Component 522struct Index { 523 modelApplicationAuth(): void { 524 try { 525 const rand = cryptoFramework.createRandom(); 526 const len: number = 16; 527 let randData: Uint8Array | null = null; 528 let retryCount = 0; 529 while(retryCount < 3){ 530 randData = rand?.generateRandomSync(len)?.data; 531 if(randData){ 532 break; 533 } 534 retryCount++; 535 } 536 if(!randData){ 537 return; 538 } 539 const authParam: userAuth.AuthParam = { 540 challenge: randData, 541 authType: [userAuth.UserAuthType.PIN], 542 authTrustLevel: userAuth.AuthTrustLevel.ATL3, 543 }; 544 const uiContext: UIContext = this.getUIContext(); 545 const context: Context | undefined = uiContext.getHostContext(); 546 const widgetParam: userAuth.WidgetParam = { 547 title:'Enter password', 548 uiContext: context, 549 }; 550 const userAuthInstance = userAuth.getUserAuthInstance(authParam, widgetParam); 551 console.info('get userAuth instance success'); 552 // The authentication result is returned by onResult only after the authentication is started by start() of UserAuthInstance. 553 userAuthInstance.on('result', { 554 onResult (result) { 555 console.info(`userAuthInstance callback result = ${JSON.stringify(result)}`); 556 } 557 }); 558 console.info('auth on success'); 559 userAuthInstance.start(); 560 console.info('auth start success'); 561 } catch (error) { 562 const err: BusinessError = error as BusinessError; 563 console.error(`auth catch error. Code is ${err?.code}, message is ${err?.message}`); 564 } 565 } 566 567 build() { 568 Column() { 569 Button('start auth') 570 .onClick(() => { 571 this.modelApplicationAuth(); 572 }) 573 } 574 } 575} 576``` 577 578### off<sup>10+</sup> 579 580off(type: 'result', callback?: IAuthCallback): void 581 582Unsubscribes from the user authentication result. 583 584> **NOTE** 585> 586> The [UserAuthInstance](#userauthinstance10) instance used to invoke this API must be the one used to subscribe to the event. 587 588**Atomic service API**: This API can be used in atomic services since API version 12. 589 590**System capability**: SystemCapability.UserIAM.UserAuth.Core 591 592**Parameters** 593 594| Name | Type | Mandatory| Description | 595| -------- | --------------------------------- | ---- | ------------------------------------------ | 596| type | 'result' | Yes | Event type. The value is **result**, which indicates the authentication result.| 597| callback | [IAuthCallback](#iauthcallback10) | No | Callback used to return the user authentication result. | 598 599**Error codes** 600 601For details about the error codes, see [User Authentication Error Codes](errorcode-useriam.md). 602 603| ID| Error Message | 604| -------- | ------------------------ | 605| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. 3.Parameter verification failed. | 606| 12500002 | General operation error. | 607 608**Example** 609 610```ts 611import { BusinessError } from '@kit.BasicServicesKit'; 612import { cryptoFramework } from '@kit.CryptoArchitectureKit'; 613import { userAuth } from '@kit.UserAuthenticationKit'; 614 615try { 616 const rand = cryptoFramework.createRandom(); 617 const len: number = 16; 618 let randData: Uint8Array | null = null; 619 let retryCount = 0; 620 while(retryCount < 3){ 621 randData = rand?.generateRandomSync(len)?.data; 622 if(randData){ 623 break; 624 } 625 retryCount++; 626 } 627 if(!randData){ 628 return; 629 } 630 const authParam: userAuth.AuthParam = { 631 challenge: randData, 632 authType: [userAuth.UserAuthType.PIN], 633 authTrustLevel: userAuth.AuthTrustLevel.ATL3, 634 }; 635 const widgetParam: userAuth.WidgetParam = { 636 title:'Enter password', 637 }; 638 const userAuthInstance = userAuth.getUserAuthInstance(authParam, widgetParam); 639 console.info('get userAuth instance success'); 640 userAuthInstance.off('result', { 641 onResult (result) { 642 console.info(`auth off result = ${JSON.stringify(result)}`); 643 } 644 }); 645 console.info('auth off success'); 646} catch (error) { 647 const err: BusinessError = error as BusinessError; 648 console.error(`auth catch error. Code is ${err?.code}, message is ${err?.message}`); 649} 650``` 651 652### start<sup>10+</sup> 653 654start(): void 655 656Starts authentication. 657 658> **NOTE**<br> 659> Each **UserAuthInstance** can be used for authentication only once. 660 661**Required permissions**: ohos.permission.ACCESS_BIOMETRIC or ohos.permission.USER_AUTH_FROM_BACKGROUND (available only for system applications) 662 663Starting from API version 20, only system applications can apply for the ohos.permission.USER_AUTH_FROM_BACKGROUND permission. 664 665**Atomic service API**: This API can be used in atomic services since API version 12. 666 667**System capability**: SystemCapability.UserIAM.UserAuth.Core 668 669**Error codes** 670 671For details about the error codes, see [User Authentication Error Codes](errorcode-useriam.md). 672 673| ID| Error Message | 674| -------- | ------------------------------------------------ | 675| 201 | Permission denied. Possible causes:1.No permission to access biometric. 2.No permission to start authentication from background.| 676| 401 | Parameter error. Possible causes: 1.Incorrect parameter types. | 677| 12500001 | Authentication failed. | 678| 12500002 | General operation error. | 679| 12500003 | Authentication canceled. | 680| 12500004 | Authentication timeout. | 681| 12500005 | The authentication type is not supported. | 682| 12500006 | The authentication trust level is not supported. | 683| 12500007 | Authentication service is busy. | 684| 12500009 | Authentication is locked out. | 685| 12500010 | The type of credential has not been enrolled. | 686| 12500011 | Switched to the custom authentication process. | 687| 12500013 | Operation failed because of PIN expired. | 688 689**Example** 690 691```ts 692import { BusinessError } from '@kit.BasicServicesKit'; 693import { cryptoFramework } from '@kit.CryptoArchitectureKit'; 694import { userAuth } from '@kit.UserAuthenticationKit'; 695 696try { 697 const rand = cryptoFramework.createRandom(); 698 const len: number = 16; 699 let randData: Uint8Array | null = null; 700 let retryCount = 0; 701 while(retryCount < 3){ 702 randData = rand?.generateRandomSync(len)?.data; 703 if(randData){ 704 break; 705 } 706 retryCount++; 707 } 708 if(!randData){ 709 return; 710 } 711 const authParam: userAuth.AuthParam = { 712 challenge: randData, 713 authType: [userAuth.UserAuthType.PIN], 714 authTrustLevel: userAuth.AuthTrustLevel.ATL3, 715 }; 716 const widgetParam: userAuth.WidgetParam = { 717 title:'Enter password', 718 }; 719 const userAuthInstance = userAuth.getUserAuthInstance(authParam, widgetParam); 720 console.info('get userAuth instance success'); 721 userAuthInstance.start(); 722 console.info('auth start success'); 723} catch (error) { 724 const err: BusinessError = error as BusinessError; 725 console.error(`auth catch error. Code is ${err?.code}, message is ${err?.message}`); 726} 727``` 728 729### cancel<sup>10+</sup> 730 731cancel(): void 732 733Cancels this authentication. 734 735> **NOTE** 736> 737> **UserAuthInstance** must be the instance being authenticated. 738 739**Required permissions**: ohos.permission.ACCESS_BIOMETRIC 740 741**Atomic service API**: This API can be used in atomic services since API version 12. 742 743**System capability**: SystemCapability.UserIAM.UserAuth.Core 744 745**Error codes** 746 747| ID| Error Message | 748| -------- | ------------------------------- | 749| 201 | Permission denied. | 750| 401 | Parameter error. Possible causes: 1.Incorrect parameter types. | 751| 12500002 | General operation error. | 752 753**Example** 754 755```ts 756import { BusinessError } from '@kit.BasicServicesKit'; 757import { cryptoFramework } from '@kit.CryptoArchitectureKit'; 758import { userAuth } from '@kit.UserAuthenticationKit'; 759 760try { 761 const rand = cryptoFramework.createRandom(); 762 const len: number = 16; 763 let randData: Uint8Array | null = null; 764 let retryCount = 0; 765 while(retryCount < 3){ 766 randData = rand?.generateRandomSync(len)?.data; 767 if(randData){ 768 break; 769 } 770 retryCount++; 771 } 772 if(!randData){ 773 return; 774 } 775 const authParam : userAuth.AuthParam = { 776 challenge: randData, 777 authType: [userAuth.UserAuthType.PIN], 778 authTrustLevel: userAuth.AuthTrustLevel.ATL3, 779 }; 780 const widgetParam: userAuth.WidgetParam = { 781 title:'Enter password', 782 }; 783 const userAuthInstance = userAuth.getUserAuthInstance(authParam, widgetParam); 784 console.info('get userAuth instance success'); 785 // The cancel() API can be called only after the authentication is started by start() of UserAuthInstance. 786 userAuthInstance.start(); 787 console.info('auth start success'); 788 userAuthInstance.cancel(); 789 console.info('auth cancel success'); 790} catch (error) { 791 const err: BusinessError = error as BusinessError; 792 console.error(`auth catch error. Code is ${err?.code}, message is ${err?.message}`); 793} 794``` 795 796### on<sup>20+</sup> 797 798on(type: 'authTip', callback: AuthTipCallback): void 799 800Subscribes to the event for intermediate authentication status. 801 802**Atomic service API**: This API can be used in atomic services since API version 20. 803 804**System capability**: SystemCapability.UserIAM.UserAuth.Core 805 806**Parameters** 807 808| Name | Type | Mandatory| Description | 809| -------- | ------------- | ---- | ------------------------------------------ | 810| type | string | Yes | Event type. The supported event is **'authTip'**. This event is triggered when [start()](#start10) is called and authentication is initiated.| 811| callback | [AuthTipCallback](#authtipcallback20) | Yes | Callback used to return the intermediate authentication status. | 812 813**Error codes** 814 815For details about the error codes, see [User Authentication Error Codes](errorcode-useriam.md). 816 817| ID| Error Message | 818| -------- | ------------------------ | 819| 12500002 | General operation error. | 820 821**Example** 822 823```ts 824import { BusinessError } from '@kit.BasicServicesKit'; 825import { cryptoFramework } from '@kit.CryptoArchitectureKit'; 826import { userAuth } from '@kit.UserAuthenticationKit'; 827 828try { 829 const rand = cryptoFramework.createRandom(); 830 const len: number = 16; 831 let randData: Uint8Array | null = null; 832 let retryCount = 0; 833 while(retryCount < 3){ 834 randData = rand?.generateRandomSync(len)?.data; 835 if(randData){ 836 break; 837 } 838 retryCount++; 839 } 840 if(!randData){ 841 return; 842 } 843 const authParam: userAuth.AuthParam = { 844 challenge: randData, 845 authType: [userAuth.UserAuthType.PIN], 846 authTrustLevel: userAuth.AuthTrustLevel.ATL3, 847 }; 848 const widgetParam: userAuth.WidgetParam = { 849 title:'Enter password', 850 }; 851 const userAuthInstance = userAuth.getUserAuthInstance(authParam, widgetParam); 852 console.info('get userAuth instance success'); 853 // The intermediate authentication status is returned by onAuthTip only after the authentication is started by start() of UserAuthInstance. 854 userAuthInstance.on('authTip', (authTipInfo: userAuth.AuthTipInfo) => { 855 console.info(`userAuthInstance callback authTipInfo = ${JSON.stringify(authTipInfo)}`); 856 }); 857 console.info('auth on success'); 858 userAuthInstance.start(); 859 console.info('auth start success'); 860} catch (error) { 861 const err: BusinessError = error as BusinessError; 862 console.error(`auth catch error. Code is ${err?.code}, message is ${err?.message}`); 863} 864``` 865 866### off<sup>20+</sup> 867 868off(type: 'authTip', callback?: AuthTipCallback): void 869 870Unsubscribes from the event for intermediate authentication status. 871 872> **NOTE** 873> 874> The [UserAuthInstance](#userauthinstance10) instance used to invoke this API must be the one used to subscribe to the event. 875 876**Atomic service API**: This API can be used in atomic services since API version 20. 877 878**System capability**: SystemCapability.UserIAM.UserAuth.Core 879 880**Parameters** 881 882| Name | Type | Mandatory| Description | 883| -------- | ------------- | ---- | ------------------------------------------ | 884| type | string | Yes | Event type. The supported event is **'authTip'**. This API unsubscribes from the event triggered by [on()](#on20) after the [start()](#start10) call and the initiation of authentication.| 885| callback | [AuthTipCallback](#authtipcallback20) | No | Callback used to return the intermediate authentication status. If this parameter is not passed, the value passed when the [on()](#on20) API is called is used by default.| 886 887**Error codes** 888 889For details about the error codes, see [User Authentication Error Codes](errorcode-useriam.md). 890 891| ID| Error Message | 892| -------- | ------------------------ | 893| 12500002 | General operation error. | 894 895**Example** 896 897```ts 898import { BusinessError } from '@kit.BasicServicesKit'; 899import { cryptoFramework } from '@kit.CryptoArchitectureKit'; 900import { userAuth } from '@kit.UserAuthenticationKit'; 901 902try { 903 const rand = cryptoFramework.createRandom(); 904 const len: number = 16; 905 let randData: Uint8Array | null = null; 906 let retryCount = 0; 907 while(retryCount < 3){ 908 randData = rand?.generateRandomSync(len)?.data; 909 if(randData){ 910 break; 911 } 912 retryCount++; 913 } 914 if(!randData){ 915 return; 916 } 917 const authParam: userAuth.AuthParam = { 918 challenge: randData, 919 authType: [userAuth.UserAuthType.PIN], 920 authTrustLevel: userAuth.AuthTrustLevel.ATL3, 921 }; 922 const widgetParam: userAuth.WidgetParam = { 923 title:'Enter password', 924 }; 925 const userAuthInstance = userAuth.getUserAuthInstance(authParam, widgetParam); 926 console.info('get userAuth instance success'); 927 userAuthInstance.off('authTip', (authTipInfo: userAuth.AuthTipInfo) => { 928 console.info(`userAuthInstance callback authTipInfo = ${JSON.stringify(authTipInfo)}`); 929 }); 930 console.info('auth off success'); 931} catch (error) { 932 const err: BusinessError = error as BusinessError; 933 console.error(`auth catch error. Code is ${err?.code}, message is ${err?.message}`); 934} 935``` 936 937## userAuth.getUserAuthInstance<sup>10+</sup> 938 939getUserAuthInstance(authParam: AuthParam, widgetParam: WidgetParam): UserAuthInstance 940 941Obtains a [UserAuthInstance](#userauthinstance10) instance for user authentication. The user authentication widget is also supported. 942 943> **NOTE**<br> 944> Each **UserAuthInstance** can be used for authentication only once. 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| authParam | [AuthParam](#authparam10) | Yes | User authentication parameters. | 955| widgetParam | [WidgetParam](#widgetparam10) | Yes | Parameters on the user authentication page.| 956 957**Return value** 958 959| Type | Description | 960| --------------------------------------- | -------------------------- | 961| [UserAuthInstance](#userauthinstance10) | **UserAuthInstance** instance that supports UI.| 962 963**Error codes** 964 965For details about the error codes, see [User Authentication Error Codes](errorcode-useriam.md). 966 967| ID| Error Message | 968| -------- | ------------------------------------------------ | 969| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. 3.Parameter verification failed. | 970| 12500002 | General operation error. | 971| 12500005 | The authentication type is not supported. | 972| 12500006 | The authentication trust level is not supported. | 973 974**Example** 975 976```ts 977import { BusinessError } from '@kit.BasicServicesKit'; 978import { cryptoFramework } from '@kit.CryptoArchitectureKit'; 979import { userAuth } from '@kit.UserAuthenticationKit'; 980 981try { 982 const rand = cryptoFramework.createRandom(); 983 const len: number = 16; 984 let randData: Uint8Array | null = null; 985 let retryCount = 0; 986 while(retryCount < 3){ 987 randData = rand?.generateRandomSync(len)?.data; 988 if(randData){ 989 break; 990 } 991 retryCount++; 992 } 993 if(!randData){ 994 return; 995 } 996 const authParam: userAuth.AuthParam = { 997 challenge: randData, 998 authType: [userAuth.UserAuthType.PIN], 999 authTrustLevel: userAuth.AuthTrustLevel.ATL3, 1000 }; 1001 const widgetParam: userAuth.WidgetParam = { 1002 title:'Enter password', 1003 }; 1004 let userAuthInstance = userAuth.getUserAuthInstance(authParam, widgetParam); 1005 console.info('get userAuth instance success'); 1006} catch (error) { 1007 const err: BusinessError = error as BusinessError; 1008 console.error(`auth catch error. Code is ${err?.code}, message is ${err?.message}`); 1009} 1010``` 1011 1012## AuthResultInfo<sup>(deprecated)</sup> 1013 1014Represents the authentication result. 1015 1016> **NOTE**<br> 1017> This API is supported since API version 9 and deprecated since API version 11. 1018 1019**System capability**: SystemCapability.UserIAM.UserAuth.Core 1020 1021| Name | Type | Mandatory| Description | 1022| ------------ | ---------- | ---- | -------------------- | 1023| result | number | Yes | Authentication result. | 1024| token | Uint8Array | No | Token that has passed the user identity authentication.| 1025| remainAttempts | number | No | Number of remaining authentication attempts.| 1026| lockoutDuration | number | No | Lock duration of the authentication operation, in ms.| 1027 1028## TipInfo<sup>(deprecated)</sup> 1029 1030Represents the tip information displayed during the authentication, which is used to provide feedback during the authentication process. 1031 1032> **NOTE**<br> 1033> This API is supported since API version 9 and deprecated since API version 11. 1034 1035**System capability**: SystemCapability.UserIAM.UserAuth.Core 1036 1037| Name | Type | Mandatory| Description | 1038| ------------ | ---------- | ---- | -------------------- | 1039| module | number | Yes | ID of the module that sends the tip information. | 1040| tip | number | Yes | Tip to be given during the authentication process. | 1041 1042## EventInfo<sup>(deprecated)</sup> 1043 1044type EventInfo = AuthResultInfo | TipInfo 1045 1046Enumerates the authentication event information types. 1047 1048It consists of the fields in **Type** in the following table. 1049 1050> **NOTE**<br> 1051> This parameter is supported since API version 9 and deprecated since API version 11. Use [UserAuthResult](#userauthresult10) instead. 1052 1053**System capability**: SystemCapability.UserIAM.UserAuth.Core 1054 1055| Type | Description | 1056| --------- | ----------------------- | 1057| [AuthResultInfo](#authresultinfodeprecated) | Authentication result. | 1058| [TipInfo](#tipinfodeprecated) | Authentication tip information. | 1059 1060## AuthEventKey<sup>(deprecated)</sup> 1061 1062type AuthEventKey = 'result' | 'tip' 1063 1064Defines the keyword of the authentication event type. It is used as a parameter of [on](#ondeprecated). 1065 1066It consists of the fields in **Type** in the following table. 1067 1068> **NOTE**<br> 1069> This API is supported since API version 9 and deprecated since API version 11. 1070 1071**System capability**: SystemCapability.UserIAM.UserAuth.Core 1072 1073| Type | Description | 1074| ---------- | ----------------------- | 1075| 'result' | If the first parameter of [on](#ondeprecated) is **result**, the [callback](#callbackdeprecated) returns the authentication result.| 1076| 'tip' | If the first parameter of [on](#ondeprecated) is **tip**, the [callback](#callbackdeprecated) returns the authentication tip information.| 1077 1078## AuthEvent<sup>(deprecated)</sup> 1079 1080Provides an asynchronous callback to return the authentication event information. 1081 1082> **NOTE**<br> 1083> This API is supported since API version 9 and deprecated since API version 11. Use [IAuthCallback](#iauthcallback10) instead. 1084 1085### callback<sup>(deprecated)</sup> 1086 1087callback(result : EventInfo) : void 1088 1089Called to return the authentication result or authentication tip information. 1090 1091> **NOTE**<br> 1092> This API is supported since API version 9 and deprecated since API version 11. Use [onResult](#onresult10) instead. 1093 1094**System capability**: SystemCapability.UserIAM.UserAuth.Core 1095 1096**Parameters** 1097 1098| Name | Type | Mandatory| Description | 1099| --------- | -------------------------- | ---- | ------------------------------ | 1100| result | [EventInfo](#eventinfodeprecated) | Yes | Authentication result or tip information. | 1101 1102**Example** 1103 1104```ts 1105import { userAuth } from '@kit.UserAuthenticationKit'; 1106 1107let challenge = new Uint8Array([1, 2, 3, 4, 5, 6, 7, 8]); 1108let authType = userAuth.UserAuthType.FACE; 1109let authTrustLevel = userAuth.AuthTrustLevel.ATL1; 1110// Obtain the authentication result via a callback. 1111try { 1112 let auth = userAuth.getAuthInstance(challenge, authType, authTrustLevel); 1113 auth.on('result', { 1114 callback: (result: userAuth.AuthResultInfo) => { 1115 console.info(`authV9 result ${result.result}`); 1116 console.info(`authV9 token ${result.token}`); 1117 console.info(`authV9 remainAttempts ${result.remainAttempts}`); 1118 console.info(`authV9 lockoutDuration ${result.lockoutDuration}`); 1119 } 1120 } as userAuth.AuthEvent); 1121 auth.start(); 1122 console.info('authV9 start success'); 1123} catch (error) { 1124 console.error(`authV9 error = ${error}`); 1125 // do error. 1126} 1127// Obtain the authentication tip information via a callback. 1128try { 1129 let auth = userAuth.getAuthInstance(challenge, authType, authTrustLevel); 1130 auth.on('tip', { 1131 callback : (result : userAuth.TipInfo) => { 1132 switch (result.tip) { 1133 case userAuth.FaceTips.FACE_AUTH_TIP_TOO_BRIGHT: 1134 // Do something. 1135 break; 1136 case userAuth.FaceTips.FACE_AUTH_TIP_TOO_DARK: 1137 // Do something. 1138 break; 1139 default: 1140 // do others. 1141 } 1142 } 1143 } as userAuth.AuthEvent); 1144 auth.start(); 1145 console.info('authV9 start success'); 1146} catch (error) { 1147 console.error(`authV9 error = ${error}`); 1148 // do error. 1149} 1150``` 1151 1152## AuthInstance<sup>(deprecated)</sup> 1153 1154Implements user authentication. 1155 1156> **NOTE**<br> 1157> This API is supported since API version 9 and deprecated since API version 10. Use [UserAuthInstance](#userauthinstance10) instead. 1158 1159### on<sup>(deprecated)</sup> 1160 1161on : (name : AuthEventKey, callback : AuthEvent) => void 1162 1163Subscribes to the user authentication events of the specified type. 1164 1165> **NOTE**<br> 1166> - This API is supported since API version 9 and deprecated since API version 10. 1167> - Use the [AuthInstance](#authinstancedeprecated) instance obtained to call this API. 1168 1169**System capability**: SystemCapability.UserIAM.UserAuth.Core 1170 1171**Parameters** 1172 1173| Name | Type | Mandatory| Description | 1174| --------- | -------------------------- | ---- | ------------------------- | 1175| 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.| 1176| callback | [AuthEvent](#autheventdeprecated) | Yes | Callback used to return the authentication result or tip information.| 1177 1178**Error codes** 1179 1180For details about the error codes, see [User Authentication Error Codes](errorcode-useriam.md). 1181 1182| ID| Error Message| 1183| -------- | ------- | 1184| 401 | Parameter error. | 1185| 12500002 | General operation error. | 1186 1187**Example** 1188 1189```ts 1190import { userAuth } from '@kit.UserAuthenticationKit'; 1191 1192let challenge = new Uint8Array([1, 2, 3, 4, 5, 6, 7, 8]); 1193let authType = userAuth.UserAuthType.FACE; 1194let authTrustLevel = userAuth.AuthTrustLevel.ATL1; 1195try { 1196 let auth = userAuth.getAuthInstance(challenge, authType, authTrustLevel); 1197 // Subscribe to the authentication result. 1198 auth.on('result', { 1199 callback: (result: userAuth.AuthResultInfo) => { 1200 console.info(`authV9 result ${result.result}`); 1201 console.info(`authV9 token ${result.token}`); 1202 console.info(`authV9 remainAttempts ${result.remainAttempts}`); 1203 console.info(`authV9 lockoutDuration ${result.lockoutDuration}`); 1204 } 1205 }); 1206 // Subscribe to authentication tip information. 1207 auth.on('tip', { 1208 callback : (result : userAuth.TipInfo) => { 1209 switch (result.tip) { 1210 case userAuth.FaceTips.FACE_AUTH_TIP_TOO_BRIGHT: 1211 // Do something. 1212 break; 1213 case userAuth.FaceTips.FACE_AUTH_TIP_TOO_DARK: 1214 // Do something. 1215 break; 1216 default: 1217 // do others. 1218 } 1219 } 1220 } as userAuth.AuthEvent); 1221 auth.start(); 1222 console.info('authV9 start success'); 1223} catch (error) { 1224 console.error(`authV9 error = ${error}`); 1225 // do error. 1226} 1227``` 1228 1229### off<sup>(deprecated)</sup> 1230 1231off : (name : AuthEventKey) => void 1232 1233Unsubscribes from the user authentication events of the specific type. 1234 1235> **NOTE**<br> 1236> - This API is supported since API version 9 and deprecated since API version 10. 1237> - The [AuthInstance](#authinstancedeprecated) instance used to call this API must be the one used to subscribe to the events. 1238 1239**System capability**: SystemCapability.UserIAM.UserAuth.Core 1240 1241| Name | Type | Mandatory| Description | 1242| --------- | -------------------------- | ---- | ------------------------- | 1243| 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.| 1244 1245**Error codes** 1246 1247For details about the error codes, see [User Authentication Error Codes](errorcode-useriam.md). 1248 1249| ID| Error Message| 1250| -------- | ------- | 1251| 401 | Parameter error. | 1252| 12500002 | General operation error. | 1253 1254**Example** 1255 1256```ts 1257import { userAuth } from '@kit.UserAuthenticationKit'; 1258 1259let challenge = new Uint8Array([1, 2, 3, 4, 5, 6, 7, 8]); 1260let authType = userAuth.UserAuthType.FACE; 1261let authTrustLevel = userAuth.AuthTrustLevel.ATL1; 1262try { 1263 let auth = userAuth.getAuthInstance(challenge, authType, authTrustLevel); 1264 // Subscribe to the authentication result. 1265 auth.on('result', { 1266 callback: (result: userAuth.AuthResultInfo) => { 1267 console.info(`authV9 result ${result.result}`); 1268 console.info(`authV9 token ${result.token}`); 1269 console.info(`authV9 remainAttempts ${result.remainAttempts}`); 1270 console.info(`authV9 lockoutDuration ${result.lockoutDuration}`); 1271 } 1272 }); 1273 // Unsubscribe from the authentication result. 1274 auth.off('result'); 1275 console.info('cancel subscribe authentication event success'); 1276} catch (error) { 1277 console.error(`cancel subscribe authentication event failed, error = ${error}`); 1278 // do error. 1279} 1280``` 1281 1282### start<sup>(deprecated)</sup> 1283 1284start : () => void 1285 1286Starts authentication. 1287 1288> **NOTE**<br> 1289> - This API is supported since API version 9 and deprecated since API version 10. 1290> - Use the [AuthInstance](#authinstancedeprecated) instance obtained to call this API. 1291 1292**Required permissions**: ohos.permission.ACCESS_BIOMETRIC 1293 1294**System capability**: SystemCapability.UserIAM.UserAuth.Core 1295 1296**Error codes** 1297 1298For details about the error codes, see [User Authentication Error Codes](errorcode-useriam.md). 1299 1300| ID| Error Message| 1301| -------- | ------- | 1302| 201 | Permission denied. | 1303| 401 | Parameter error. | 1304| 12500001 | Authentication failed. | 1305| 12500002 | General operation error. | 1306| 12500003 | The operation is canceled. | 1307| 12500004 | The operation is time-out. | 1308| 12500005 | The authentication type is not supported. | 1309| 12500006 | The authentication trust level is not supported. | 1310| 12500007 | The authentication task is busy. | 1311| 12500009 | The authenticator is locked. | 1312| 12500010 | The type of credential has not been enrolled. | 1313 1314**Example** 1315 1316```ts 1317import { userAuth } from '@kit.UserAuthenticationKit'; 1318 1319let challenge = new Uint8Array([1, 2, 3, 4, 5, 6, 7, 8]); 1320let authType = userAuth.UserAuthType.FACE; 1321let authTrustLevel = userAuth.AuthTrustLevel.ATL1; 1322 1323try { 1324 let auth = userAuth.getAuthInstance(challenge, authType, authTrustLevel); 1325 auth.start(); 1326 console.info('authV9 start auth success'); 1327} catch (error) { 1328 console.error(`authV9 start auth failed, error = ${error}`); 1329} 1330``` 1331 1332### cancel<sup>(deprecated)</sup> 1333 1334cancel : () => void 1335 1336Cancels this authentication. 1337 1338> **NOTE**<br> 1339> 1340> - This API is supported since API version 9 and deprecated since API version 10. 1341> - Use the [AuthInstance](#authinstancedeprecated) instance obtained to call this API. The [AuthInstance](#authinstancedeprecated) instance must be the instance being authenticated. 1342 1343**Required permissions**: ohos.permission.ACCESS_BIOMETRIC 1344 1345**System capability**: SystemCapability.UserIAM.UserAuth.Core 1346 1347**Error codes** 1348 1349For details about the error codes, see [User Authentication Error Codes](errorcode-useriam.md). 1350 1351| ID| Error Message| 1352| -------- | ------- | 1353| 201 | Permission denied. | 1354| 401 | Parameter error. | 1355| 12500002 | General operation error. | 1356 1357**Example** 1358 1359```ts 1360import { userAuth } from '@kit.UserAuthenticationKit'; 1361 1362let challenge = new Uint8Array([1, 2, 3, 4, 5, 6, 7, 8]); 1363let authType = userAuth.UserAuthType.FACE; 1364let authTrustLevel = userAuth.AuthTrustLevel.ATL1; 1365 1366try { 1367 let auth = userAuth.getAuthInstance(challenge, authType, authTrustLevel); 1368 auth.cancel(); 1369 console.info('cancel auth success'); 1370} catch (error) { 1371 console.error(`cancel auth failed, error = ${error}`); 1372} 1373``` 1374 1375## userAuth.getAuthInstance<sup>(deprecated)</sup> 1376 1377getAuthInstance(challenge : Uint8Array, authType : UserAuthType, authTrustLevel : AuthTrustLevel): AuthInstance 1378 1379Obtains an **AuthInstance** instance for user authentication. 1380 1381> **NOTE**<br> 1382> 1383> - This API is supported since API version 9 and deprecated since API version 10. Use [getUserAuthInstance](#userauthgetuserauthinstance10) instead. 1384> - An **AuthInstance** instance can be used for authentication only once. 1385 1386 1387**System capability**: SystemCapability.UserIAM.UserAuth.Core 1388 1389**Parameters** 1390 1391| Name | Type | Mandatory| Description | 1392| -------------- | ---------------------------------------- | ---- | ------------------------ | 1393| challenge | Uint8Array | Yes | Challenge value. It cannot exceed 32 bytes and can be passed in Uint8Array([]) format.| 1394| authType | [UserAuthType](#userauthtype8) | Yes | Authentication type. Currently, **FACE** and **FINGERPRINT** are supported.| 1395| authTrustLevel | [AuthTrustLevel](#authtrustlevel8) | Yes | Authentication trust level. | 1396 1397**Return value** 1398 1399| Type | Description | 1400| --------------------------------------- | ------------ | 1401| [AuthInstance](#authinstancedeprecated) | **AuthInstance** instance obtained.| 1402 1403**Error codes** 1404 1405For details about the error codes, see [User Authentication Error Codes](errorcode-useriam.md). 1406 1407| ID| Error Message| 1408| -------- | ------- | 1409| 401 | Parameter error. | 1410| 12500002 | General operation error. | 1411| 12500005 | The authentication type is not supported. | 1412| 12500006 | The authentication trust level is not supported. | 1413 1414**Example** 1415 1416```ts 1417import { userAuth } from '@kit.UserAuthenticationKit'; 1418 1419let challenge = new Uint8Array([1, 2, 3, 4, 5, 6, 7, 8]); 1420let authType = userAuth.UserAuthType.FACE; 1421let authTrustLevel = userAuth.AuthTrustLevel.ATL1; 1422 1423try { 1424 let auth = userAuth.getAuthInstance(challenge, authType, authTrustLevel); 1425 console.info('let auth instance success'); 1426} catch (error) { 1427 console.error(`get auth instance success failed, error = ${error}`); 1428} 1429``` 1430 1431## userAuth.getAvailableStatus<sup>9+</sup> 1432 1433getAvailableStatus(authType : UserAuthType, authTrustLevel : AuthTrustLevel): void 1434 1435Checks whether the specified authentication capability is supported. 1436 1437**Required permissions**: ohos.permission.ACCESS_BIOMETRIC 1438 1439**Atomic service API**: This API can be used in atomic services since API version 12. 1440 1441**System capability**: SystemCapability.UserIAM.UserAuth.Core 1442 1443**Parameters** 1444 1445| Name | Type | Mandatory| Description | 1446| -------------- | ---------------------------------- | ---- | -------------------------- | 1447| authType | [UserAuthType](#userauthtype8) | Yes | Authentication type. PIN is supported since API version 11.| 1448| authTrustLevel | [AuthTrustLevel](#authtrustlevel8) | Yes | Authentication trust level. | 1449 1450> The mechanism for returning the error code is as follows: 1451> 1452> - Error code 12500005 is returned if the authentication executor is not registered and the specified authentication capability is not supported. 1453> - Error code 12500006 is returned if the authentication executor has been registered, the authentication functionality is not disabled, but the authentication trust level is lower than that specified by the service. 1454> - Error code 12500010 is returned if the authentication executor has been registered, the authentication functionality is not disabled, but the user has not enrolled credential. 1455> - Error code 12500013 is returned if the authentication executor has been registered, the authentication functionality is not disabled, but the password has expired. 1456 1457> **NOTE** 1458> - If **getAvailableStatus** is called to check whether lock screen password authentication at ATL4 is supported for a user who has enrolled a 4-digit PIN as the lock screen password (the authentication trust level is ATL3), error code 12500010 will be returned. 1459 1460**Error codes** 1461 1462For details about the error codes, see [User Authentication Error Codes](errorcode-useriam.md). 1463 1464| ID| Error Message| 1465| -------- | ------- | 1466| 201 | Permission denied. | 1467| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. | 1468| 12500002 | General operation error. | 1469| 12500005 | The authentication type is not supported. | 1470| 12500006 | The authentication trust level is not supported. | 1471| 12500010 | The type of credential has not been enrolled. | 1472| 12500013 | Operation failed because of PIN expired. | 1473 1474**Example** 1475 1476```ts 1477import { userAuth } from '@kit.UserAuthenticationKit'; 1478 1479try { 1480 userAuth.getAvailableStatus(userAuth.UserAuthType.FACE, userAuth.AuthTrustLevel.ATL3); 1481 console.info('current auth trust level is supported'); 1482} catch (error) { 1483 console.error(`current auth trust level is not supported, error = ${error}`); 1484} 1485``` 1486 1487## UserAuthResultCode<sup>9+</sup> 1488 1489Enumerates the authentication result codes. 1490 1491**System capability**: SystemCapability.UserIAM.UserAuth.Core 1492 1493| Name | Value | Description | 1494| ----------------------- | ------ | -------------------- | 1495| SUCCESS<sup>9+</sup> | 12500000 | The operation is successful. | 1496| FAIL<sup>9+</sup> | 12500001 | The authentication failed. | 1497| GENERAL_ERROR<sup>9+</sup> | 12500002 | A general operation error occurred. | 1498| CANCELED<sup>9+</sup> | 12500003 | The authentication is canceled. | 1499| TIMEOUT<sup>9+</sup> | 12500004 | The authentication has timed out. | 1500| TYPE_NOT_SUPPORT<sup>9+</sup> | 12500005 | The authentication type is not supported. | 1501| TRUST_LEVEL_NOT_SUPPORT<sup>9+</sup> | 12500006 | The authentication trust level is not supported. | 1502| BUSY<sup>9+</sup> | 12500007 | The system does not respond. | 1503| INVALID_PARAMETERS<sup>20+</sup> | 12500008 | Parameter verification failed. | 1504| LOCKED<sup>9+</sup> | 12500009 | The authentication executor is locked. | 1505| NOT_ENROLLED<sup>9+</sup> | 12500010 | The user has not enrolled the specified system identity authentication credential.| 1506| CANCELED_FROM_WIDGET<sup>10+</sup> | 12500011 | The user cancels the system authentication and selects a custom authentication of the application. The caller needs to launch the custom authentication page.| 1507| PIN_EXPIRED<sup>12+</sup> | 12500013 | The authentication failed because the lock screen password has expired.| 1508 1509## UserAuth<sup>(deprecated)</sup> 1510 1511Provides APIs for managing the **UserAuth** object. 1512 1513### constructor<sup>(deprecated)</sup> 1514 1515constructor() 1516 1517A constructor used to create a **UserAuth** instance. 1518 1519> **NOTE**<br> 1520> This API is supported since API version 8 and deprecated since API version 9. Use [getAuthInstance](#userauthgetauthinstancedeprecated) instead. 1521 1522**System capability**: SystemCapability.UserIAM.UserAuth.Core 1523 1524**Example** 1525 1526```ts 1527import { userAuth } from '@kit.UserAuthenticationKit'; 1528 1529let auth = new userAuth.UserAuth(); 1530``` 1531 1532### getVersion<sup>(deprecated)</sup> 1533 1534getVersion() : number 1535 1536Obtains the version of this authenticator. 1537 1538> **NOTE**<br> 1539> This API is supported since API version 8 and deprecated since API version 9. 1540 1541**Required permissions**: ohos.permission.ACCESS_BIOMETRIC 1542 1543**System capability**: SystemCapability.UserIAM.UserAuth.Core 1544 1545**Return value** 1546 1547| Type | Description | 1548| ------ | ---------------------- | 1549| number | Authenticator version obtained.| 1550 1551**Example** 1552 1553```ts 1554import { userAuth } from '@kit.UserAuthenticationKit'; 1555 1556let auth = new userAuth.UserAuth(); 1557let version = auth.getVersion(); 1558console.info(`auth version = ${version}`); 1559``` 1560 1561### getAvailableStatus<sup>(deprecated)</sup> 1562 1563getAvailableStatus(authType : UserAuthType, authTrustLevel : AuthTrustLevel) : number 1564 1565Checks whether the specified authentication capability is supported. 1566 1567> **NOTE**<br> 1568> This API is supported since API version 8 and deprecated since API version 9. Use [getAvailableStatus](#userauthgetavailablestatus9) instead. 1569 1570**Required permissions**: ohos.permission.ACCESS_BIOMETRIC 1571 1572**System capability**: SystemCapability.UserIAM.UserAuth.Core 1573 1574**Parameters** 1575 1576| Name | Type | Mandatory| Description | 1577| -------------- | ---------------------------------- | ---- | -------------------------- | 1578| authType | [UserAuthType](#userauthtype8) | Yes | Authentication type. Currently, **FACE** and **FINGERPRINT** are supported.| 1579| authTrustLevel | [AuthTrustLevel](#authtrustlevel8) | Yes | Authentication trust level. | 1580 1581**Return value** 1582 1583| Type | Description | 1584| ------ | ------------------------------------------------------------ | 1585| number | Query result. If the authentication capability is supported, **SUCCESS** is returned. Otherwise, a [ResultCode](#resultcodedeprecated) is returned.| 1586 1587**Example** 1588 1589```ts 1590import { userAuth } from '@kit.UserAuthenticationKit'; 1591 1592let auth = new userAuth.UserAuth(); 1593let checkCode = auth.getAvailableStatus(userAuth.UserAuthType.FACE, userAuth.AuthTrustLevel.ATL1); 1594if (checkCode == userAuth.ResultCode.SUCCESS) { 1595 console.info('check auth support success'); 1596} else { 1597 console.error(`check auth support fail, code = ${checkCode}`); 1598} 1599``` 1600 1601### auth<sup>(deprecated)</sup> 1602 1603auth(challenge: Uint8Array, authType: UserAuthType, authTrustLevel: AuthTrustLevel, callback: IUserAuthCallback): Uint8Array 1604 1605Starts user authentication. This API uses a callback to return the result. 1606 1607> **NOTE**<br> 1608> This API is supported since API version 8 and deprecated since API version 9. Use [start](#startdeprecated) instead. 1609 1610**Required permissions**: ohos.permission.ACCESS_BIOMETRIC 1611 1612**System capability**: SystemCapability.UserIAM.UserAuth.Core 1613 1614**Parameters** 1615 1616| Name | Type | Mandatory| Description | 1617| -------------- | ---------------------------------------- | ---- | ------------------------ | 1618| challenge | Uint8Array | Yes | Challenge value, which can be passed in Uint8Array([]) format.| 1619| authType | [UserAuthType](#userauthtype8) | Yes | Authentication type. Currently, **FACE** and **FINGERPRINT** are supported.| 1620| authTrustLevel | [AuthTrustLevel](#authtrustlevel8) | Yes | Authentication trust level. | 1621| callback | [IUserAuthCallback](#iuserauthcallbackdeprecated) | Yes | Callback used to return the result. | 1622 1623**Return value** 1624 1625| Type | Description | 1626| ---------- | ------------------------------------------------------------ | 1627| Uint8Array | Context ID, which is used as the input parameter of [cancelAuth](#cancelauthdeprecated).| 1628 1629**Example** 1630 1631```ts 1632import { userAuth } from '@kit.UserAuthenticationKit'; 1633 1634let auth = new userAuth.UserAuth(); 1635let challenge = new Uint8Array([]); 1636auth.auth(challenge, userAuth.UserAuthType.FACE, userAuth.AuthTrustLevel.ATL1, { 1637 onResult: (result, extraInfo) => { 1638 try { 1639 console.info(`auth onResult result = ${result}`); 1640 console.info(`auth onResult extraInfo = ${JSON.stringify(extraInfo)}`); 1641 if (result == userAuth.ResultCode.SUCCESS) { 1642 // Add the logic to be executed when the authentication is successful. 1643 } else { 1644 // Add the logic to be executed when the authentication fails. 1645 } 1646 } catch (error) { 1647 console.error(`auth onResult error = ${error}`); 1648 } 1649 } 1650}); 1651``` 1652 1653### cancelAuth<sup>(deprecated)</sup> 1654 1655cancelAuth(contextID : Uint8Array) : number 1656 1657Cancels the authentication based on the context ID. 1658 1659> **NOTE**<br> 1660> This API is supported since API version 8 and deprecated since API version 9. Use [cancel](#canceldeprecated) instead. 1661 1662**Required permissions**: ohos.permission.ACCESS_BIOMETRIC 1663 1664**System capability**: SystemCapability.UserIAM.UserAuth.Core 1665 1666**Parameters** 1667 1668| Name | Type | Mandatory| Description | 1669| --------- | ---------- | ---- | ------------------------------------------ | 1670| contextID | Uint8Array | Yes | Context ID, which is obtained by [auth](#authdeprecated).| 1671 1672**Return value** 1673 1674| Type | Description | 1675| ------ | ------------------------ | 1676| number | Returns **SUCCESS** if the cancellation is successful. Returns a [ResultCode](#resultcodedeprecated) otherwise.| 1677 1678**Example** 1679 1680```ts 1681import { userAuth } from '@kit.UserAuthenticationKit'; 1682 1683// contextId can be obtained via auth(). In this example, it is defined here. 1684let contextId = new Uint8Array([0, 1, 2, 3, 4, 5, 6, 7]); 1685let auth = new userAuth.UserAuth(); 1686let cancelCode = auth.cancelAuth(contextId); 1687if (cancelCode == userAuth.ResultCode.SUCCESS) { 1688 console.info('cancel auth success'); 1689} else { 1690 console.error('cancel auth fail'); 1691} 1692``` 1693 1694## IUserAuthCallback<sup>(deprecated)</sup> 1695 1696Provides callbacks to return the authentication result. 1697 1698> **NOTE**<br> 1699> This API is supported since API version 8 and deprecated since API version 9. Use [AuthEvent](#autheventdeprecated) instead. 1700 1701### onResult<sup>(deprecated)</sup> 1702 1703onResult: (result : number, extraInfo : AuthResult) => void 1704 1705Called to return the authentication result. 1706 1707> **NOTE**<br> 1708> This API is supported since API version 8 and deprecated since API version 9. Use [callback](#callbackdeprecated) instead. 1709 1710**System capability**: SystemCapability.UserIAM.UserAuth.Core 1711 1712**Parameters** 1713 1714| Name | Type | Mandatory| Description | 1715| --------- | -------------------------- | ---- | ------------------------------------------------ | 1716| result | number | Yes | Authentication result. For details, see [ResultCode](#resultcodedeprecated).| 1717| 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**.| 1718 1719**Example** 1720 1721```ts 1722import { userAuth } from '@kit.UserAuthenticationKit'; 1723 1724let auth = new userAuth.UserAuth(); 1725let challenge = new Uint8Array([]); 1726auth.auth(challenge, userAuth.UserAuthType.FACE, userAuth.AuthTrustLevel.ATL1, { 1727 onResult: (result, extraInfo) => { 1728 try { 1729 console.info(`auth onResult result = ${result}`); 1730 console.info(`auth onResult extraInfo = ${JSON.stringify(extraInfo)}`); 1731 if (result == userAuth.ResultCode.SUCCESS) { 1732 // Add the logic to be executed when the authentication is successful. 1733 } else { 1734 // Add the logic to be executed when the authentication fails. 1735 } 1736 } catch (error) { 1737 console.error(`auth onResult error = ${error}`); 1738 } 1739 } 1740}); 1741``` 1742 1743### onAcquireInfo<sup>(deprecated)</sup> 1744 1745onAcquireInfo ?: (module : number, acquire : number, extraInfo : any) => void 1746 1747Called to acquire authentication tip information. This API is optional. 1748 1749> **NOTE**<br> 1750> This API is supported since API version 8 and deprecated since API version 9. Use [callback](#callbackdeprecated) instead. 1751 1752**System capability**: SystemCapability.UserIAM.UserAuth.Core 1753 1754**Parameters** 1755 1756| Name | Type | Mandatory| Description | 1757| --------- | ------ | ---- | ------------------------------ | 1758| module | number | Yes | ID of the module that sends the tip information. | 1759| acquire | number | Yes | Authentication tip information.| 1760| extraInfo | any | Yes | Reserved field. | 1761 1762**Example** 1763 1764```ts 1765import { userAuth } from '@kit.UserAuthenticationKit'; 1766 1767let auth = new userAuth.UserAuth(); 1768let challenge = new Uint8Array([]); 1769auth.auth(challenge, userAuth.UserAuthType.FACE, userAuth.AuthTrustLevel.ATL1, { 1770 onResult: (result, extraInfo) => { 1771 try { 1772 console.info(`auth onResult result = ${result}`); 1773 console.info(`auth onResult extraInfo = ${JSON.stringify(extraInfo)}`); 1774 if (result == userAuth.ResultCode.SUCCESS) { 1775 // Add the logic to be executed when the authentication is successful. 1776 } else { 1777 // Add the logic to be executed when the authentication fails. 1778 } 1779 } catch (error) { 1780 console.error(`auth onResult error = ${error}`); 1781 } 1782 }, 1783 onAcquireInfo: (module, acquire, extraInfo : userAuth.AuthResult) => { 1784 try { 1785 console.info(`auth onAcquireInfo module = ${module}`); 1786 console.info(`auth onAcquireInfo acquire = ${acquire}`); 1787 console.info(`auth onAcquireInfo extraInfo = ${JSON.stringify(extraInfo)}`); 1788 } catch (error) { 1789 console.error(`auth onAcquireInfo error = ${error}`); 1790 } 1791 } 1792}); 1793``` 1794 1795## AuthResult<sup>(deprecated)</sup> 1796 1797Represents the authentication result object. 1798 1799> **NOTE**<br> 1800> This API is supported since API version 8 and deprecated since API version 9. Use [AuthResultInfo](#authresultinfodeprecated) instead. 1801 1802**System capability**: SystemCapability.UserIAM.UserAuth.Core 1803 1804| Name | Type | Mandatory| Description | 1805| ------------ | ---------- | ---- | -------------------| 1806| token | Uint8Array | No | Authentication token information.| 1807| remainTimes | number | No | Number of remaining authentication operations.| 1808| freezingTime | number | No | Time for which the authentication operation is frozen.| 1809 1810## ResultCode<sup>(deprecated)</sup> 1811 1812Enumerates the authentication result codes. 1813 1814> **NOTE**<br> 1815> This object is deprecated since API version 9. Use [UserAuthResultCode](#userauthresultcode9) instead. 1816 1817**System capability**: SystemCapability.UserIAM.UserAuth.Core 1818 1819| Name | Value| Description | 1820| ----------------------- | ------ | -------------------- | 1821| SUCCESS | 0 | The operation is successful. | 1822| FAIL | 1 | The authentication failed. | 1823| GENERAL_ERROR | 2 | A general operation error occurred. | 1824| CANCELED | 3 | The authentication is canceled. | 1825| TIMEOUT | 4 | The authentication timed out. | 1826| TYPE_NOT_SUPPORT | 5 | The authentication type is not supported. | 1827| TRUST_LEVEL_NOT_SUPPORT | 6 | The authentication trust level is not supported. | 1828| BUSY | 7 | Indicates the busy state. | 1829| INVALID_PARAMETERS | 8 | Invalid parameters are detected. | 1830| LOCKED | 9 | The authentication executor is locked. | 1831| NOT_ENROLLED | 10 | The user has not enrolled the authentication information.| 1832 1833## FaceTips<sup>(deprecated)</sup> 1834 1835Enumerates the tip codes used during the facial authentication process. 1836 1837> **NOTE**<br> 1838> This API is supported since API version 8 and deprecated since API version 11. 1839 1840**System capability**: SystemCapability.UserIAM.UserAuth.Core 1841 1842| Name | Value | Description | 1843| ----------------------------- | ------ | ------------------------------------ | 1844| FACE_AUTH_TIP_TOO_BRIGHT | 1 | The obtained facial image is too bright due to high illumination. | 1845| FACE_AUTH_TIP_TOO_DARK | 2 | The obtained facial image is too dark due to low illumination. | 1846| FACE_AUTH_TIP_TOO_CLOSE | 3 | The face is too close to the device. | 1847| FACE_AUTH_TIP_TOO_FAR | 4 | The face is too far away from the device. | 1848| FACE_AUTH_TIP_TOO_HIGH | 5 | Only the upper part of the face is captured because the device is angled too high. | 1849| FACE_AUTH_TIP_TOO_LOW | 6 | Only the lower part of the face is captured because the device is angled too low. | 1850| FACE_AUTH_TIP_TOO_RIGHT | 7 | Only the right part of the face is captured because the device is deviated to the right. | 1851| FACE_AUTH_TIP_TOO_LEFT | 8 | Only the left part of the face is captured because the device is deviated to the left. | 1852| FACE_AUTH_TIP_TOO_MUCH_MOTION | 9 | The face moves too fast during facial information collection.| 1853| FACE_AUTH_TIP_POOR_GAZE | 10 | The face is not facing the camera. | 1854| FACE_AUTH_TIP_NOT_DETECTED | 11 | No face is detected. | 1855 1856 1857## FingerprintTips<sup>(deprecated)</sup> 1858 1859Enumerates the tip codes used during the fingerprint authentication process. 1860 1861> **NOTE**<br> 1862> This API is supported since API version 8 and deprecated since API version 11. 1863 1864**System capability**: SystemCapability.UserIAM.UserAuth.Core 1865 1866| Name | Value | Description | 1867| --------------------------------- | ------ | -------------------------------------------------- | 1868| FINGERPRINT_AUTH_TIP_GOOD | 0 | The obtained fingerprint image is in good condition. | 1869| FINGERPRINT_AUTH_TIP_DIRTY | 1 | Large fingerprint image noise is detected due to suspicious or detected dirt on the sensor.| 1870| FINGERPRINT_AUTH_TIP_INSUFFICIENT | 2 | The noise of the fingerprint image is too large to be processed. | 1871| FINGERPRINT_AUTH_TIP_PARTIAL | 3 | Incomplete fingerprint image is detected. | 1872| FINGERPRINT_AUTH_TIP_TOO_FAST | 4 | The fingerprint image is incomplete due to fast movement. | 1873| FINGERPRINT_AUTH_TIP_TOO_SLOW | 5 | Failed to obtain the fingerprint image because the finger seldom moves. | 1874 1875 1876## UserAuthType<sup>8+</sup> 1877 1878Enumerates the identity authentication types. 1879 1880**Atomic service API**: This API can be used in atomic services since API version 12. 1881 1882**System capability**: SystemCapability.UserIAM.UserAuth.Core 1883 1884| Name | Value | Description | 1885| ----------- | ---- | ---------- | 1886| PIN<sup>10+</sup> | 1 | PIN authentication.| 1887| FACE | 2 | Facial authentication.| 1888| FINGERPRINT | 4 | Fingerprint authentication.| 1889 1890## AuthTrustLevel<sup>8+</sup> 1891 1892Enumerates the trust levels of the authentication result. 1893 1894For typical use cases, see [Principles for Classifying Biometric Authentication Trust Levels](../../security/UserAuthenticationKit/user-authentication-overview.md#principles-for-classifying-biometric-authentication-trust-levels). 1895 1896**Atomic service API**: This API can be used in atomic services since API version 12. 1897 1898**System capability**: SystemCapability.UserIAM.UserAuth.Core 1899 1900| Name| Value | Description | 1901| ---- | ----- | ------------------------------------------------------------ | 1902| ATL1 | 10000 | Authentication trust level 1. The authentication of this level can identify individual users and provides limited liveness detection capabilities. It is applicable to scenarios such as service risk control and access to common personal data.| 1903| ATL2 | 20000 | Authentication trust level 2. The authentication of this level can accurately identify individual users and provides regular liveness detection capabilities. It is applicable to scenarios such as device unlocking and application login.| 1904| ATL3 | 30000 | Authentication trust level 3. The authentication of this level can accurately identify individual users and provides strong liveness detection capabilities. It is applicable to scenarios such as device unlocking.| 1905| ATL4 | 40000 | Authentication trust level 4. The authentication of this level can accurately identify individual users and provides powerful liveness detection capabilities. It is applicable to scenarios such as small-amount payment.| 1906 1907## SecureLevel<sup>(deprecated)</sup> 1908 1909type SecureLevel = string 1910 1911Enumerates the authentication security levels. 1912 1913**NOTE**<br>This API is supported since API version 6 and deprecated since API version 8. 1914 1915**System capability**: SystemCapability.UserIAM.UserAuth.Core 1916 1917| Type| Description | 1918| ---- | ------------------------------------------------------------ | 1919| string | Authentication security level, which can be any of the following:| | | <br>\- **S1**: 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.<br>\- **S2**: 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.<br>\- **S3**: 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.<br>\- **S4**: 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.| 1920 1921## AuthType<sup>(deprecated)</sup> 1922 1923type AuthType = string 1924 1925Enumerates the authentication types. 1926 1927**NOTE**<br>This API is supported since API version 6 and deprecated since API version 8. 1928 1929**System capability**: SystemCapability.UserIAM.UserAuth.Core 1930 1931| Type| Description | 1932| ---- | ------------------------------------------------------------ | 1933| string | Authentication type, which can be any of the following:| <br>\- **ALL**: reserved and not supported by the current version.<br>\- **FACE_ONLY**: facial authentication.| 1934 1935## userAuth.getAuthenticator<sup>(deprecated)</sup> 1936 1937getAuthenticator(): Authenticator 1938 1939Obtains an **Authenticator** instance for user authentication. 1940 1941> **NOTE**<br> 1942> This API is deprecated since API version 8. Use [constructor](#constructordeprecated) instead. 1943 1944**System capability**: SystemCapability.UserIAM.UserAuth.Core 1945 1946**Return value** 1947 1948| Type | Description | 1949| ----------------------------------------- | ------------ | 1950| [Authenticator](#authenticatordeprecated) | **Authenticator** instance obtained.| 1951 1952**Example** 1953 ```ts 1954 import { userAuth } from '@kit.UserAuthenticationKit'; 1955 1956 let authenticator = userAuth.getAuthenticator(); 1957 ``` 1958 1959## Authenticator<sup>(deprecated)</sup> 1960 1961Provides APIs for managing the **Authenticator** object. 1962 1963> **NOTE**<br> 1964> This API is deprecated since API version 8. Use [UserAuth](#userauthdeprecated) instead. 1965 1966### execute<sup>(deprecated)</sup> 1967 1968execute(type: AuthType, level: SecureLevel, callback: AsyncCallback<number>): void 1969 1970Starts user authentication. This API uses an asynchronous callback to return the result. 1971 1972> **NOTE**<br> 1973> This API is deprecated since API version 8. Use [auth](#authdeprecated) instead. 1974 1975**Required permissions**: ohos.permission.ACCESS_BIOMETRIC 1976 1977**System capability**: SystemCapability.UserIAM.UserAuth.Core 1978 1979**Parameters** 1980 1981| Name | Type | Mandatory| Description | 1982| -------- | --------------------------- | ---- |-----------------------------------------------------------------------------------------------------------------------| 1983| type | AuthType | Yes | Authentication type. Currently, only **FACE_ONLY** is supported.<br>**ALL** is reserved and not supported by the current version. | 1984| 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.| 1985| callback | AsyncCallback<number> | Yes| Callback used to return the result. **number** indicates the [AuthenticationResult](#authenticationresultdeprecated).| 1986 1987**Example** 1988 1989```ts 1990import { userAuth } from '@kit.UserAuthenticationKit'; 1991 1992let authenticator = userAuth.getAuthenticator(); 1993authenticator.execute('FACE_ONLY', 'S2', (error, code)=>{ 1994 if (code === userAuth.ResultCode.SUCCESS) { 1995 console.info('auth success'); 1996 return; 1997 } 1998 console.error(`auth fail, code = ${code}`); 1999}); 2000``` 2001 2002 2003### execute<sup>(deprecated)</sup> 2004 2005execute(type : AuthType, level : SecureLevel): Promise<number> 2006 2007Starts user authentication. This API uses a promise to return the result. 2008 2009> **NOTE**<br> 2010> This API is deprecated since API version 8. Use [auth](#authdeprecated) instead. 2011 2012**Required permissions**: ohos.permission.ACCESS_BIOMETRIC 2013 2014**System capability**: SystemCapability.UserIAM.UserAuth.Core 2015 2016**Parameters** 2017 2018| Name| Type | Mandatory| Description | 2019| ------ | ------ | ---- |-----------------------------------------------------------------------------------------------------------------------| 2020| type | AuthType | Yes | Authentication type. Currently, only **FACE_ONLY** is supported.<br>**ALL** is reserved and not supported by the current version. | 2021| 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.| 2022 2023**Return value** 2024 2025| Type | Description | 2026| --------------------- | ------------------------------------------------------------ | 2027| Promise<number> | Promise used to return the authentication result, which is a number. For details, see [AuthenticationResult](#authenticationresultdeprecated).| 2028 2029**Example** 2030 2031```ts 2032import { userAuth } from '@kit.UserAuthenticationKit'; 2033 2034try { 2035 let authenticator = userAuth.getAuthenticator(); 2036 authenticator.execute('FACE_ONLY', 'S2').then((code)=>{ 2037 console.info('auth success'); 2038 }) 2039} catch (error) { 2040 console.error(`auth fail, code = ${error}`); 2041} 2042``` 2043 2044## AuthenticationResult<sup>(deprecated)</sup> 2045 2046Enumerates the authentication results. 2047 2048> **NOTE**<br> 2049> This object is deprecated since API version 8. Use [ResultCode](#resultcodedeprecated) instead. 2050 2051**System capability**: SystemCapability.UserIAM.UserAuth.Core 2052 2053| Name | Value | Description | 2054| ------------------ | ------ | -------------------------- | 2055| NO_SUPPORT | -1 | The device does not support the current authentication mode.| 2056| SUCCESS | 0 | The authentication is successful. | 2057| COMPARE_FAILURE | 1 | The feature comparison failed. | 2058| CANCELED | 2 | The authentication was canceled by the user. | 2059| TIMEOUT | 3 | The authentication has timed out. | 2060| CAMERA_FAIL | 4 | The camera failed to start. | 2061| BUSY | 5 | The authentication service is not available. Try again later. | 2062| INVALID_PARAMETERS | 6 | The authentication parameters are invalid. | 2063| LOCKED | 7 | The user account is locked because the number of authentication failures has reached the threshold.| 2064| NOT_ENROLLED | 8 | No authentication credential is registered. | 2065| GENERAL_ERROR | 100 | Other errors. | 2066