• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1# @ohos.userIAM.userAccessCtrl (User Access Control) (System API)
2
3<!--Kit: User Authentication Kit-->
4<!--Subsystem: UserIAM-->
5<!--Owner: @WALL_EYE-->
6<!--SE: @lichangting518-->
7<!--TSE: @jane_lz-->
8
9The **userAccessCtrl** module provides APIs for setting and obtaining user identity authentication policies and verifying user identity authentication results.
10
11> **NOTE**
12>
13> The initial APIs of this module are supported since API version 18. Newly added APIs will be marked with a superscript to indicate their earliest API version.
14
15## Modules to Import
16
17```ts
18import { userAccessCtrl } from '@kit.UserAuthenticationKit';
19```
20
21## AuthTokenType
22
23Enumerates the authentication token types.
24
25**System capability**: SystemCapability.UserIAM.UserAuth.Core
26
27**System API**: This is a system API.
28
29| Name                     | Value  | Description      |
30| ------------------------ | ---- | ---------- |
31| TOKEN_TYPE_LOCAL_AUTH    | 0    | Authentication token issued based on the local authentication result.|
32| TOKEN_TYPE_LOCAL_RESIGN  | 1    | Authentication token issued based on the reused identity authentication result.|
33| TOKEN_TYPE_COAUTH        | 2    | Authentication token issued based on a collaborative authentication result of multiple devices.|
34
35## AuthToken
36
37Represents the AuthToken data returned after a successful verification.
38
39**System capability**: SystemCapability.UserIAM.UserAuth.Core
40
41**System API**: This is a system API.
42
43| Name          | Type                              | Read Only| Optional| Description                                      |
44| -------------- | ---------------------------------- | ----- | ----- |------------------------------------------------------------ |
45| challenge | Uint8Array | No| No|Random challenge for the authentication.|
46| authTrustLevel | [userAuth.AuthTrustLevel](js-apis-useriam-userauth.md#authtrustlevel8) | No| No|Authentication trust level.|
47| authType | [userAuth.UserAuthType](js-apis-useriam-userauth.md#userauthtype8) | No| No |Credential type for the identity authentication.|
48| tokenType | [AuthTokenType](#authtokentype) | No| No|Authentication token type.|
49| userId | number | No| No |User ID.|
50| timeInterval | bigint | No | No |Time elapsed since the issuance of the authentication token, in milliseconds.|
51| secureUid | bigint    | No | Yes |Secure user ID.|
52| enrolledId | bigint   | No | Yes |Credential enrollment ID.|
53| credentialId | bigint | No | Yes |Credential ID.|
54
55
56## userAccessCtrl.verifyAuthToken
57
58verifyAuthToken(authToken: Uint8Array, allowableDuration: number): Promise\<AuthToken>
59
60Verifies an authentication token.
61
62**Required permissions**: ohos.permission.USE_USER_ACCESS_MANAGER
63
64**System capability**: SystemCapability.UserIAM.UserAuth.Core
65
66**System API**: This is a system API.
67
68**Parameters**
69
70| Name    | Type                       | Mandatory| Description      |
71| ---------- | --------------------------- | ---- | ---------- |
72| authToken | Uint8Array | Yes  | Authentication token to verify, which cannot exceed 1024.|
73| allowableDuration  | number  | Yes  | Time allowed for the authentication token to be used after being issued, in milliseconds. The value must be greater than 0 and less than or equal to 86,400,000.|
74
75**Return value**
76
77| Type                                     | Description        |
78| ----------------------------------------- | ------------ |
79| Promise\<[AuthToken](#authtoken)> | Promise used to return the parsed authentication token.|
80
81**Error codes**
82
83For details about the error codes, see [User Authentication Error Codes](errorcode-useriam.md).
84
85| ID| Error Message                               |
86| -------- | --------------------------------------- |
87| 201      | Permission denied.        |
88| 202      | Permission denied. Called by non-system application. |
89| 401      | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. 3.Parameter verification failed.    |
90| 12500002 | General operation error.                |
91| 12500015 | AuthToken integrity check failed.     |
92| 12500016 | AuthToken has expired.                |
93
94**Example**
95
96```ts
97import { BusinessError } from '@kit.BasicServicesKit';
98import { cryptoFramework } from '@kit.CryptoArchitectureKit';
99import { userAccessCtrl } from '@kit.UserAuthenticationKit';
100import { userAuth } from '@kit.UserAuthenticationKit';
101
102try {
103  const rand = cryptoFramework.createRandom();
104  const allowableDuration: number = 5000;
105  const len: number = 16;
106  let randData: Uint8Array | null = null;
107  let retryCount = 0;
108  while(retryCount < 3){
109    randData = rand?.generateRandomSync(len)?.data;
110    if(randData){
111      break;
112    }
113    retryCount++;
114  }
115  if(!randData){
116    return;
117  }
118  const authParam: userAuth.AuthParam = {
119    challenge: randData,
120    authType: [userAuth.UserAuthType.PIN],
121    authTrustLevel: userAuth.AuthTrustLevel.ATL3,
122  };
123  const widgetParam: userAuth.WidgetParam = {
124    title: 'Enter password',
125  };
126
127  const userAuthInstance = userAuth.getUserAuthInstance(authParam, widgetParam);
128  console.info('get userAuth instance success');
129  // The authentication result is returned by onResult() only after the authentication is started by start() of UserAuthInstance.
130  userAuthInstance.on('result', {
131    onResult (result) {
132        if (!result.token) {
133            console.error('userAuthInstance callback result.token is null');
134            return;
135        }
136        try {
137          // Initiate a request for verifying the AuthToken.
138          userAccessCtrl.verifyAuthToken(result.token, allowableDuration)
139              .then((retAuthToken: userAccessCtrl.AuthToken) => {
140                  Object.keys(retAuthToken).forEach((key) => {
141                      // Process the service logic.
142                      console.info(`retAuthToken key:${key}`);
143                  })
144              }).catch ((error: BusinessError) => {
145                  console.error(`verify authToken error. Code is ${error?.code}, message is ${error?.message}`);
146              })
147        } catch (error) {
148          const err: BusinessError = error as BusinessError;
149          console.error(`verify authToken error. Code is ${err?.code}, message is ${err?.message}`);
150        }
151    }
152  });
153  console.info('auth on success');
154  // Start authentication.
155  userAuthInstance.start();
156  console.info('auth start success');
157} catch (error) {
158  const err: BusinessError = error as BusinessError;
159  console.error(`auth catch error. Code is ${err?.code}, message is ${err?.message}`);
160}
161```
162