• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1# @ohos.userIAM.userAccessCtrl (用户访问控制)(系统接口)
2
3提供用户访问控制能力，用于应用查询和配置用户身份认证策略、校验用户身份认证结果。
4
5> **说明：**
6>
7> 本模块首批接口从API version 18开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。
8
9## 导入模块
10
11```ts
12import { userAccessCtrl } from '@kit.UserAuthenticationKit';
13```
14
15## AuthTokenType
16
17认证令牌类型。
18
19**系统能力**：SystemCapability.UserIAM.UserAuth.Core
20
21**系统接口**：此接口为系统接口。
22
23| 名称                      | 值   | 说明       |
24| ------------------------ | ---- | ---------- |
25| TOKEN_TYPE_LOCAL_AUTH    | 0    | 身份验证令牌基于本地认证结果签发。 |
26| TOKEN_TYPE_LOCAL_RESIGN  | 1    | 身份验证令牌基于复用的身份认证结果重新签发。 |
27| TOKEN_TYPE_COAUTH        | 2    | 身份验证令牌基于多个设备协同认证结果签发。 |
28
29## AuthToken
30
31表示校验通过返回解析的AuthToken数据结果。
32
33**系统能力**：SystemCapability.UserIAM.UserAuth.Core
34
35**系统接口**：此接口为系统接口。
36
37| 名称           | 类型                               | 只读 | 可选 | 说明                                       |
38| -------------- | ---------------------------------- | ----- | ----- |------------------------------------------------------------ |
39| challenge | Uint8Array | 否 | 否 |认证随机挑战。|
40| authTrustLevel | [userAuth.AuthTrustLevel](js-apis-useriam-userauth.md#authtrustlevel8) | 否 | 否 |认证信任等级。|
41| authType | [userAuth.UserAuthType](js-apis-useriam-userauth.md#userauthtype8) | 否 | 否  |身份认证的凭据类型。|
42| tokenType | [AuthTokenType](#authtokentype) | 否 | 否 |认证令牌类型。|
43| userId | number | 否 | 否  |用户ID。|
44| timeInterval | bigint | 否  | 否  |自AuthToken签发至当前的时间，以毫秒表示。|
45| secureUid | bigint    | 否  | 是  |安全用户ID。|
46| enrolledId | bigint   | 否  | 是  |凭据注册ID。|
47| credentialId | bigint | 否  | 是  |匹配上的凭据ID。|
48
49
50## userAccessCtrl.verifyAuthToken
51
52verifyAuthToken(authToken: Uint8Array, allowableDuration: number): Promise\<AuthToken>
53
54验证认证令牌。
55
56**需要权限**：ohos.permission.USE_USER_ACCESS_MANAGER
57
58**系统能力**：SystemCapability.UserIAM.UserAuth.Core
59
60**系统接口**：此接口为系统接口。
61
62**参数：**
63
64| 参数名     | 类型                        | 必填 | 说明       |
65| ---------- | --------------------------- | ---- | ---------- |
66| authToken | Uint8Array | 是   | 需要被验证的AuthToken。最大长度为1024。 |
67| allowableDuration  | number  | 是   | 从AuthToken签发起允许认证的时间间隔，以毫秒表示。有效时长值应大于0，最大值为86400000毫秒。 |
68
69**返回值：**
70
71| 类型                                      | 说明         |
72| ----------------------------------------- | ------------ |
73| Promise\<[AuthToken](#authtoken)> | Promise对象，返回解析后的AuthToken。 |
74
75**错误码：**
76
77以下错误码的详细介绍请参见[用户认证错误码](errorcode-useriam.md)。
78
79| 错误码ID | 错误信息                                |
80| -------- | --------------------------------------- |
81| 201      | Permission verification failed.         |
82| 202      | The caller is not a system application. |
83| 401      | Incorrect parameters. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. 3.Parameter verification failed.    |
84| 12500002 | General operation error.                |
85| 12500015 | AuthToken integrity check failed.     |
86| 12500016 | AuthToken has expired.                |
87
88**示例：**
89
90```ts
91import { BusinessError } from '@kit.BasicServicesKit';
92import { cryptoFramework } from '@kit.CryptoArchitectureKit';
93import { userAccessCtrl } from '@kit.UserAuthenticationKit';
94import { userAuth } from '@kit.UserAuthenticationKit';
95
96try {
97  const rand = cryptoFramework.createRandom();
98  const allowableDuration: number = 5000;
99  const len: number = 16;
100  const randData: Uint8Array = rand?.generateRandomSync(len)?.data;
101  const authParam: userAuth.AuthParam = {
102    challenge: randData,
103    authType: [userAuth.UserAuthType.PIN],
104    authTrustLevel: userAuth.AuthTrustLevel.ATL3,
105  };
106  const widgetParam: userAuth.WidgetParam = {
107    title: '请输入密码',
108  };
109
110  const userAuthInstance = userAuth.getUserAuthInstance(authParam, widgetParam);
111  console.info('get userAuth instance success');
112  // 需要调用UserAuthInstance的start()接口，启动认证后，才能通过onResult获取到认证结果。
113  userAuthInstance.on('result', {
114    onResult (result) {
115        if (!result.token) {
116            console.error('userAuthInstance callback result.token is null');
117            return;
118        }
119        // 发起 AuthToken 验证请求。
120        userAccessCtrl.verifyAuthToken(result.token, allowableDuration)
121            .then((retAuthToken: userAccessCtrl.AuthToken) => {
122                Object.keys(retAuthToken).forEach((key) => {
123                    console.info(`retAuthToken key:${key}, value:${retAuthToken[key]}`);
124                })
125            }).catch ((error: BusinessError) => {
126                console.error(`verify authToken error. Code is ${error?.code}, message is ${error?.message}`);
127            })
128    }
129  });
130  console.info('auth on success');
131  // 启动认证。
132  userAuthInstance.start();
133  console.info('auth start success');
134} catch (error) {
135  const err: BusinessError = error as BusinessError;
136  console.error(`auth catch error. Code is ${err?.code}, message is ${err?.message}`);
137}
138```