Initiating User Authentication

A user authentication is required before an application accesses a critical functionality or sensitive data. This topic walks you through the process.

Available APIs

For details about the parameters, return values, and error codes, see User Authentication.

User Authentication Widget

The system provides a unified user authentication widget, which stands out with following features:

• The user authentication widget identifies and authenticates user information and returns the authentication result to the application. The overall process is secure and controllable.

• The widget comes with a unified UI component style to elevate user experience.

The following figure shows the style of the user authentication widget, which can be set via the WidgetParam parameter.

• ①: Title (WidgetParam.title) of the user authentication page, which cannot exceed 500 characters. You can set the title based on actual requirements.

• ②: 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.

  If biometric authentication fails, the authentication widget button is displayed. You can click this button to apply custom authentication.

• The following shows the display modes (WidgetParam.windowMode) of the user authentication widget.

  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).

  Currently, the full screen mode is available only for system applications.

  

The user authentication widget supports the following types of authentication:

• Lock screen password authentication

• Facial authentication

• Fingerprint authentication

• Facial + lock screen password authentication

• Fingerprint + lock screen password authentication

• Facial + fingerprint + lock screen password authentication

NOTE Currently, the text on the navigation button (WidgetParam.navigationButtonText) can be set only for a single fingerprint or facial authentication.

How to Develop

1. Check that the application has the ohos.permission.ACCESS_BIOMETRIC permission. For details about how to request permissions, see Requesting Permissions.

2. Set AuthParam (including the challenge, UserAuthType, and AuthTrustLevel), configure WidgetParam, and use getUserAuthInstance to obtain a UserAuthInstance instance.

3. Use UserAuthInstance.on to subscribe to the authentication result.

4. Use UserAuthInstance.start to start authentication. The authentication result UserAuthResult is returned through IAuthCallback. If the authentication is successful, the authentication type (UserAuthType) and token information (AuthToken) are returned.

Example: Initiate facial authentication and lock screen password authentication with the authentication trust level greater than or equal to ATL3.

import type {BusinessError} from '@ohos.base';
import userIAM_userAuth from '@ohos.userIAM.userAuth';

// Set authentication parameters.
const authParam: userIAM_userAuth.AuthParam = {
  challenge: new Uint8Array([49, 49, 49, 49, 49, 49]),
  authType: [userIAM_userAuth.UserAuthType.PIN, userIAM_userAuth.UserAuthType.FACE],
  authTrustLevel: userIAM_userAuth.AuthTrustLevel.ATL3,
};
// Set the authentication page.
const widgetParam: userIAM_userAuth.WidgetParam = {
  title: 'Verify identity',
};
try {
  // Obtain a UserAuthInstance object.
  let userAuthInstance = userIAM_userAuth.getUserAuthInstance(authParam, widgetParam);
  console.log('get userAuth instance success');
  // Subscribe to the authentication result.
  userAuthInstance.on('result', {
    onResult(result) {
      console.log('userAuthInstance callback result = ' + JSON.stringify(result));
      // Unsubscribe from the authentication result if required.
      userAuthInstance.off('result');
    }
  });
  console.log('auth on success');
  userAuthInstance.start();
  console.log('auth start success');
} catch (error) {
  const err: BusinessError = error as BusinessError;
  console.log(`auth catch error. Code is ${err?.code}, message is ${err?.message}`);
}