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