1# @ohos.userIAM.userAuth (用户认证) 2 3提供用户认证能力，可应用于设备解锁、支付、应用登录等身份认证场景。 4 5> **说明：** 6> 本模块首批接口从API version 6开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。 7 8 9## 导入模块 10 11```js 12import userIAM_userAuth from '@ohos.userIAM.userAuth'; 13``` 14 15## AuthResultInfo<sup>9+</sup> 16 17表示认证结果信息。 18 19**系统能力**：以下各项对应的系统能力均为SystemCapability.UserIAM.UserAuth.Core。 20 21| 名称 | 类型 | 必填 | 说明 | 22| ------------ | ---------- | ---- | -------------------- | 23| result | number | 是 | 认证结果。 | 24| token | Uint8Array | 否 | 用户身份认证通过的凭证。 | 25| remainAttempts | number | 否 | 剩余的认证尝试次数。 | 26| lockoutDuration | number | 否 | 认证操作的锁定时长，时间单位为毫秒ms。 | 27 28## TipInfo<sup>9+</sup> 29 30表示认证过程中的提示信息。 31 32**系统能力**：以下各项对应的系统能力均为SystemCapability.UserIAM.UserAuth.Core。 33 34| 名称 | 类型 | 必填 | 说明 | 35| ------------ | ---------- | ---- | -------------------- | 36| module | number | 是 | 发送提示信息的模块标识。 | 37| tip | number | 是 | 认证过程提示信息。 | 38 39## EventInfo<sup>9+</sup> 40 41表示认证过程中事件信息的类型。 42 43**系统能力**：以下各项对应的系统能力均为SystemCapability.UserIAM.UserAuth.Core。 44 45| 取值类型 | 说明 | 46| --------- | ----------------------- | 47| [AuthResultInfo](#authresultinfo9) | 获取到的认证结果信息。 | 48| [TipInfo](#tipinfo9) | 认证过程中的提示信息。 | 49 50## AuthEventKey<sup>9+</sup> 51 52表示认证事件类型的关键字，作为[on](#on9)接口的的参数。 53 54| 取值类型 | 说明 | 55| ---------- | ----------------------- | 56| "result" | [on](#on9)接口第一个参数为"result"时，[callback](#callback9)回调返回认证的结果信息。 | 57| "tip" | [on](#on9)接口第一个参数为"tip"时，[callback](#callback9)回调返回认证操作中的提示信息。 | 58 59## AuthEvent<sup>9+</sup> 60 61认证接口的异步回调对象。 62 63### callback<sup>9+</sup> 64 65callback(result : EventInfo) : void 66 67通过该回调获取认证结果信息或认证过程中的提示信息。 68 69**系统能力**：SystemCapability.UserIAM.UserAuth.Core 70 71**参数：** 72 73| 参数名 | 类型 | 必填 | 说明 | 74| --------- | -------------------------- | ---- | ------------------------------ | 75| result | [EventInfo](#eventinfo9) | 是 | 返回的认证结果信息或提示信息。 | 76 77**示例：** 78 79```js 80import userIAM_userAuth from '@ohos.userIAM.userAuth'; 81 82let challenge = new Uint8Array([1, 2, 3, 4, 5, 6, 7, 8]); 83let authType = userIAM_userAuth.UserAuthType.FACE; 84let authTrustLevel = userIAM_userAuth.AuthTrustLevel.ATL1; 85// 通过callback获取认证结果 86try { 87 let auth = userIAM_userAuth.getAuthInstance(challenge, authType, authTrustLevel); 88 auth.on("result", { 89 callback: (result: userIAM_userAuth.AuthResultInfo) => { 90 console.log("authV9 result " + result.result); 91 console.log("authV9 token " + result.token); 92 console.log("authV9 remainAttempts " + result.remainAttempts); 93 console.log("authV9 lockoutDuration " + result.lockoutDuration); 94 } 95 }); 96 auth.start(); 97 console.log("authV9 start success"); 98} catch (error) { 99 console.log("authV9 error = " + error); 100 // do error 101} 102// 通过callback获取认证过程中的提示信息 103try { 104 let auth = userIAM_userAuth.getAuthInstance(challenge, authType, authTrustLevel); 105 auth.on("tip", { 106 callback : (result : userIAM_userAuth.TipInfo) => { 107 switch (result.tip) { 108 case userIAM_userAuth.FaceTips.FACE_AUTH_TIP_TOO_BRIGHT: 109 // do something; 110 case userIAM_userAuth.FaceTips.FACE_AUTH_TIP_TOO_DARK: 111 // do something; 112 default: 113 // do others 114 } 115 } 116 }); 117 auth.start(); 118 console.log("authV9 start success"); 119} catch (error) { 120 console.log("authV9 error = " + error); 121 // do error 122} 123``` 124 125## AuthInstance<sup>9+</sup> 126 127执行用户认证的对象。 128 129### on<sup>9+</sup> 130 131on : (name : AuthEventKey, callback : AuthEvent) => void 132 133订阅指定类型的用户认证事件。 134 135> **说明：** 136> 使用获取到的[AuthInstance](#authinstance9)对象调用该接口进行订阅。 137 138**系统能力**：SystemCapability.UserIAM.UserAuth.Core 139 140**参数：** 141 142| 参数名 | 类型 | 必填 | 说明 | 143| --------- | -------------------------- | ---- | ------------------------- | 144| name | [AuthEventKey](#autheventkey9) | 是 | 表示认证事件类型，取值为"result"时，回调函数返回认证结果；取值为"tip"时，回调函数返回认证过程中的提示信息。 | 145| callback | [AuthEvent](#authevent9) | 是 | 认证接口的回调函数，用于返回认证结果或认证过程中的提示信息。 | 146 147以下错误码的详细介绍请参见[用户认证错误码](../errorcodes/errorcode-useriam.md) 148 149**错误码：** 150 151| 错误码ID | 错误信息 | 152| -------- | ------- | 153| 401 | Incorrect parameters. | 154| 12500002 | General operation error. | 155 156**示例：** 157 158```js 159import userIAM_userAuth from '@ohos.userIAM.userAuth'; 160 161let challenge = new Uint8Array([1, 2, 3, 4, 5, 6, 7, 8]); 162let authType = userIAM_userAuth.UserAuthType.FACE; 163let authTrustLevel = userIAM_userAuth.AuthTrustLevel.ATL1; 164try { 165 let auth = userIAM_userAuth.getAuthInstance(challenge, authType, authTrustLevel); 166 // 订阅认证结果 167 auth.on("result", { 168 callback: (result: userIAM_userAuth.AuthResultInfo) => { 169 console.log("authV9 result " + result.result); 170 console.log("authV9 token " + result.token); 171 console.log("authV9 remainAttempts " + result.remainAttempts); 172 console.log("authV9 lockoutDuration " + result.lockoutDuration); 173 } 174 }); 175 // 订阅认证过程中的提示信息 176 auth.on("tip", { 177 callback : (result : userIAM_userAuth.TipInfo) => { 178 switch (result.tip) { 179 case userIAM_userAuth.FaceTips.FACE_AUTH_TIP_TOO_BRIGHT: 180 // do something; 181 case userIAM_userAuth.FaceTips.FACE_AUTH_TIP_TOO_DARK: 182 // do something; 183 default: 184 // do others 185 } 186 } 187 }); 188 auth.start(); 189 console.log("authV9 start success"); 190} catch (error) { 191 console.log("authV9 error = " + error); 192 // do error 193} 194``` 195 196### off<sup>9+</sup> 197 198off : (name : AuthEventKey) => void 199 200取消订阅特定类型的认证事件。 201 202> **说明：** 203> 需要使用已经成功订阅事件的[AuthInstance](#authinstance9)对象调用该接口进行取消订阅。 204 205**系统能力**：SystemCapability.UserIAM.UserAuth.Core 206 207| 名称 | 类型 | 必填 | 说明 | 208| --------- | -------------------------- | ---- | ------------------------- | 209| name | [AuthEventKey](#autheventkey9) | 是 | 表示认证事件类型，取值为"result"时，取消订阅认证结果；取值为"tip"时，取消订阅认证过程中的提示信息。 | 210 211以下错误码的详细介绍请参见[用户认证错误码](../errorcodes/errorcode-useriam.md) 212 213**错误码：** 214 215| 错误码ID | 错误信息 | 216| -------- | ------- | 217| 401 | Incorrect parameters. | 218| 12500002 | General operation error. | 219 220**示例：** 221 222```js 223import userIAM_userAuth from '@ohos.userIAM.userAuth'; 224 225let challenge = new Uint8Array([1, 2, 3, 4, 5, 6, 7, 8]); 226let authType = userIAM_userAuth.UserAuthType.FACE; 227let authTrustLevel = userIAM_userAuth.AuthTrustLevel.ATL1; 228let auth; 229try { 230 auth = userIAM_userAuth.getAuthInstance(challenge, authType, authTrustLevel); 231 console.log("get auth instance success"); 232} catch (error) { 233 console.log("get auth instance failed" + error); 234} 235 236try { 237 // 订阅认证结果 238 auth.on("result", { 239 callback: (result: userIAM_userAuth.AuthResultInfo) => { 240 console.log("authV9 result " + result.result); 241 console.log("authV9 token " + result.token); 242 console.log("authV9 remainAttempts " + result.remainAttempts); 243 console.log("authV9 lockoutDuration " + result.lockoutDuration); 244 } 245 }); 246 console.log("subscribe authentication event success"); 247} catch (error) { 248 console.log("subscribe authentication event failed " + error); 249} 250// 取消订阅认证结果 251try { 252 auth.off("result"); 253 console.info("cancel subscribe authentication event success"); 254} catch (error) { 255 console.info("cancel subscribe authentication event failed, error = " + error); 256} 257``` 258 259### start<sup>9+</sup> 260 261start : () => void 262 263开始认证。 264 265> **说明：** 266> 使用获取到的[AuthInstance](#authinstance9)对象调用该接口进行认证。 267 268**需要权限**：ohos.permission.ACCESS_BIOMETRIC 269 270**系统能力**：SystemCapability.UserIAM.UserAuth.Core 271 272以下错误码的详细介绍请参见[用户认证错误码](../errorcodes/errorcode-useriam.md) 273 274**错误码：** 275 276| 错误码ID | 错误信息 | 277| -------- | ------- | 278| 201 | Permission verification failed. | 279| 401 | Incorrect parameters. | 280| 12500001 | Authentication failed. | 281| 12500002 | General operation error. | 282| 12500003 | The operation is canceled. | 283| 12500004 | The operation is time-out. | 284| 12500005 | The authentication type is not supported. | 285| 12500006 | The authentication trust level is not supported. | 286| 12500007 | The authentication task is busy. | 287| 12500009 | The authenticator is locked. | 288| 12500010 | The type of credential has not been enrolled. | 289 290**示例：** 291 292```js 293import userIAM_userAuth from '@ohos.userIAM.userAuth'; 294 295let challenge = new Uint8Array([1, 2, 3, 4, 5, 6, 7, 8]); 296let authType = userIAM_userAuth.UserAuthType.FACE; 297let authTrustLevel = userIAM_userAuth.AuthTrustLevel.ATL1; 298 299try { 300 let auth = userIAM_userAuth.getAuthInstance(challenge, authType, authTrustLevel); 301 auth.start(); 302 console.info("authV9 start auth success"); 303} catch (error) { 304 console.info("authV9 start auth failed, error = " + error); 305} 306``` 307 308### cancel<sup>9+</sup> 309 310cancel : () => void 311 312取消认证。 313 314> **说明：** 315> 使用获取到的[AuthInstance](#authinstance9)对象调用该接口进行取消认证，此[AuthInstance](#authinstance9)需要是正在进行认证的对象。 316 317**需要权限**：ohos.permission.ACCESS_BIOMETRIC 318 319**系统能力**：SystemCapability.UserIAM.UserAuth.Core 320 321以下错误码的详细介绍请参见[用户认证错误码](../errorcodes/errorcode-useriam.md) 322 323**错误码：** 324 325| 错误码ID | 错误信息 | 326| -------- | ------- | 327| 201 | Permission verification failed. | 328| 401 | Incorrect parameters. | 329| 12500002 | General operation error. | 330 331**示例：** 332 333```js 334import userIAM_userAuth from '@ohos.userIAM.userAuth'; 335 336let challenge = new Uint8Array([1, 2, 3, 4, 5, 6, 7, 8]); 337let authType = userIAM_userAuth.UserAuthType.FACE; 338let authTrustLevel = userIAM_userAuth.AuthTrustLevel.ATL1; 339 340try { 341 let auth = userIAM_userAuth.getAuthInstance(challenge, authType, authTrustLevel); 342 auth.cancel(); 343 console.info("cancel auth success"); 344} catch (error) { 345 console.info("cancel auth failed, error = " + error); 346} 347``` 348 349## userIAM_userAuth.getAuthInstance<sup>9+</sup> 350 351getAuthInstance(challenge : Uint8Array, authType : UserAuthType, authTrustLevel : AuthTrustLevel): AuthInstance 352 353获取AuthInstance对象，用于执行用户身份认证。 354 355> **说明：** 356> 每个AuthInstance只能进行一次认证，若需要再次进行认证则需重新获取AuthInstance。 357 358**系统能力**：SystemCapability.UserIAM.UserAuth.Core 359 360**参数：** 361 362| 参数名 | 类型 | 必填 | 说明 | 363| -------------- | ---------------------------------------- | ---- | ------------------------ | 364| challenge | Uint8Array | 是 | 挑战值，最大长度为32字节，可以填null。 | 365| authType | [UserAuthType](#userauthtype8) | 是 | 认证类型，当前支持FACE。 | 366| authTrustLevel | [AuthTrustLevel](#authtrustlevel8) | 是 | 认证信任等级。 | 367 368**返回值：** 369 370| 类型 | 说明 | 371| ----------------------------------------- | ------------ | 372| [AuthInstance](#authinstance9) | 认证器对象。 | 373 374以下错误码的详细介绍请参见[用户认证错误码](../errorcodes/errorcode-useriam.md) 375 376**错误码：** 377 378| 错误码ID | 错误信息 | 379| -------- | ------- | 380| 401 | Incorrect parameters. | 381| 12500002 | General operation error. | 382| 12500005 | The authentication type is not supported. | 383| 12500006 | The authentication trust level is not supported. | 384 385**示例：** 386 387```js 388import userIAM_userAuth from '@ohos.userIAM.userAuth'; 389 390let challenge = new Uint8Array([1, 2, 3, 4, 5, 6, 7, 8]); 391let authType = userIAM_userAuth.UserAuthType.FACE; 392let authTrustLevel = userIAM_userAuth.AuthTrustLevel.ATL1; 393 394try { 395 let auth = userIAM_userAuth.getAuthInstance(challenge, authType, authTrustLevel); 396 console.info("get auth instance success"); 397} catch (error) { 398 console.info("get auth instance success failed, error = " + error); 399} 400``` 401 402## userIAM_userAuth.getAvailableStatus<sup>9+</sup> 403 404getAvailableStatus(authType : UserAuthType, authTrustLevel : AuthTrustLevel): void 405 406查询指定类型和等级的认证能力是否支持。 407 408**需要权限**：ohos.permission.ACCESS_BIOMETRIC 409 410**系统能力**：SystemCapability.UserIAM.UserAuth.Core 411 412**参数：** 413 414| 参数名 | 类型 | 必填 | 说明 | 415| -------------- | ---------------------------------- | ---- | -------------------------- | 416| authType | [UserAuthType](#userauthtype8) | 是 | 认证类型，当前只支持FACE。 | 417| authTrustLevel | [AuthTrustLevel](#authtrustlevel8) | 是 | 认证信任等级。 | 418 419以下错误码的详细介绍请参见[用户认证错误码](../errorcodes/errorcode-useriam.md) 420 421**错误码：** 422 423| 错误码ID | 错误信息 | 424| -------- | ------- | 425| 201 | Permission verification failed. | 426| 401 | Incorrect parameters. | 427| 12500002 | General operation error. | 428| 12500005 | The authentication type is not supported. | 429| 12500006 | The authentication trust level is not supported. | 430| 12500010 | The type of credential has not been enrolled. | 431 432**示例：** 433 434```js 435import userIAM_userAuth from '@ohos.userIAM.userAuth'; 436 437try { 438 userIAM_userAuth.getAvailableStatus(userIAM_userAuth.UserAuthType.FACE, userIAM_userAuth.AuthTrustLevel.ATL1); 439 console.info("current auth trust level is supported"); 440} catch (error) { 441 console.info("current auth trust level is not supported, error = " + error); 442} 443``` 444 445## UserAuthResultCode<sup>9+</sup> 446 447表示返回码的枚举。 448 449**系统能力**：SystemCapability.UserIAM.UserAuth.Core 450 451| 名称 | 值 | 说明 | 452| ----------------------- | ------ | -------------------- | 453| SUCCESS | 12500000 | 执行成功。 | 454| FAIL | 12500001 | 认证失败。 | 455| GENERAL_ERROR | 12500002 | 操作通用错误。 | 456| CANCELED | 12500003 | 操作取消。 | 457| TIMEOUT | 12500004 | 操作超时。 | 458| TYPE_NOT_SUPPORT | 12500005 | 不支持的认证类型。 | 459| TRUST_LEVEL_NOT_SUPPORT | 12500006 | 不支持的认证等级。 | 460| BUSY | 12500007 | 忙碌状态。 | 461| LOCKED | 12500009 | 认证器已锁定。 | 462| NOT_ENROLLED | 12500010 | 用户未录入认证信息。 | 463 464## UserAuth<sup>8+</sup> 465 466认证器对象。 467 468### constructor<sup>(deprecated)</sup> 469 470constructor() 471 472创建认证器对象。 473 474> **说明：** 475> 从 API version 8 开始支持，从 API version 9 开始废弃，请使用[getAuthInstance](#useriam_userauthgetauthinstance9)替代。 476 477**系统能力**：SystemCapability.UserIAM.UserAuth.Core 478 479**返回值：** 480 481| 类型 | 说明 | 482| ---------------------- | -------------------- | 483| [UserAuth](#userauth8) | 认证器对象。 | 484 485**示例：** 486 487```js 488import userIAM_userAuth from '@ohos.userIAM.userAuth'; 489 490let auth = new userIAM_userAuth.UserAuth(); 491``` 492 493### getVersion<sup>(deprecated)</sup> 494 495getVersion() : number 496 497获取认证器的版本信息。 498 499> **说明：** 500> 从 API version 8 开始支持，从 API version 9 开始废弃。 501 502**需要权限**：ohos.permission.ACCESS_BIOMETRIC 503 504**系统能力**：SystemCapability.UserIAM.UserAuth.Core 505 506**返回值：** 507 508| 类型 | 说明 | 509| ------ | ---------------------- | 510| number | 认证器版本信息。 | 511 512**示例：** 513 514```js 515import userIAM_userAuth from '@ohos.userIAM.userAuth'; 516 517let auth = new userIAM_userAuth.UserAuth(); 518let version = auth.getVersion(); 519console.info("auth version = " + version); 520``` 521 522### getAvailableStatus<sup>(deprecated)</sup> 523 524getAvailableStatus(authType : UserAuthType, authTrustLevel : AuthTrustLevel) : number 525 526查询指定类型和等级的认证能力是否支持。 527 528> **说明：** 529> 从 API version 8 开始支持，从 API version 9 开始废弃，请使用[getAvailableStatus](#useriam_userauthgetavailablestatus9)替代。 530 531**需要权限**：ohos.permission.ACCESS_BIOMETRIC 532 533**系统能力**：SystemCapability.UserIAM.UserAuth.Core 534 535**参数：** 536 537| 参数名 | 类型 | 必填 | 说明 | 538| -------------- | ---------------------------------- | ---- | -------------------------- | 539| authType | [UserAuthType](#userauthtype8) | 是 | 认证类型，当前只支持FACE。 | 540| authTrustLevel | [AuthTrustLevel](#authtrustlevel8) | 是 | 认证信任等级。 | 541 542**返回值：** 543 544| 类型 | 说明 | 545| ------ | ------------------------------------------------------------ | 546| number | 查询结果，结果为SUCCESS时表示支持，其他返回值参见[ResultCode](#resultcodedeprecated)。 | 547 548**示例：** 549 550```js 551import userIAM_userAuth from '@ohos.userIAM.userAuth'; 552 553let auth = new userIAM_userAuth.UserAuth(); 554let checkCode = auth.getAvailableStatus(userIAM_userAuth.UserAuthType.FACE, userIAM_userAuth.AuthTrustLevel.ATL1); 555if (checkCode == userIAM_userAuth.ResultCode.SUCCESS) { 556 console.info("check auth support success"); 557} else { 558 console.error("check auth support fail, code = " + checkCode); 559} 560``` 561 562### auth<sup>(deprecated)</sup> 563 564auth(challenge: Uint8Array, authType: UserAuthType, authTrustLevel: AuthTrustLevel, callback: IUserAuthCallback): Uint8Array 565 566执行用户认证，使用回调函数返回结果。 567 568> **说明：** 569> 从 API version 8 开始支持，从 API version 9 开始废弃，建议使用[start](#start9)代替。 570 571**需要权限**：ohos.permission.ACCESS_BIOMETRIC 572 573**系统能力**：SystemCapability.UserIAM.UserAuth.Core 574 575**参数：** 576 577| 参数名 | 类型 | 必填 | 说明 | 578| -------------- | ---------------------------------------- | ---- | ------------------------ | 579| challenge | Uint8Array | 是 | 挑战值，可以填null。 | 580| authType | [UserAuthType](#userauthtype8) | 是 | 认证类型，当前支持FACE。 | 581| authTrustLevel | [AuthTrustLevel](#authtrustlevel8) | 是 | 认证信任等级。 | 582| callback | [IUserAuthCallback](#iuserauthcallbackdeprecated) | 是 | 回调函数。 | 583 584**返回值：** 585 586| 类型 | 说明 | 587| ---------- | ------------------------------------------------------------ | 588| Uint8Array | ContextId，作为取消认证[cancelAuth](#cancelauthdeprecated)接口的入参。 | 589 590**示例：** 591 592```js 593import userIAM_userAuth from '@ohos.userIAM.userAuth'; 594 595let auth = new userIAM_userAuth.UserAuth(); 596auth.auth(null, userIAM_userAuth.UserAuthType.FACE, userIAM_userAuth.AuthTrustLevel.ATL1, { 597 onResult: (result, extraInfo) => { 598 try { 599 console.info("auth onResult result = " + result); 600 console.info("auth onResult extraInfo = " + JSON.stringify(extraInfo)); 601 if (result == userIAM_userAuth.ResultCode.SUCCESS) { 602 // 此处添加认证成功逻辑 603 } else { 604 // 此处添加认证失败逻辑 605 } 606 } catch (e) { 607 console.info("auth onResult error = " + e); 608 } 609 } 610}); 611``` 612 613### cancelAuth<sup>(deprecated)</sup> 614 615cancelAuth(contextID : Uint8Array) : number 616 617表示通过contextID取消本次认证操作。 618 619> **说明：** 620> 从 API version 8 开始支持，从 API version 9 开始废弃，建议使用[cancel](#cancel9)代替。 621 622**需要权限**：ohos.permission.ACCESS_BIOMETRIC 623 624**系统能力**：SystemCapability.UserIAM.UserAuth.Core 625 626**参数：** 627 628| 参数名 | 类型 | 必填 | 说明 | 629| --------- | ---------- | ---- | ------------------------------------------ | 630| contextID | Uint8Array | 是 | 上下文的标识，通过[auth](#authdeprecated)接口获取。 | 631 632**返回值：** 633 634| 类型 | 说明 | 635| ------ | ------------------------ | 636| number | 取消认证的结果，结果为SUCCESS时表示取消成功，其他返回值参见[ResultCode](#resultcodedeprecated)。 | 637 638**示例：** 639 640```js 641import userIAM_userAuth from '@ohos.userIAM.userAuth'; 642 643// contextId可通过auth接口获取，此处直接定义 644let contextId = new Uint8Array([0, 1, 2, 3, 4, 5, 6, 7]); 645let auth = new userIAM_userAuth.UserAuth(); 646let cancelCode = auth.cancelAuth(contextId); 647if (cancelCode == userIAM_userAuth.ResultCode.SUCCESS) { 648 console.info("cancel auth success"); 649} else { 650 console.error("cancel auth fail"); 651} 652``` 653 654## IUserAuthCallback<sup>(deprecated)</sup> 655 656返回认证结果的回调对象。 657 658> **说明：** 659> 从 API version 8 开始支持，从 API version 9 开始废弃，建议使用[AuthEvent](#authevent9)代替。 660 661### onResult<sup>(deprecated)</sup> 662 663onResult: (result : number, extraInfo : AuthResult) => void 664 665回调函数，返回认证结果。 666 667> **说明：** 668> 从 API version 8 开始支持，从 API version 9 开始废弃，建议使用[callback](#callback9)代替。 669 670**系统能力**：SystemCapability.UserIAM.UserAuth.Core 671 672**参数：** 673 674| 参数名 | 类型 | 必填 | 说明 | 675| --------- | -------------------------- | ---- | ------------------------------------------------ | 676| result | number | 是 | 认证结果，参见[ResultCode](#resultcodedeprecated)。 | 677| extraInfo | [AuthResult](#authresultdeprecated) | 是 | 扩展信息，不同情况下的具体信息，<br/>如果身份验证通过，则在extraInfo中返回用户认证令牌，<br/>如果身份验证失败，则在extraInfo中返回剩余的用户认证次数，<br/>如果身份验证执行器被锁定，则在extraInfo中返回冻结时间。 | 678 679**示例：** 680 681```js 682import userIAM_userAuth from '@ohos.userIAM.userAuth'; 683 684let auth = new userIAM_userAuth.UserAuth(); 685auth.auth(null, userIAM_userAuth.UserAuthType.FACE, userIAM_userAuth.AuthTrustLevel.ATL1, { 686 onResult: (result, extraInfo) => { 687 try { 688 console.info("auth onResult result = " + result); 689 console.info("auth onResult extraInfo = " + JSON.stringify(extraInfo)); 690 if (result == userIAM_userAuth.ResultCode.SUCCESS) { 691 // 此处添加认证成功逻辑 692 } else { 693 // 此处添加认证失败逻辑 694 } 695 } catch (e) { 696 console.info("auth onResult error = " + e); 697 } 698 } 699}); 700``` 701 702### onAcquireInfo<sup>(deprecated)</sup> 703 704onAcquireInfo ?: (module : number, acquire : number, extraInfo : any) => void 705 706回调函数，返回认证过程中的提示信息，非必须实现。 707 708> **说明：** 709> 从 API version 8 开始支持，从 API version 9 开始废弃，建议使用[callback](#callback9)代替。 710 711**系统能力**：SystemCapability.UserIAM.UserAuth.Core 712 713**参数：** 714 715| 参数名 | 类型 | 必填 | 说明 | 716| --------- | ------ | ---- | ------------------------------ | 717| module | number | 是 | 发送提示信息的模块标识。 | 718| acquire | number | 是 | 认证执过程中的提示信息。 | 719| extraInfo | any | 是 | 预留字段。 | 720 721**示例：** 722 723```js 724import userIAM_userAuth from '@ohos.userIAM.userAuth'; 725 726let auth = new userIAM_userAuth.UserAuth(); 727auth.auth(null, userIAM_userAuth.UserAuthType.FACE, userIAM_userAuth.AuthTrustLevel.ATL1, { 728 onAcquireInfo: (module, acquire, extraInfo) => { 729 try { 730 console.info("auth onAcquireInfo module = " + module); 731 console.info("auth onAcquireInfo acquire = " + acquire); 732 console.info("auth onAcquireInfo extraInfo = " + JSON.stringify(extraInfo)); 733 } catch (e) { 734 console.info("auth onAcquireInfo error = " + e); 735 } 736 } 737}); 738``` 739 740## AuthResult<sup>(deprecated)</sup> 741 742表示认证结果的对象。 743 744> **说明：** 745> 从 API version 8 开始支持，从 API version 9 开始废弃，建议使用[AuthResultInfo](#authresultinfo9)代替。 746 747**系统能力**：SystemCapability.UserIAM.UserAuth.Core 748 749| 名称 | 类型 | 必填 | 说明 | 750| ------------ | ---------- | ---- | -------------------| 751| token | Uint8Array | 否 | 认证通过的令牌信息。 | 752| remainTimes | number | 否 | 剩余的认证操作次数。 | 753| freezingTime | number | 否 | 认证操作的冻结时间。 | 754 755## ResultCode<sup>(deprecated)</sup> 756 757表示返回码的枚举。 758 759> **说明：** 760> 从 API version 9 开始废弃，建议使用[UserAuthResultCode](#userauthresultcode9)代替。 761 762**系统能力**：SystemCapability.UserIAM.UserAuth.Core 763 764| 名称 | 值 | 说明 | 765| ----------------------- | ------ | -------------------- | 766| SUCCESS | 0 | 执行成功。 | 767| FAIL | 1 | 认证失败。 | 768| GENERAL_ERROR | 2 | 操作通用错误。 | 769| CANCELED | 3 | 操作取消。 | 770| TIMEOUT | 4 | 操作超时。 | 771| TYPE_NOT_SUPPORT | 5 | 不支持的认证类型。 | 772| TRUST_LEVEL_NOT_SUPPORT | 6 | 不支持的认证等级。 | 773| BUSY | 7 | 忙碌状态。 | 774| INVALID_PARAMETERS | 8 | 无效参数。 | 775| LOCKED | 9 | 认证器已锁定。 | 776| NOT_ENROLLED | 10 | 用户未录入认证信息。 | 777 778## FaceTips<sup>8+</sup> 779 780表示人脸认证过程中提示码的枚举。 781 782**系统能力**：SystemCapability.UserIAM.UserAuth.Core 783 784| 名称 | 值 | 说明 | 785| ----------------------------- | ------ | ------------------------------------ | 786| FACE_AUTH_TIP_TOO_BRIGHT | 1 | 光线太强，获取的图像太亮。 | 787| FACE_AUTH_TIP_TOO_DARK | 2 | 光线太暗，获取的图像太暗。 | 788| FACE_AUTH_TIP_TOO_CLOSE | 3 | 人脸距离设备过近。 | 789| FACE_AUTH_TIP_TOO_FAR | 4 | 人脸距离设备过远。 | 790| FACE_AUTH_TIP_TOO_HIGH | 5 | 设备太高，仅获取到人脸上部。 | 791| FACE_AUTH_TIP_TOO_LOW | 6 | 设备太低，仅获取到人脸下部。 | 792| FACE_AUTH_TIP_TOO_RIGHT | 7 | 设备太靠右，仅获取到人脸右部。 | 793| FACE_AUTH_TIP_TOO_LEFT | 8 | 设备太靠左，仅获取到人脸左部。 | 794| FACE_AUTH_TIP_TOO_MUCH_MOTION | 9 | 在图像采集过程中，用户人脸移动太快。 | 795| FACE_AUTH_TIP_POOR_GAZE | 10 | 没有正视摄像头。 | 796| FACE_AUTH_TIP_NOT_DETECTED | 11 | 没有检测到人脸信息。 | 797 798 799## FingerprintTips<sup>8+</sup> 800 801表示指纹认证过程中提示码的枚举。 802 803**系统能力**：SystemCapability.UserIAM.UserAuth.Core 804 805| 名称 | 值 | 说明 | 806| --------------------------------- | ------ | -------------------------------------------------- | 807| FINGERPRINT_AUTH_TIP_GOOD | 0 | 获取的指纹图像良好。 | 808| FINGERPRINT_AUTH_TIP_DIRTY | 1 | 由于传感器上可疑或检测到的污垢，指纹图像噪音过大。 | 809| FINGERPRINT_AUTH_TIP_INSUFFICIENT | 2 | 由于检测到的情况，指纹图像噪声太大，无法处理。 | 810| FINGERPRINT_AUTH_TIP_PARTIAL | 3 | 仅检测到部分指纹图像。 | 811| FINGERPRINT_AUTH_TIP_TOO_FAST | 4 | 快速移动，指纹图像不完整。 | 812| FINGERPRINT_AUTH_TIP_TOO_SLOW | 5 | 缺少运动，指纹图像无法读取。 | 813 814 815## UserAuthType<sup>8+</sup> 816 817表示身份认证的凭据类型枚举。 818 819**系统能力**：SystemCapability.UserIAM.UserAuth.Core 820 821| 名称 | 值 | 说明 | 822| ----------- | ------ | ---------- | 823| FACE | 2 | 人脸认证。 | 824| FINGERPRINT | 4 | 指纹认证。 | 825 826## AuthTrustLevel<sup>8+</sup> 827 828表示认证结果的信任等级枚举。 829 830**系统能力**：SystemCapability.UserIAM.UserAuth.Core 831 832| 名称 | 值 | 说明 | 833| ---- | ------ | ------------------------- | 834| ATL1 | 10000 | 认证结果的信任等级级别1。 | 835| ATL2 | 20000 | 认证结果的信任等级级别2。 | 836| ATL3 | 30000 | 认证结果的信任等级级别3。 | 837| ATL4 | 40000 | 认证结果的信任等级级别4。 | 838 839## userIAM_userAuth.getAuthenticator<sup>(deprecated)</sup> 840 841getAuthenticator(): Authenticator 842 843获取Authenticator对象，用于执行用户身份认证。 844 845> **说明：** 846> 从 API version 8 开始废弃，建议使用[constructor](#constructordeprecated)替代。 847 848**系统能力**：SystemCapability.UserIAM.UserAuth.Core 849 850**返回值：** 851 852| 类型 | 说明 | 853| ----------------------------------------- | ------------ | 854| [Authenticator](#authenticatordeprecated) | 认证器对象。 | 855 856**示例：** 857 ```js 858 let authenticator = userIAM_userAuth.getAuthenticator(); 859 ``` 860 861## Authenticator<sup>(deprecated)</sup> 862 863认证器对象。 864 865> **说明：** 866> 从 API version 8 开始废弃，建议使用[UserAuth](#userauth8)替代。 867 868### execute<sup>(deprecated)</sup> 869 870execute(type: AuthType, level: SecureLevel, callback: AsyncCallback<number>): void 871 872执行用户认证，使用callback方式作为异步方法。 873 874> **说明：** 875> 从 API version 8 开始废弃，建议使用[auth](#authdeprecated)替代。 876 877**需要权限**：ohos.permission.ACCESS_BIOMETRIC 878 879**系统能力**：SystemCapability.UserIAM.UserAuth.Core 880 881**参数：** 882 883| 参数名 | 类型 | 必填 | 说明 | 884| -------- | --------------------------- | ---- | -------------------------- | 885| type | AuthType | 是 | 认证类型，当前只支持"FACE_ONLY"。<br/>ALL为预留参数，当前版本暂不支持ALL类型的认证。 | 886| level | SecureLevel | 是 | 安全级别，对应认证的安全级别，有效值为"S1"（最低）、"S2"、"S3"、"S4"（最高）。<br/>具备3D人脸识别能力的设备支持"S3"及以下安全级别的认证。<br/>具备2D人脸识别能力的设备支持"S2"及以下安全级别的认证。 | 887| callback | AsyncCallback<number> | 是 | 回调函数。 | 888 889callback返回值： 890 891| 类型 | 说明 | 892| ------ | ------------------------------------------------------------ | 893| number | 表示认证结果，参见[AuthenticationResult](#authenticationresultdeprecated)。 | 894 895**示例：** 896 897```js 898let authenticator = userIAM_userAuth.getAuthenticator(); 899authenticator.execute("FACE_ONLY", "S2", (error, code)=>{ 900 if (code === userIAM_userAuth.ResultCode.SUCCESS) { 901 console.info("auth success"); 902 return; 903 } 904 console.error("auth fail, code = " + code); 905}); 906``` 907 908 909### execute<sup>(deprecated)</sup> 910 911execute(type : AuthType, level : SecureLevel): Promise<number> 912 913执行用户认证，使用promise方式作为异步方法。 914 915> **说明：** 916> 从 API version 8 开始废弃，建议使用[auth](#authdeprecated)替代。 917 918**需要权限**：ohos.permission.ACCESS_BIOMETRIC 919 920**系统能力**：SystemCapability.UserIAM.UserAuth.Core 921 922**参数：** 923 924| 参数名 | 类型 | 必填 | 说明 | 925| ------ | ------ | ---- | ------------------------------------------------------------ | 926| type | AuthType | 是 | 认证类型，当前只支持"FACE_ONLY"。<br/>ALL为预留参数，当前版本暂不支持ALL类型的认证。 | 927| level | SecureLevel | 是 | 安全级别，对应认证的安全级别，有效值为"S1"（最低）、"S2"、"S3"、"S4"（最高）。<br/>具备3D人脸识别能力的设备支持"S3"及以下安全级别的认证。<br/>具备2D人脸识别能力的设备支持"S2"及以下安全级别的认证。 | 928 929**返回值：** 930 931| 类型 | 说明 | 932| --------------------- | ------------------------------------------------------------ | 933| Promise<number> | 返回携带一个number的Promise。number 为认证结果，参见[AuthenticationResult](#authenticationresultdeprecated)。 | 934 935**示例：** 936 937```js 938let authenticator = userIAM_userAuth.getAuthenticator(); 939authenticator.execute("FACE_ONLY", "S2").then((code)=>{ 940 console.info("auth success"); 941}).catch((error)=>{ 942 console.error("auth fail, code = " + error); 943}); 944``` 945 946## AuthenticationResult<sup>(deprecated)</sup> 947 948表示认证结果的枚举。 949 950> **说明：** 951> 从 API version 8 开始废弃，建议使用[ResultCode](#resultcodedeprecated)替代。 952 953**系统能力**：SystemCapability.UserIAM.UserAuth.Core 954 955| 名称 | 值 | 说明 | 956| ------------------ | ------ | -------------------------- | 957| NO_SUPPORT | -1 | 设备不支持当前的认证方式。 | 958| SUCCESS | 0 | 认证成功。 | 959| COMPARE_FAILURE | 1 | 比对失败。 | 960| CANCELED | 2 | 用户取消认证。 | 961| TIMEOUT | 3 | 认证超时。 | 962| CAMERA_FAIL | 4 | 开启相机失败。 | 963| BUSY | 5 | 认证服务忙，请稍后重试。 | 964| INVALID_PARAMETERS | 6 | 认证参数无效。 | 965| LOCKED | 7 | 认证失败次数过多，已锁定。 | 966| NOT_ENROLLED | 8 | 未录入认证凭据。 | 967| GENERAL_ERROR | 100 | 其他错误。 | 968