1# 用户认证 2 3>  **说明：** 4> 本模块首批接口从API version 6开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。 5 6 7## 导入模块 8 9```js 10import userIAM_userAuth from '@ohos.userIAM.userAuth'; 11``` 12 13## 完整示例 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 // 此处添加认证成功逻辑 26 }).catch((code)=>{ 27 console.error("auth fail, code = " + code); 28 // 此处添加认证失败逻辑 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 // 此处添加认证成功逻辑 55 } else { 56 // 此处添加认证失败逻辑 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 // 此处添加支持指定类型认证的逻辑 81 } else { 82 console.error("check auth support fail, code = " + checkCode); 83 // 此处添加不支持指定类型认证的逻辑 84 } 85 }, 86 87 cancelAuth() { 88 console.info("start cancel auth"); 89 // contextId通过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> **说明：** 114> 从 API Version 8 开始废弃，建议使用[constructor](#constructor8)替代。 115 116获取Authenticator对象，用于执行用户身份认证。 117 118**需要权限**：ohos.permission.ACCESS_BIOMETRIC 119 120**系统能力**：以下各项对应的系统能力均为SystemCapability.UserIAM.UserAuth.Core 121 122**返回值：** 123| 类型 | 说明 | 124| ----------------------------------------- | ------------ | 125| [Authenticator](#authenticatordeprecated) | 认证器对象。 | 126 127**示例：** 128 ```js 129 let authenticator = userIAM_userAuth.getAuthenticator(); 130 ``` 131 132## Authenticator<sup>(deprecated)</sup> 133 134> **说明：** 135> 从 API Version 8 开始废弃，建议使用[UserAuth](#userauth8)替代。 136 137认证器对象。 138 139 140### execute<sup>(deprecated)</sup> 141 142execute(type: string, level: string, callback: AsyncCallback<number>): void 143 144> **说明：** 145> 从 API Version 8 开始废弃，建议使用[auth](#auth8)替代。 146 147执行用户认证，使用callback方式作为异步方法。 148 149**需要权限**：ohos.permission.ACCESS_BIOMETRIC 150 151**系统能力**：以下各项对应的系统能力均为SystemCapability.UserIAM.UserAuth.Core 152 153**参数：** 154 155| 参数名 | 类型 | 必填 | 说明 | 156| -------- | --------------------------- | ---- | ------------------------------------------------------------ | 157| type | string | 是 | 认证类型，当前只支持FACE_ONLY。<br/>ALL为预留参数，当前版本暂不支持ALL类型的认证。 | 158| level | string | 是 | 安全级别，对应认证的安全级别，有效值为S1（最低）、S2、S3、S4（最高）。<br/>具备3D人脸识别能力的设备支持S3及以下安全级别的认证。<br/>具备2D人脸识别能力的设备支持S2及以下安全级别的认证。 | 159| callback | AsyncCallback<number> | 否 | 回调函数。 | 160 161 callback返回值： 162 163| 类型 | 说明 | 164| ------ | ------------------------------------------------------------ | 165| number | 表示认证结果，参见[AuthenticationResult](#authenticationresultdeprecated)。 | 166 167**示例：** 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> **说明：** 184> 从 API Version 8 开始废弃，建议使用[auth](#auth8)替代。 185 186执行用户认证，使用promise方式作为异步方法。 187 188**需要权限**：ohos.permission.ACCESS_BIOMETRIC 189 190**系统能力**：以下各项对应的系统能力均为SystemCapability.UserIAM.UserAuth.Core 191 192**参数：** 193| 参数名 | 类型 | 必填 | 说明 | 194| ------ | ------ | ---- | ------------------------------------------------------------ | 195| type | string | 是 | 认证类型，当前只支持FACE_ONLY。<br/>ALL为预留参数，当前版本暂不支持ALL类型的认证。 | 196| level | string | 是 | 安全级别，对应认证的安全级别，有效值为S1（最低）、S2、S3、S4（最高）。<br/>具备3D人脸识别能力的设备支持S3及以下安全级别的认证。<br/>具备2D人脸识别能力的设备支持S2及以下安全级别的认证。 | 197 198**返回值：** 199| 类型 | 说明 | 200| --------------------- | ------------------------------------------------------------ | 201| Promise<number> | 返回携带一个number的Promise。number 为认证结果，参见[AuthenticationResult](#authenticationresultdeprecated)。 | 202 203**示例：** 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> **说明：** 217> 从 API Version 8 开始废弃，建议使用[ResultCode](#resultcode8)替代。 218 219表示认证结果的枚举。 220 221**系统能力**：以下各项对应的系统能力均为SystemCapability.UserIAM.UserAuth.Core 222 223| 名称 | 默认值 | 描述 | 224| ------------------ | ------ | -------------------------- | 225| NO_SUPPORT | -1 | 设备不支持当前的认证方式。 | 226| SUCCESS | 0 | 认证成功。 | 227| COMPARE_FAILURE | 1 | 比对失败。 | 228| CANCELED | 2 | 用户取消认证。 | 229| TIMEOUT | 3 | 认证超时。 | 230| CAMERA_FAIL | 4 | 开启相机失败。 | 231| BUSY | 5 | 认证服务忙，请稍后重试。 | 232| INVALID_PARAMETERS | 6 | 认证参数无效。 | 233| LOCKED | 7 | 认证失败次数过多，已锁定。 | 234| NOT_ENROLLED | 8 | 未录入认证凭据。 | 235| GENERAL_ERROR | 100 | 其他错误。 | 236 237## UserAuth<sup>8+</sup> 238 239认证器的对象。 240 241### constructor<sup>8+</sup> 242 243constructor() 244 245表示获取的认证器对象。 246 247**需要权限**：ohos.permission.ACCESS_BIOMETRIC 248 249**系统能力**：以下各项对应的系统能力均为SystemCapability.UserIAM.UserAuth.Core 250 251**返回值：** 252 253| 类型 | 说明 | 254| ---------------------- | -------------------- | 255| [UserAuth](#userauth8) | UserAuth认证器对象。 | 256 257**示例：** 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 269表示获取的认证器版本信息。 270 271**需要权限**：ohos.permission.ACCESS_BIOMETRIC 272 273**系统能力**：以下各项对应的系统能力均为SystemCapability.UserIAM.UserAuth.Core 274 275**返回值：** 276 277| 类型 | 说明 | 278| ------ | ---------------------- | 279| number | 获取的认证器版本信息。 | 280 281**示例：** 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 295表示检查指定的认证等级的认证能力是否可用。 296 297**需要权限**：ohos.permission.ACCESS_BIOMETRIC 298 299**系统能力**：以下各项对应的系统能力均为SystemCapability.UserIAM.UserAuth.Core 300 301**参数：** 302 303| 参数名 | 类型 | 必填 | 说明 | 304| -------------- | ---------------------------------- | ---- | -------------------------- | 305| authType | [UserAuthType](#userauthtype8) | 是 | 认证类型，当前只支持FACE。 | 306| authTrustLevel | [AuthTrustLevel](#authtrustlevel8) | 是 | 认证结果的信任等级。 | 307 308**返回值：** 309 310| 类型 | 说明 | 311| ------ | ------------------------------------------------------------ | 312| number | 获取指定的认证等级的认证能力是否可用的检查结果，返回值参见[ResultCode](#resultcode8)。 | 313 314**示例：** 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 // 此处添加支持指定类型认证的逻辑 324 } else { 325 console.error("check auth support fail, code = " + checkCode); 326 // 此处添加不支持指定类型认证的逻辑 327 } 328 ``` 329 330### auth<sup>8+</sup> 331 332auth(challenge: Uint8Array, authType: UserAuthType, authTrustLevel: AuthTrustLevel, callback: IUserAuthCallback): Uint8Array 333 334表示执行用户认证，使用callback方式作为异步方法。 335 336**需要权限**：ohos.permission.ACCESS_BIOMETRIC 337 338**系统能力**：以下各项对应的系统能力均为SystemCapability.UserIAM.UserAuth.Core 339 340**参数：** 341 342| 参数名 | 类型 | 必填 | 说明 | 343| -------------- | ---------------------------------------- | ---- | ------------------------ | 344| challenge | Uint8Array | 是 | 挑战值，可以填null。 | 345| authType | [UserAuthType](#userauthtype8) | 是 | 认证类型，当前支持FACE。 | 346| authTrustLevel | [AuthTrustLevel](#authtrustlevel8) | 是 | 信任等级。 | 347| callback | [IUserAuthCallback](#iuserauthcallback8) | 是 | 回调函数。 | 348 349**返回值：** 350 351| 类型 | 说明 | 352| ---------- | ------------------------------------------------------------ | 353| Uint8Array | ContextId，作为取消认证[cancelAuth](#cancelauth8)接口的入参。 | 354 355**示例：** 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 // 此处添加认证成功逻辑 368 } else { 369 // 此处添加认证失败逻辑 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 382表示通过contextID取消本次认证操作。 383 384**需要权限**：ohos.permission.ACCESS_BIOMETRIC 385 386**系统能力**：以下各项对应的系统能力均为SystemCapability.UserIAM.UserAuth.Core 387 388**参数：** 389 390| 参数名 | 类型 | 必填 | 说明 | 391| --------- | ---------- | ---- | ------------------------------------------ | 392| contextID | Uint8Array | 是 | 上下文ID信息，通过[auth](#auth8)接口获得。 | 393 394**返回值：** 395 396| 类型 | 说明 | 397| ------ | ------------------------ | 398| number | 取消本次认证操作的结果。 | 399 400**示例：** 401 402 ```js 403 import userIAM_userAuth from '@ohos.userIAM.userAuth'; 404 405 // contextId可通过auth接口获取，此处直接定义 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 417认证过程中回调结果的对象。 418 419### onResult<sup>8+</sup> 420 421onResult: (result : number, extraInfo : AuthResult) => void 422 423表示在认证操作中，获取认证结果。 424 425**系统能力**：以下各项对应的系统能力均为SystemCapability.UserIAM.UserAuth.Core 426 427**参数：** 428 429| 参数名 | 类型 | 必填 | 说明 | 430| --------- | -------------------------- | ---- | ------------------------------------------------------------ | 431| result | number | 是 | 认证结果，参见[ResultCode](#resultcode8)。 | 432| extraInfo | [AuthResult](#authresult8) | 是 | 扩展信息，不同情况下的具体信息，<br/>如果身份验证通过，则在extrainfo中返回用户认证令牌，<br/>如果身份验证失败，则在extrainfo中返回剩余的用户认证次数，<br/>如果身份验证执行器被锁定，则在extrainfo中返回冻结时间。 | 433 434 435**示例：** 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 // 此处添加认证成功逻辑 448 } else { 449 // 此处添加认证失败逻辑 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 472表示在认证过程中，获取提示码信息，非必须实现。 473 474**系统能力**：以下各项对应的系统能力均为SystemCapability.UserIAM.UserAuth.Core 475 476**参数：** 477 478| 参数名 | 类型 | 必填 | 说明 | 479| --------- | ------ | ---- | ------------------------------ | 480| module | number | 是 | 认证执行器的类型。 | 481| acquire | number | 是 | 认证执行器认证过程的交互信息。 | 482| extraInfo | any | 是 | 预留字段。 | 483 484**示例：** 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 // 此处添加认证成功逻辑 497 } else { 498 // 此处添加认证失败逻辑 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 519表示认证结果的对象。 520 521**系统能力**：以下各项对应的系统能力均为SystemCapability.UserIAM.UserAuth.Core 522 523| 名称 | 参数类型 | 必填 | 说明 | 524| ------------ | ---------- | ---- | -------------------- | 525| token | Uint8Array | 否 | 身份认证令牌。 | 526| remainTimes | number | 否 | 剩余的认证操作次数。 | 527| freezingTime | number | 否 | 认证操作的冻结时间。 | 528 529## ResultCode<sup>8+</sup> 530 531表示执行结果的枚举。 532 533**系统能力**：以下各项对应的系统能力均为SystemCapability.UserIAM.UserAuth.Core 534 535| 名称 | 默认值 | 描述 | 536| ----------------------- | ------ | -------------------- | 537| SUCCESS | 0 | 执行成功。 | 538| FAIL | 1 | 执行失败。 | 539| GENERAL_ERROR | 2 | 操作通用错误。 | 540| CANCELED | 3 | 操作取消。 | 541| TIMEOUT | 4 | 操作超时。 | 542| TYPE_NOT_SUPPORT | 5 | 不支持的认证类型。 | 543| TRUST_LEVEL_NOT_SUPPORT | 6 | 不支持的认证等级。 | 544| BUSY | 7 | 忙碌状态。 | 545| INVALID_PARAMETERS | 8 | 无效参数。 | 546| LOCKED | 9 | 认证器已锁定。 | 547| NOT_ENROLLED | 10 | 用户未录入认证信息。 | 548 549 550## FaceTips<sup>8+</sup> 551 552表示人脸认证过程中提示码的枚举。 553 554**系统能力**：以下各项对应的系统能力均为SystemCapability.UserIAM.UserAuth.Core 555 556| 名称 | 默认值 | 描述 | 557| ----------------------------- | ------ | ------------------------------------ | 558| FACE_AUTH_TIP_TOO_BRIGHT | 1 | 光线太强，获取的图像太亮。 | 559| FACE_AUTH_TIP_TOO_DARK | 2 | 光线太暗，获取的图像太暗。 | 560| FACE_AUTH_TIP_TOO_CLOSE | 3 | 人脸距离设备过近。 | 561| FACE_AUTH_TIP_TOO_FAR | 4 | 人脸距离设备过远。 | 562| FACE_AUTH_TIP_TOO_HIGH | 5 | 设备太高，仅获取到人脸上部。 | 563| FACE_AUTH_TIP_TOO_LOW | 6 | 设备太低，仅获取到人脸下部。 | 564| FACE_AUTH_TIP_TOO_RIGHT | 7 | 设备太靠右，仅获取到人脸右部。 | 565| FACE_AUTH_TIP_TOO_LEFT | 8 | 设备太靠左，仅获取到人脸左部。 | 566| FACE_AUTH_TIP_TOO_MUCH_MOTION | 9 | 在图像采集过程中，用户人脸移动太快。 | 567| FACE_AUTH_TIP_POOR_GAZE | 10 | 没有正视摄像头。 | 568| FACE_AUTH_TIP_NOT_DETECTED | 11 | 没有检测到人脸信息。 | 569 570 571## FingerprintTips<sup>8+</sup> 572 573表示指纹认证过程中提示码的枚举。 574 575**系统能力**：以下各项对应的系统能力均为SystemCapability.UserIAM.UserAuth.Core 576 577| 名称 | 默认值 | 描述 | 578| --------------------------------- | ------ | -------------------------------------------------- | 579| FINGERPRINT_AUTH_TIP_GOOD | 0 | 获取的指纹图像良好。 | 580| FINGERPRINT_AUTH_TIP_DIRTY | 1 | 由于传感器上可疑或检测到的污垢，指纹图像噪音过大。 | 581| FINGERPRINT_AUTH_TIP_INSUFFICIENT | 2 | 由于检测到的情况，指纹图像噪声太大，无法处理。 | 582| FINGERPRINT_AUTH_TIP_PARTIAL | 3 | 仅检测到部分指纹图像。 | 583| FINGERPRINT_AUTH_TIP_TOO_FAST | 4 | 快速移动，指纹图像不完整。 | 584| FINGERPRINT_AUTH_TIP_TOO_SLOW | 5 | 缺少运动，指纹图像无法读取。 | 585 586 587## UserAuthType<sup>8+</sup> 588 589表示身份认证的凭据类型枚举。 590 591**系统能力**：以下各项对应的系统能力均为SystemCapability.UserIAM.UserAuth.Core 592 593| 名称 | 默认值 | 描述 | 594| ----------- | ------ | ---------- | 595| FACE | 2 | 人脸认证。 | 596| FINGERPRINT | 4 | 指纹认证。 | 597 598## AuthTrustLevel<sup>8+</sup> 599 600表示认证结果的信任等级枚举。 601 602**系统能力**：以下各项对应的系统能力均为SystemCapability.UserIAM.UserAuth.Core 603 604| 名称 | 默认值 | 描述 | 605| ---- | ------ | ------------------------- | 606| ATL1 | 10000 | 认证结果的信任等级级别1。 | 607| ATL2 | 20000 | 认证结果的信任等级级别2。 | 608| ATL3 | 30000 | 认证结果的信任等级级别3。 | 609| ATL4 | 40000 | 认证结果的信任等级级别4。 |
