1# User Authentication 2 3> **NOTE**<br/> 4> 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. 5 6 7## Modules to Import 8 9```js 10import userIAM_userAuth from '@ohos.userIAM.userAuth'; 11``` 12 13## Example 14 15```js 16// API version 6 17import userIAM_userAuth from '@ohos.userIAM.userAuth'; 18 19export default { 20 startAuth() { 21 console.info("start auth"); 22 let auth = userIAM_userAuth.getAuthenticator(); 23 auth.execute("FACE_ONLY", "S2").then((code)=>{ 24 console.info("auth success"); 25 // Add the logic to be executed when the authentication is successful. 26 }).catch((code)=>{ 27 console.error("auth fail, code = " + code); 28 // Add the logic to be executed when the authentication fails. 29 }); 30 } 31} 32``` 33 34```js 35// API version 8 36import userIAM_userAuth from '@ohos.userIAM.userAuth'; 37let auth = new userIAM_userAuth.UserAuth(); 38 39export default { 40 getVersion() { 41 console.info("start get version"); 42 let version = this.auth.getVersion(); 43 console.info("auth version = " + version); 44 }, 45 46 startAuth() { 47 console.info("start auth"); 48 this.auth.auth(null, userIAM_userAuth.UserAuthType.FACE, userIAM_userAuth.AuthTrustLevel.ATL1, { 49 onResult: (result, extraInfo) => { 50 try { 51 console.info("auth onResult result = " + result); 52 console.info("auth onResult extraInfo = " + JSON.stringify(extraInfo)); 53 if (result == 'SUCCESS') { 54 // Add the logic to be executed when the authentication is successful. 55 } else { 56 // Add the logic to be executed when the authentication fails. 57 } 58 } catch (e) { 59 console.info("auth onResult error = " + e); 60 } 61 }, 62 63 onAcquireInfo: (module, acquire, extraInfo) => { 64 try { 65 console.info("auth onAcquireInfo module = " + module); 66 console.info("auth onAcquireInfo acquire = " + acquire); 67 console.info("auth onAcquireInfo extraInfo = " + JSON.stringify(extraInfo)); 68 } catch (e) { 69 console.info("auth onAcquireInfo error = " + e); 70 } 71 } 72 }); 73 }, 74 75 checkAuthSupport() { 76 console.info("start check auth support"); 77 let checkCode = this.auth.getAvailableStatus(userIAM_userAuth.UserAuthType.FACE, userIAM_userAuth.AuthTrustLevel.ATL1); 78 if (checkCode == userIAM_userAuth.ResultCode.SUCCESS) { 79 console.info("check auth support success"); 80 // Add the logic to be executed if the specified authentication type is supported. 81 } else { 82 console.error("check auth support fail, code = " + checkCode); 83 // Add the logic to be executed if the specified authentication type is not supported. 84 } 85 }, 86 87 cancelAuth() { 88 console.info("start cancel auth"); 89 // Obtain contextId using auth(). 90 let contextId = auth.auth(null, userIAM_userAuth.UserAuthType.FACE, userIAM_userAuth.AuthTrustLevel.ATL1, { 91 onResult: (result, extraInfo) => { 92 console.info("auth onResult result = " + result); 93 }, 94 95 onAcquireInfo: (module, acquire, extraInfo) => { 96 console.info("auth onAcquireInfo module = " + module); 97 } 98 }); 99 let cancelCode = this.auth.cancel(contextId); 100 if (cancelCode == userIAM_userAuth.Result.SUCCESS) { 101 console.info("cancel auth success"); 102 } else { 103 console.error("cancel auth fail"); 104 } 105 } 106} 107``` 108 109## userIAM_userAuth.getAuthenticator<sup>(deprecated)</sup> 110 111getAuthenticator(): Authenticator 112 113> **NOTE**<br/> 114> This API is not longer maintained since API version 8. You are advised to use [constructor](#constructor8). 115 116Obtains an **Authenticator** object for user authentication. 117 118**Required permissions**: ohos.permission.ACCESS_BIOMETRIC 119 120**System capability**: SystemCapability.UserIAM.UserAuth.Core 121 122**Return value** 123| Type | Description | 124| ----------------------------------------- | ------------ | 125| [Authenticator](#authenticatordeprecated) | **Authenticator** object obtained.| 126 127**Example** 128 ```js 129 let authenticator = userIAM_userAuth.getAuthenticator(); 130 ``` 131 132## Authenticator<sup>(deprecated)</sup> 133 134> **NOTE**<br/> 135> This object is not longer maintained since API version 8. You are advised to use [UserAuth](#userauth8). 136 137Provides methods to manage an **Authenticator** object. 138 139 140### execute<sup>(deprecated)</sup> 141 142execute(type: string, level: string, callback: AsyncCallback<number>): void 143 144> **NOTE**<br/> 145> This API is not longer maintained since API version 8. You are advised to use [auth](#auth8). 146 147Performs user authentication. This method uses asynchronous callback to return the result. 148 149**Required permissions**: ohos.permission.ACCESS_BIOMETRIC 150 151**System capability**: SystemCapability.UserIAM.UserAuth.Core 152 153**Parameters** 154 155| Name | Type | Mandatory| Description | 156| -------- | --------------------------- | ---- | ------------------------------------------------------------ | 157| type | string | Yes | Authentication type. Only **FACE_ONLY** is supported.<br>**ALL** is reserved and not supported by the current version.| 158| level | string | 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.| 159| callback | AsyncCallback<number> | No | Callback used to return the result. | 160 161 Parameters returned in callback 162 163| Type | Description | 164| ------ | ------------------------------------------------------------ | 165| number | Authentication result. For details, see [AuthenticationResult](#authenticationresultdeprecated).| 166 167**Example** 168 ```js 169 authenticator.execute("FACE_ONLY", "S2", (code)=>{ 170 if (code == userIAM_userAuth.AuthenticationResult.SUCCESS) { 171 console.info("auth success"); 172 return; 173 } 174 console.error("auth fail, code = " + code); 175 }) 176 ``` 177 178 179### execute<sup>(deprecated)</sup> 180 181execute(type:string, level:string): Promise<number> 182 183> **NOTE**<br/> 184> This API is not longer maintained since API version 8. You are advised to use [auth](#auth8). 185 186Performs user authentication. This method uses a promise to return the result. 187 188**Required permissions**: ohos.permission.ACCESS_BIOMETRIC 189 190**System capability**: SystemCapability.UserIAM.UserAuth.Core 191 192**Parameters** 193| Name| Type | Mandatory| Description | 194| ------ | ------ | ---- | ------------------------------------------------------------ | 195| type | string | Yes | Authentication type. Only **FACE_ONLY** is supported.<br>**ALL** is reserved and not supported by the current version.| 196| level | string | 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.| 197 198**Return value** 199| Type | Description | 200| --------------------- | ------------------------------------------------------------ | 201| Promise<number> | Promise used to return the authentication result, which is a number. For details, see [AuthenticationResult](#authenticationresultdeprecated).| 202 203**Example** 204 205```js 206let authenticator = userIAM_userAuth.getAuthenticator(); 207authenticator.execute("FACE_ONLY", "S2").then((code)=>{ 208 console.info("auth success"); 209}).catch((code)=>{ 210 console.error("auth fail, code = " + code); 211}); 212``` 213 214## AuthenticationResult<sup>(deprecated)</sup> 215 216> **NOTE**<br/> 217> This parameter is not longer maintained since API version 8. You are advised to use [ResultCode](#resultcode8). 218 219Enumerates the authentication results. 220 221**System capability**: SystemCapability.UserIAM.UserAuth.Core 222 223| Name | Default Value| Description | 224| ------------------ | ------ | -------------------------- | 225| NO_SUPPORT | -1 | The device does not support the current authentication mode.| 226| SUCCESS | 0 | The authentication is successful. | 227| COMPARE_FAILURE | 1 | The feature comparison failed. | 228| CANCELED | 2 | The authentication was canceled by the user. | 229| TIMEOUT | 3 | The authentication has timed out. | 230| CAMERA_FAIL | 4 | The camera failed to start. | 231| BUSY | 5 | The authentication service is not available. Try again later. | 232| INVALID_PARAMETERS | 6 | The authentication parameters are invalid. | 233| LOCKED | 7 | The user account is locked because the number of authentication failures has reached the threshold.| 234| NOT_ENROLLED | 8 | No authentication credential is registered. | 235| GENERAL_ERROR | 100 | Other errors. | 236 237## UserAuth<sup>8+</sup> 238 239Provides methods to manage an **Authenticator** object. 240 241### constructor<sup>8+</sup> 242 243constructor() 244 245A constructor used to create an **authenticator** object. 246 247**Required permissions**: ohos.permission.ACCESS_BIOMETRIC 248 249**System capability**: SystemCapability.UserIAM.UserAuth.Core 250 251**Return value** 252 253| Type | Description | 254| ---------------------- | -------------------- | 255| [UserAuth](#userauth8) | **Authenticator** object obtained.| 256 257**Example** 258 259 ```js 260 import userIAM_userAuth from '@ohos.userIAM.userAuth'; 261 262 let auth = new userIAM_userAuth.UserAuth(); 263 ``` 264 265### getVersion<sup>8+</sup> 266 267getVersion() : number 268 269Obtains the authentication executor version. 270 271**Required permissions**: ohos.permission.ACCESS_BIOMETRIC 272 273**System capability**: SystemCapability.UserIAM.UserAuth.Core 274 275**Return value** 276 277| Type | Description | 278| ------ | ---------------------- | 279| number | Authentication executor version obtained.| 280 281**Example** 282 283 ```js 284 import userIAM_userAuth from '@ohos.userIAM.userAuth'; 285 286 let auth = new userIAM_userAuth.UserAuth(); 287 let version = auth.getVersion(); 288 console.info("auth version = " + version); 289 ``` 290 291### getAvailableStatus<sup>8+</sup> 292 293getAvailableStatus(authType : UserAuthType, authTrustLevel : AuthTrustLevel) : number 294 295Checks whether the authentication capability of the specified trust level is available. 296 297**Required permissions**: ohos.permission.ACCESS_BIOMETRIC 298 299**System capability**: SystemCapability.UserIAM.UserAuth.Core 300 301**Parameters** 302 303| Name | Type | Mandatory| Description | 304| -------------- | ---------------------------------- | ---- | -------------------------- | 305| authType | [UserAuthType](#userauthtype8) | Yes | Authentication type. Only **FACE** is supported.| 306| authTrustLevel | [AuthTrustLevel](#authtrustlevel8) | Yes | Trust level of the authentication result. | 307 308**Return value** 309 310| Type | Description | 311| ------ | ------------------------------------------------------------ | 312| number | Whether the authentication capability of the specified trust level is available. For details, see [ResultCode](#resultcode8).| 313 314**Example** 315 316 ```js 317 import userIAM_userAuth from '@ohos.userIAM.userAuth'; 318 319 let auth = new userIAM_userAuth.UserAuth(); 320 let checkCode = auth.getAvailableStatus(userIAM_userAuth.UserAuthType.FACE, userIAM_userAuth.AuthTrustLevel.ATL1); 321 if (checkCode == userIAM_userAuth.ResultCode.SUCCESS) { 322 console.info("check auth support success"); 323 // Add the logic to be executed if the specified authentication type is supported. 324 } else { 325 console.error("check auth support fail, code = " + checkCode); 326 // Add the logic to be executed if the specified authentication type is not supported. 327 } 328 ``` 329 330### auth<sup>8+</sup> 331 332auth(challenge: Uint8Array, authType: UserAuthType, authTrustLevel: AuthTrustLevel, callback: IUserAuthCallback): Uint8Array 333 334Performs user authentication. This method uses a callback to return the result. 335 336**Required permissions**: ohos.permission.ACCESS_BIOMETRIC 337 338**System capability**: SystemCapability.UserIAM.UserAuth.Core 339 340**Parameters** 341 342| Name | Type | Mandatory| Description | 343| -------------- | ---------------------------------------- | ---- | ------------------------ | 344| challenge | Uint8Array | Yes | Challenge value, which can be null. | 345| authType | [UserAuthType](#userauthtype8) | Yes | Authentication type. Only **FACE** is supported.| 346| authTrustLevel | [AuthTrustLevel](#authtrustlevel8) | Yes | Trust level. | 347| callback | [IUserAuthCallback](#iuserauthcallback8) | Yes | Callback used to return the result. | 348 349**Return value** 350 351| Type | Description | 352| ---------- | ------------------------------------------------------------ | 353| Uint8Array | ContextId, which is used as the input parameter of [cancelAuth](#cancelauth8).| 354 355**Example** 356 357 ```js 358 import userIAM_userAuth from '@ohos.userIAM.userAuth'; 359 360 let auth = new userIAM_userAuth.UserAuth(); 361 auth.auth(null, userIAM_userAuth.UserAuthType.FACE, userIAM_userAuth.AuthTrustLevel.ATL1, { 362 onResult: (result, extraInfo) => { 363 try { 364 console.info("auth onResult result = " + result); 365 console.info("auth onResult extraInfo = " + JSON.stringify(extraInfo)); 366 if (result == userIAM_userAuth.ResultCode.SUCCESS) { 367 // Add the logic to be executed when the authentication is successful. 368 } else { 369 // Add the logic to be executed when the authentication fails. 370 } 371 } catch (e) { 372 console.info("auth onResult error = " + e); 373 } 374 } 375 }); 376 ``` 377 378### cancelAuth<sup>8+</sup> 379 380cancelAuth(contextID : Uint8Array) : number 381 382Cancels an authentication. 383 384**Required permissions**: ohos.permission.ACCESS_BIOMETRIC 385 386**System capability**: SystemCapability.UserIAM.UserAuth.Core 387 388**Parameters** 389 390| Name | Type | Mandatory| Description | 391| --------- | ---------- | ---- | ------------------------------------------ | 392| contextID | Uint8Array | Yes | Context ID, which is obtained using [auth](#auth8).| 393 394**Return value** 395 396| Type | Description | 397| ------ | ------------------------ | 398| number | Whether the authentication is canceled.| 399 400**Example** 401 402 ```js 403 import userIAM_userAuth from '@ohos.userIAM.userAuth'; 404 405 // contextId can be obtained using auth(). In this example, it is defined here. 406 let contextId = new Uint8Array([0, 1, 2, 3, 4, 5, 6, 7]); 407 let cancelCode = auth.cancel(contextId); 408 if (cancelCode == userIAM_userAuth.ResultCode.SUCCESS) { 409 console.info("cancel auth success"); 410 } else { 411 console.error("cancel auth fail"); 412 } 413 ``` 414 415## IUserAuthCallback<sup>8+</sup> 416 417Defines the object of the result returned by the callback during authentication. 418 419### onResult<sup>8+</sup> 420 421onResult: (result : number, extraInfo : AuthResult) => void 422 423Obtains the authentication result. 424 425**System capability**: SystemCapability.UserIAM.UserAuth.Core 426 427**Parameters** 428 429| Name | Type | Mandatory| Description | 430| --------- | -------------------------- | ---- | ------------------------------------------------------------ | 431| result | number | Yes | Authentication result obtained. For details, see [ResultCode](#resultcode8). | 432| extraInfo | [AuthResult](#authresult8) | 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**.| 433 434 435**Example** 436 437 ```js 438 import userIAM_userAuth from '@ohos.userIAM.userAuth'; 439 440 let auth = new userIAM_userAuth.UserAuth(); 441 auth.auth(null, userIAM_userAuth.UserAuthType.FACE, userIAM_userAuth.AuthTrustLevel.ATL1, { 442 onResult: (result, extraInfo) => { 443 try { 444 console.info("auth onResult result = " + result); 445 console.info("auth onResult extraInfo = " + JSON.stringify(extraInfo)); 446 if (result == SUCCESS) { 447 // Add the logic to be executed when the authentication is successful. 448 } else { 449 // Add the logic to be executed when the authentication fails. 450 } 451 } catch (e) { 452 console.info("auth onResult error = " + e); 453 } 454 }, 455 456 onAcquireInfo: (module, acquire, extraInfo) => { 457 try { 458 console.info("auth onAcquireInfo module = " + module); 459 console.info("auth onAcquireInfo acquire = " + acquire); 460 console.info("auth onAcquireInfo extraInfo = " + JSON.stringify(extraInfo)); 461 } catch (e) { 462 console.info("auth onAcquireInfo error = " + e); 463 } 464 } 465 }); 466 ``` 467 468### onAcquireInfo<sup>8+</sup> 469 470onAcquireInfo ?: (module : number, acquire : number, extraInfo : any) => void 471 472Obtains the tip code information during authentication. This function is optional. 473 474**System capability**: SystemCapability.UserIAM.UserAuth.Core 475 476**Parameters** 477 478| Name | Type | Mandatory| Description | 479| --------- | ------ | ---- | ------------------------------ | 480| module | number | Yes | Type of the authentication executor. | 481| acquire | number | Yes | Interaction information of the authentication executor during the authentication process.| 482| extraInfo | any | Yes | Reserved field. | 483 484**Example** 485 486 ```js 487 import userIAM_userAuth from '@ohos.userIAM.userAuth'; 488 489 let auth = new userIAM_userAuth.UserAuth(); 490 auth.auth(null, userIAM_userAuth.UserAuthType.FACE, userIAM_userAuth.AuthTrustLevel.ATL1, { 491 onResult: (result, extraInfo) => { 492 try { 493 console.info("auth onResult result = " + result); 494 console.info("auth onResult extraInfo = " + JSON.stringify(extraInfo)); 495 if (result == SUCCESS) { 496 // Add the logic to be executed when the authentication is successful. 497 } else { 498 // Add the logic to be executed when the authentication fails. 499 } 500 } catch (e) { 501 console.info("auth onResult error = " + e); 502 } 503 }, 504 505 onAcquireInfo: (module, acquire, extraInfo) => { 506 try { 507 console.info("auth onAcquireInfo module = " + module); 508 console.info("auth onAcquireInfo acquire = " + acquire); 509 console.info("auth onAcquireInfo extraInfo = " + JSON.stringify(extraInfo)); 510 } catch (e) { 511 console.info("auth onAcquireInfo error = " + e); 512 } 513 } 514 }); 515 ``` 516 517## AuthResult<sup>8+</sup> 518 519Represents the authentication result object. 520 521**System capability**: SystemCapability.UserIAM.UserAuth.Core 522 523| Name | Type | Mandatory| Description | 524| ------------ | ---------- | ---- | -------------------- | 525| token | Uint8Array | No | Identity authentication token. | 526| remainTimes | number | No | Number of remaining authentication operations.| 527| freezingTime | number | No | Time for which the authentication operation is frozen.| 528 529## ResultCode<sup>8+</sup> 530 531Enumerates the operation results. 532 533**System capability**: SystemCapability.UserIAM.UserAuth.Core 534 535| Name | Default Value| Description | 536| ----------------------- | ------ | -------------------- | 537| SUCCESS | 0 | The operation is successful. | 538| FAIL | 1 | The operation failed. | 539| GENERAL_ERROR | 2 | A common operation error occurred. | 540| CANCELED | 3 | The operation is canceled. | 541| TIMEOUT | 4 | The operation timed out. | 542| TYPE_NOT_SUPPORT | 5 | The authentication type is not supported. | 543| TRUST_LEVEL_NOT_SUPPORT | 6 | The authentication trust level is not supported. | 544| BUSY | 7 | Indicates the busy state. | 545| INVALID_PARAMETERS | 8 | Invalid parameters are detected. | 546| LOCKED | 9 | The authentication executor is locked. | 547| NOT_ENROLLED | 10 | The user has not entered the authentication information.| 548 549 550## FaceTips<sup>8+</sup> 551 552Enumerates the tip codes used during the facial authentication process. 553 554**System capability**: SystemCapability.UserIAM.UserAuth.Core 555 556| Name | Default Value| Description | 557| ----------------------------- | ------ | ------------------------------------ | 558| FACE_AUTH_TIP_TOO_BRIGHT | 1 | The obtained facial image is too bright due to high illumination. | 559| FACE_AUTH_TIP_TOO_DARK | 2 | The obtained facial image is too dark due to low illumination. | 560| FACE_AUTH_TIP_TOO_CLOSE | 3 | The face is too close to the device. | 561| FACE_AUTH_TIP_TOO_FAR | 4 | The face is too far away from the device. | 562| FACE_AUTH_TIP_TOO_HIGH | 5 | Only the upper part of the face is captured because the device is angled too high. | 563| FACE_AUTH_TIP_TOO_LOW | 6 | Only the lower part of the face is captured because the device is angled too low. | 564| FACE_AUTH_TIP_TOO_RIGHT | 7 | Only the right part of the face is captured because the device is deviated to the right. | 565| FACE_AUTH_TIP_TOO_LEFT | 8 | Only the left part of the face is captured because the device is deviated to the left. | 566| FACE_AUTH_TIP_TOO_MUCH_MOTION | 9 | The face moves too fast during facial information collection.| 567| FACE_AUTH_TIP_POOR_GAZE | 10 | The face is not facing the camera. | 568| FACE_AUTH_TIP_NOT_DETECTED | 11 | No face is detected. | 569 570 571## FingerprintTips<sup>8+</sup> 572 573Enumerates the tip codes used during the fingerprint authentication process. 574 575**System capability**: SystemCapability.UserIAM.UserAuth.Core 576 577| Name | Default Value| Description | 578| --------------------------------- | ------ | -------------------------------------------------- | 579| FINGERPRINT_AUTH_TIP_GOOD | 0 | The obtained fingerprint image is in good condition. | 580| FINGERPRINT_AUTH_TIP_DIRTY | 1 | Large fingerprint image noise is detected due to suspicious or detected dirt on the sensor.| 581| FINGERPRINT_AUTH_TIP_INSUFFICIENT | 2 | The noise of the fingerprint image is too large to be processed. | 582| FINGERPRINT_AUTH_TIP_PARTIAL | 3 | Incomplete fingerprint image is detected. | 583| FINGERPRINT_AUTH_TIP_TOO_FAST | 4 | The fingerprint image is incomplete due to fast movement. | 584| FINGERPRINT_AUTH_TIP_TOO_SLOW | 5 | Failed to obtain the fingerprint image because the finger seldom moves. | 585 586 587## UserAuthType<sup>8+</sup> 588 589Enumerates the identity authentication types. 590 591**System capability**: SystemCapability.UserIAM.UserAuth.Core 592 593| Name | Default Value| Description | 594| ----------- | ------ | ---------- | 595| FACE | 2 | Facial authentication.| 596| FINGERPRINT | 4 | Fingerprint authentication.| 597 598## AuthTrustLevel<sup>8+</sup> 599 600Enumerates the trust levels of the authentication result. 601 602**System capability**: SystemCapability.UserIAM.UserAuth.Core 603 604| Name| Default Value| Description | 605| ---- | ------ | ------------------------- | 606| ATL1 | 10000 | Trust level 1.| 607| ATL2 | 20000 | Trust level 2.| 608| ATL3 | 30000 | Trust level 3.| 609| ATL4 | 40000 | Trust level 4.| 610
