• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1# Initiating User Authentication
2
3
4A user authentication is required before an application accesses a critical functionality or sensitive data. This topic walks you through the process.
5
6
7## Available APIs
8
9For details about the parameters, return values, and error codes, see [User Authentication](../../reference/apis-user-authentication-kit/js-apis-useriam-userauth.md#userauthgetuserauthinstance10).
10
11| API| Description|
12| -------- | -------- |
13| getUserAuthInstance(authParam: AuthParam, widgetParam: WidgetParam): UserAuthInstance | Obtains a **UserAuthInstance** object for user authentication. The unified [user authentication widget](#user-authentication-widget) is also supported.|
14| on(type: 'result', callback: IAuthCallback): void | Subscribes to the user authentication result.|
15| off(type: 'result', callback?: IAuthCallback): void | Unsubscribes from the user authentication result.|
16| start(): void | Starts user authentication.|
17
18
19## User Authentication Widget
20
21The system provides a unified user authentication widget, which stands out with following features:
22
23- The user authentication widget identifies and authenticates user information and returns the authentication result to the application. The overall process is secure and controllable.
24
25- The widget comes with a unified UI component style to elevate user experience.
26
27The following figure shows the style of the user authentication widget, which can be set via the [WidgetParam](../../reference/apis-user-authentication-kit/js-apis-useriam-userauth.md#widgetparam10) parameter.
28
29<!--RP1-->
30![](figures/user-authentication-widget.png)
31<!--RP1End-->
32
33- ①: Title (**WidgetParam.title**) of the user authentication page, which cannot exceed 500 characters. You can set the title based on actual requirements.
34
35- ②: Text on the navigation button (**WidgetParam.navigationButtonText**), which cannot exceed 60 characters. This parameter can be set only for a single fingerprint or facial authentication.
36
37  If biometric authentication fails, the authentication widget button is displayed. You can click this button to apply custom authentication.
38
39<!--Del-->
40- The following shows the display modes (**WidgetParam.windowMode**) of the user authentication widget.
41
42  The user authentication widget provides two display modes: dialog box (default mode, as shown in figure on the left) and full screen (as shown in the figure on the right).
43
44  Currently, the full screen mode is available only for system applications.
45
46  ![](figures/widget_display_modes.png)
47<!--DelEnd-->
48
49The user authentication widget supports the following types of authentication:
50
51- Lock screen password authentication
52
53- Facial authentication
54
55- Fingerprint authentication
56
57- Facial + lock screen password authentication
58
59- Fingerprint + lock screen password authentication
60
61- Facial + fingerprint + lock screen password authentication
62
63> **NOTE**
64> Currently, the text on the navigation button (**WidgetParam.navigationButtonText**) can be set only for a single fingerprint or facial authentication.
65
66
67## How to Develop
68
691. Check that the application has the ohos.permission.ACCESS_BIOMETRIC permission. For details about how to request permissions, see [Requesting Permissions](prerequisites.md#requesting-permissions).
70
712. Set [AuthParam](../../reference/apis-user-authentication-kit/js-apis-useriam-userauth.md#authparam10) (including the challenge, [UserAuthType](../../reference/apis-user-authentication-kit/js-apis-useriam-userauth.md#userauthtype8), and [AuthTrustLevel](../../reference/apis-user-authentication-kit/js-apis-useriam-userauth.md#authtrustlevel8)), configure [WidgetParam](../../reference/apis-user-authentication-kit/js-apis-useriam-userauth.md#widgetparam10), and use [getUserAuthInstance](../../reference/apis-user-authentication-kit/js-apis-useriam-userauth.md#userauthgetuserauthinstance10) to obtain a **UserAuthInstance** instance.
72
733. Use [UserAuthInstance.on](../../reference/apis-user-authentication-kit/js-apis-useriam-userauth.md#on10) to subscribe to the authentication result.
74
754. Use [UserAuthInstance.start](../../reference/apis-user-authentication-kit/js-apis-useriam-userauth.md#start10) to start authentication. The authentication result [UserAuthResult](../../reference/apis-user-authentication-kit/js-apis-useriam-userauth.md#userauthresult10) is returned through [IAuthCallback](../../reference/apis-user-authentication-kit/js-apis-useriam-userauth.md#iauthcallback10).
76   If the authentication is successful, [UserAuthType](../../reference/apis-user-authentication-kit/js-apis-useriam-userauth.md#userauthtype8) and token information (**AuthToken**) are returned.
77
78**Example 1**
79
80 Initiate facial authentication and lock screen password authentication with the authentication trust level greater than or equal to ATL3.
81
82```ts
83// API version 10
84import { BusinessError } from '@kit.BasicServicesKit';
85import { userAuth } from '@kit.UserAuthenticationKit';
86
87// Set authentication parameters.
88const authParam: userAuth.AuthParam = {
89  challenge: new Uint8Array([49, 49, 49, 49, 49, 49]),
90  authType: [userAuth.UserAuthType.PIN, userAuth.UserAuthType.FACE],
91  authTrustLevel: userAuth.AuthTrustLevel.ATL3,
92};
93// Set the authentication page.
94const widgetParam: userAuth.WidgetParam = {
95  title: 'Verify identity',
96};
97try {
98  // Obtain a UserAuthInstance object.
99  let userAuthInstance = userAuth.getUserAuthInstance(authParam, widgetParam);
100  console.info('get userAuth instance success');
101  // Subscribe to the authentication result.
102  userAuthInstance.on('result', {
103    onResult(result) {
104      console.info(`userAuthInstance callback result: ${JSON.stringify(result)}`);
105      // Unsubscribe from the authentication result if required.
106      userAuthInstance.off('result');
107    }
108  });
109  console.info('auth on success');
110  userAuthInstance.start();
111  console.info('auth start success');
112} catch (error) {
113  const err: BusinessError = error as BusinessError;
114  console.error(`auth catch error. Code is ${err?.code}, message is ${err?.message}`);
115}
116```
117**Example 2**
118
119Initiate facial authentication with the authentication trust level greater than or equal to ATL3, and enable the device unlock result to be reused for the same type of authentication within the specified time.
120
121```ts
122// API version 10
123import { BusinessError } from  '@kit.BasicServicesKit';
124import { userAuth } from '@kit.UserAuthenticationKit';
125
126// Set authentication parameters.
127let reuseUnlockResult: userAuth.ReuseUnlockResult = {
128  reuseMode: userAuth.ReuseMode.AUTH_TYPE_RELEVANT,
129  reuseDuration: userAuth.MAX_ALLOWABLE_REUSE_DURATION,
130}
131const authParam: userAuth.AuthParam = {
132  challenge: new Uint8Array([49, 49, 49, 49, 49, 49]),
133  authType: [userAuth.UserAuthType.FACE],
134  authTrustLevel: userAuth.AuthTrustLevel.ATL3,
135  reuseUnlockResult: reuseUnlockResult,
136};
137// Set the authentication page.
138const widgetParam: userAuth.WidgetParam = {
139  title: 'Verify identity',
140};
141try {
142  // Obtain a UserAuthInstance object.
143  let userAuthInstance = userAuth.getUserAuthInstance(authParam, widgetParam);
144  console.info('get userAuth instance success');
145  // Subscribe to the authentication result.
146  userAuthInstance.on('result', {
147    onResult(result) {
148      console.info(`userAuthInstance callback result: ${JSON.stringify(result)}`);
149      // Unsubscribe from the authentication result if required.
150      userAuthInstance.off('result');
151    }
152  });
153  console.info('auth on success');
154  userAuthInstance.start();
155  console.info('auth start success');
156} catch (error) {
157  const err: BusinessError = error as BusinessError;
158  console.error(`auth catch error. Code is ${err?.code}, message is ${err?.message}`);
159}
160```
161