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