1# @ohos.userIAM.userAuth (User Authentication) (System API)
2
3The **userIAM.userAuth** module provides user authentication capabilities in identity authentication scenarios, such as device unlocking, payment, and app login.
4
5> **NOTE**
6>
7> - The initial APIs of this module are supported since API version 6. Newly added APIs will be marked with a superscript to indicate their earliest API version.
8> - This topic describes only the system APIs provided by the module. For details about its public APIs, see [@ohos.userIAM.userAuth (User Authentication)](js-apis-useriam-userauth.md).
9
10## Modules to Import
11
12```ts
13import { userAuth } from '@kit.UserAuthenticationKit';
14```
15
16## WindowModeType<sup>10+</sup>
17
18Enumerates the window types of the authentication widget.
19
20**System capability**: SystemCapability.UserIAM.UserAuth.Core
21
22**System API**: This is a system API.
23
24| Name      | Value  | Description      |
25| ---------- | ---- | ---------- |
26| DIALOG_BOX | 1    | Dialog box.|
27| FULLSCREEN | 2    | Full screen.|
28
29## WidgetParam<sup>10+</sup>
30
31Represents the information presented on the user authentication page.
32
33**System capability**: SystemCapability.UserIAM.UserAuth.Core
34
35| Name                | Type                               | Mandatory| Description                                                        |
36| -------------------- | ----------------------------------- | ---- | ------------------------------------------------------------ |
37| windowMode           | [WindowModeType](#windowmodetype10) | No  | Display format of the user authentication page. The default value is **WindowModeType.DIALOG_BOX**.<br>**System API**: This is a system API.|
38
39## NoticeType<sup>10+</sup>
40
41Defines the type of the user authentication notification.
42
43**System capability**: SystemCapability.UserIAM.UserAuth.Core
44
45**System API**: This is a system API.
46
47| Name         | Value  | Description                |
48| ------------- | ---- | -------------------- |
49| WIDGET_NOTICE | 1    | Notification from the user authentication widget.|
50
51## userAuth.sendNotice<sup>10+</sup>
52
53sendNotice(noticeType: NoticeType, eventData: string): void
54
55Sends a notification from the user authentication widget.
56
57**Required permissions**: ohos.permission.SUPPORT_USER_AUTH
58
59**System capability**: SystemCapability.UserIAM.UserAuth.Core
60
61**System API**: This is a system API.
62
63**Parameters**
64
65| Name    | Type                       | Mandatory| Description      |
66| ---------- | --------------------------- | ---- | ---------- |
67| noticeType | [NoticeType](#noticetype10) | Yes  | Notification type.|
68| eventData  | string                      | Yes  | Event data.|
69
70**Error codes**
71
72For details about the error codes, see [User Authentication Error Codes](errorcode-useriam.md).
73
74| ID| Error Message                               |
75| -------- | --------------------------------------- |
76| 201      | Permission verification failed.         |
77| 202      | The caller is not a system application. |
78| 401      | Incorrect parameters. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. 3.Parameter verification failed.    |
79| 12500002 | General operation error.                |
80
81**Example**
82
83```ts
84import { userAuth } from '@kit.UserAuthenticationKit';
85
86interface  EventData {
87  widgetContextId: number;
88  event: string;
89  version: string;
90  payload: PayLoad;
91}
92interface PayLoad {
93  type: Object[];
94}
95try {
96  const eventData : EventData = {
97    widgetContextId: 123456,
98    event: 'EVENT_AUTH_TYPE_READY',
99    version: '1',
100    payload: {
101      type: ['pin']
102    } as PayLoad,
103  };
104  const jsonEventData = JSON.stringify(eventData);
105  let noticeType = userAuth.NoticeType.WIDGET_NOTICE;
106  userAuth.sendNotice(noticeType, jsonEventData);
107  console.info('sendNotice success');
108} catch (error) {
109  console.error(`sendNotice catch error: ${JSON.stringify(error)}`);
110}
111```
112
113## UserAuthWidgetMgr<sup>10+</sup>
114
115Provides APIs for managing the user authentication widget. You can use the APIs to register the user authentication widget with UserAuthWidgetMgr for management and scheduling.
116
117### on<sup>10+</sup>
118
119on(type: 'command', callback: IAuthWidgetCallback): void
120
121Subscribes to commands from the user authentication framework for the user authentication widget.
122
123**System capability**: SystemCapability.UserIAM.UserAuth.Core
124
125**System API**: This is a system API.
126
127**Parameters**
128
129| Name  | Type                                         | Mandatory| Description                                                        |
130| -------- | --------------------------------------------- | ---- | ------------------------------------------------------------ |
131| type     | 'command'                                     | Yes  | Event type. The vlaue is **command**, which indicates the command sent from the user authentication framework to the user authentication widget. |
132| callback | [IAuthWidgetCallback](#iauthwidgetcallback10) | Yes  | Callback used to return the command from the user authentication framework to the user authentication widget.|
133
134**Error codes**
135
136For details about the error codes, see [User Authentication Error Codes](errorcode-useriam.md).
137
138| ID| Error Message                |
139| -------- | ------------------------ |
140| 401      | Incorrect parameters. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. 3.Parameter verification failed. |
141| 12500002 | General operation error. |
142
143**Example**
144
145```ts
146import { userAuth } from '@kit.UserAuthenticationKit';
147
148const userAuthWidgetMgrVersion = 1;
149try {
150  let userAuthWidgetMgr = userAuth.getUserAuthWidgetMgr(userAuthWidgetMgrVersion);
151  console.info('get userAuthWidgetMgr instance success');
152  userAuthWidgetMgr.on('command', {
153    sendCommand(cmdData) {
154      console.info(`The cmdData is ${cmdData}`);
155    }
156  })
157  console.info('subscribe authentication event success');
158} catch (error) {
159  console.error(`userAuth widgetMgr catch error: ${JSON.stringify(error)}`);
160}
161```
162
163### off<sup>10+</sup>
164
165off(type: 'command', callback?: IAuthWidgetCallback): void
166
167Unsubscribes from commands sent from the user authentication framework.
168
169**System capability**: SystemCapability.UserIAM.UserAuth.Core
170
171**System API**: This is a system API.
172
173**Parameters**
174
175| Name  | Type                                         | Mandatory| Description                                                        |
176| -------- | --------------------------------------------- | ---- | ------------------------------------------------------------ |
177| type     | 'command'                                     | Yes  | Event type. The value is **command**, which indicates the command sent from the user authentication framework to the user authentication widget. |
178| callback | [IAuthWidgetCallback](#iauthwidgetcallback10) | No  | Callback to unregister.|
179
180**Error codes**
181
182For details about the error codes, see [User Authentication Error Codes](errorcode-useriam.md).
183
184| ID| Error Message                |
185| -------- | ------------------------ |
186| 401      | Incorrect parameters. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. 3.Parameter verification failed. |
187| 12500002 | General operation error. |
188
189**Example**
190
191```ts
192import { userAuth } from '@kit.UserAuthenticationKit';
193
194const userAuthWidgetMgrVersion = 1;
195try {
196  let userAuthWidgetMgr = userAuth.getUserAuthWidgetMgr(userAuthWidgetMgrVersion);
197  console.info('get userAuthWidgetMgr instance success');
198  userAuthWidgetMgr.off('command', {
199    sendCommand(cmdData) {
200      console.info(`The cmdData is ${cmdData}`);
201    }
202  })
203  console.info('cancel subscribe authentication event success');
204} catch (error) {
205  console.error(`userAuth widgetMgr catch error: ${JSON.stringify(error)}`);
206}
207```
208
209## userAuth.getUserAuthWidgetMgr<sup>10+</sup>
210
211getUserAuthWidgetMgr(version: number): UserAuthWidgetMgr
212
213Obtains a **UserAuthWidgetMgr** instance for user authentication.
214
215> **NOTE**<br>
216> A **UserAuthInstance** instance can be used for an authentication only once.
217
218**Required permissions**: ohos.permission.SUPPORT_USER_AUTH
219
220**System capability**: SystemCapability.UserIAM.UserAuth.Core
221
222**System API**: This is a system API.
223
224**Parameters**
225
226| Name | Type  | Mandatory| Description                |
227| ------- | ------ | ---- | -------------------- |
228| version | number | Yes  | Version of the user authentication widget.|
229
230**Return value**
231
232| Type                                     | Description        |
233| ----------------------------------------- | ------------ |
234| [UserAuthWidgetMgr](#userauthwidgetmgr10) | **UserAuthWidgetMgr** instance obtained.|
235
236**Error codes**
237
238For details about the error codes, see [User Authentication Error Codes](errorcode-useriam.md).
239
240| ID| Error Message                               |
241| -------- | --------------------------------------- |
242| 201      | Permission verification failed.         |
243| 202      | The caller is not a system application. |
244| 401      | Incorrect parameters. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types.                                     |
245| 12500002 | General operation error.                |
246
247**Example**
248
249```ts
250import { userAuth } from '@kit.UserAuthenticationKit';
251
252let userAuthWidgetMgrVersion = 1;
253try {
254  let userAuthWidgetMgr = userAuth.getUserAuthWidgetMgr(userAuthWidgetMgrVersion);
255  console.info('get userAuthWidgetMgr instance success');
256} catch (error) {
257  console.error(`userAuth widgetMgr catch error: ${JSON.stringify(error)}`);
258}
259```
260
261## IAuthWidgetCallback<sup>10+</sup>
262
263Provides the callback for returning the commands sent from the user authentication framework to the user authentication widget.
264
265### sendCommand<sup>10+</sup>
266
267sendCommand(cmdData: string): void
268
269Called to return the command sent from the user authentication framework to the user authentication widget.
270
271**System capability**: SystemCapability.UserIAM.UserAuth.Core
272
273**System API**: This is a system API.
274
275**Parameters**
276
277| Name | Type  | Mandatory| Description                              |
278| ------- | ------ | ---- | ---------------------------------- |
279| cmdData | string | Yes  | Command sent from the user authentication framework to the user authentication widget.|
280
281**Example**
282
283```ts
284import { userAuth } from '@kit.UserAuthenticationKit';
285
286const userAuthWidgetMgrVersion = 1;
287try {
288  let userAuthWidgetMgr = userAuth.getUserAuthWidgetMgr(userAuthWidgetMgrVersion);
289  console.info('get userAuthWidgetMgr instance success');
290  userAuthWidgetMgr.on('command', {
291    sendCommand(cmdData) {
292      console.info(`The cmdData is ${cmdData}`);
293    }
294  })
295  console.info('subscribe authentication event success');
296} catch (error) {
297  console.error(`userAuth widgetMgr catch error: ${JSON.stringify(error)}`);
298}
299```
300
301## UserAuthType<sup>8+</sup>
302
303Enumerates the types of credentials for identity authentication.
304
305**System capability**: SystemCapability.UserIAM.UserAuth.Core
306
307| Name       | Value  | Description      |
308| ----------- | ---- | ---------- |
309| PRIVATE_PIN<sup>14+</sup>  | 16   | Privacy password.|
310
311**Example**
312
313Initiate privacy PIN authentication with the authentication trust level greater than or equal to ATL3.
314
315```ts
316import { BusinessError } from '@kit.BasicServicesKit';
317import { cryptoFramework } from '@kit.CryptoArchitectureKit';
318import { userAuth } from '@kit.UserAuthenticationKit';
319
320try {
321  const rand = cryptoFramework.createRandom();
322  const len: number = 16;
323  const randData: Uint8Array = rand?.generateRandomSync(len)?.data;
324  const authParam: userAuth.AuthParam = {
325    challenge: randData,
326    authType: [userAuth.UserAuthType.PRIVATE_PIN],
327    authTrustLevel: userAuth.AuthTrustLevel.ATL3,
328  };
329  const widgetParam: userAuth.WidgetParam = {
330    title: 'Enter password',
331  };
332
333  const userAuthInstance = userAuth.getUserAuthInstance(authParam, widgetParam);
334  console.info('get userAuth instance success');
335  // The authentication result is returned by onResult() only after the authentication is started by start() of UserAuthInstance.
336  userAuthInstance.on('result', {
337    onResult (result) {
338      console.info(`userAuthInstance callback result = ${JSON.stringify(result)}`);
339    }
340  });
341  console.info('auth on success');
342} catch (error) {
343  const err: BusinessError = error as BusinessError;
344  console.error(`auth catch error. Code is ${err?.code}, message is ${err?.message}`);
345}
346```
347
348