harmony 鸿蒙@ohos.userIAM.userAccessCtrl (用户访问控制)(系统接口)

2025-06-16
浏览 (2)

@ohos.userIAM.userAccessCtrl (用户访问控制)(系统接口)

提供用户访问控制能力，用于应用查询和配置用户身份认证策略、校验用户身份认证结果。

说明：

本模块首批接口从API version 18开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。

导入模块

import { userAccessCtrl } from '@kit.UserAuthenticationKit';

AuthTokenType

认证令牌类型。

系统能力：SystemCapability.UserIAM.UserAuth.Core

系统接口：此接口为系统接口。

名称	值	说明
TOKEN_TYPE_LOCAL_AUTH	0	身份验证令牌基于本地认证结果签发。
TOKEN_TYPE_LOCAL_RESIGN	1	身份验证令牌基于复用的身份认证结果重新签发。
TOKEN_TYPE_COAUTH	2	身份验证令牌基于多个设备协同认证结果签发。

AuthToken

表示校验通过返回解析的AuthToken数据结果。

系统能力：SystemCapability.UserIAM.UserAuth.Core

系统接口：此接口为系统接口。

名称	类型	只读	可选	说明
challenge	Uint8Array	否	否	认证随机挑战。
authTrustLevel	userAuth.AuthTrustLevel	否	否	认证信任等级。
authType	userAuth.UserAuthType	否	否	身份认证的凭据类型。
tokenType	AuthTokenType	否	否	认证令牌类型。
userId	number	否	否	用户ID。
timeInterval	bigint	否	否	自AuthToken签发至当前的时间，以毫秒表示。
secureUid	bigint	否	是	安全用户ID。
enrolledId	bigint	否	是	凭据注册ID。
credentialId	bigint	否	是	匹配上的凭据ID。

userAccessCtrl.verifyAuthToken

verifyAuthToken(authToken: Uint8Array, allowableDuration: number): Promise<AuthToken>

验证认证令牌。

需要权限：ohos.permission.USE_USER_ACCESS_MANAGER

系统能力：SystemCapability.UserIAM.UserAuth.Core

系统接口：此接口为系统接口。

参数：

参数名	类型	必填	说明
authToken	Uint8Array	是	需要被验证的AuthToken。最大长度为1024。
allowableDuration	number	是	从AuthToken签发起允许认证的时间间隔，以毫秒表示。有效时长值应大于0，最大值为86400000毫秒。

返回值：

类型	说明
Promise<AuthToken>	Promise对象，返回解析后的AuthToken。

错误码：

以下错误码的详细介绍请参见用户认证错误码。

错误码ID	错误信息
201	Permission verification failed.
202	The caller is not a system application.
401	Incorrect parameters. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. 3.Parameter verification failed.
12500002	General operation error.
12500015	AuthToken integrity check failed.
12500016	AuthToken has expired.

示例：

import { BusinessError } from '@kit.BasicServicesKit';
import { cryptoFramework } from '@kit.CryptoArchitectureKit';
import { userAccessCtrl } from '@kit.UserAuthenticationKit';
import { userAuth } from '@kit.UserAuthenticationKit';

try {
  const rand = cryptoFramework.createRandom();
  const allowableDuration: number = 5000;
  const len: number = 16;
  const randData: Uint8Array = rand?.generateRandomSync(len)?.data;
  const authParam: userAuth.AuthParam = {
    challenge: randData,
    authType: [userAuth.UserAuthType.PIN],
    authTrustLevel: userAuth.AuthTrustLevel.ATL3,
  };
  const widgetParam: userAuth.WidgetParam = {
    title: '请输入密码',
  };

  const userAuthInstance = userAuth.getUserAuthInstance(authParam, widgetParam);
  console.info('get userAuth instance success');
  // 需要调用UserAuthInstance的start()接口，启动认证后，才能通过onResult获取到认证结果。
  userAuthInstance.on('result', {
    onResult (result) {
        if (!result.token) {
            console.error('userAuthInstance callback result.token is null');
            return;
        }
        // 发起 AuthToken 验证请求。
        userAccessCtrl.verifyAuthToken(result.token, allowableDuration)
            .then((retAuthToken: userAccessCtrl.AuthToken) => {
                Object.keys(retAuthToken).forEach((key) => {
                    console.info(`retAuthToken key:${key}, value:${retAuthToken[key]}`);
                })
            }).catch ((error: BusinessError) => {
                console.error(`verify authToken error. Code is ${error?.code}, message is ${error?.message}`);
            })
    }
  });
  console.info('auth on success');
  // 启动认证。
  userAuthInstance.start();
  console.info('auth start success');
} catch (error) {
  const err: BusinessError = error as BusinessError;
  console.error(`auth catch error. Code is ${err?.code}, message is ${err?.message}`);
}