@ohos.userIAM.userAuth (User Authentication) (System API)

The userIAM.userAuth module provides user authentication capabilities in identity authentication scenarios, such as device unlocking, payment, and app login.

NOTE

• 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.
• This topic describes only the system APIs provided by the module. For details about its public APIs, see @ohos.userIAM.userAuth (User Authentication).

Modules to Import

import { userAuth } from '@kit.UserAuthenticationKit';

AuthParam¹⁰⁺

Represents the user authentication parameters.

System capability: SystemCapability.UserIAM.UserAuth.Core

WindowModeType¹⁰⁺

Enumerates the window types of the authentication widget.

System capability: SystemCapability.UserIAM.UserAuth.Core

System API: This is a system API.

WidgetParam¹⁰⁺

Represents the information presented on the user authentication page.

System capability: SystemCapability.UserIAM.UserAuth.Core

NoticeType¹⁰⁺

Defines the type of the user authentication notification.

System capability: SystemCapability.UserIAM.UserAuth.Core

System API: This is a system API.

userAuth.sendNotice¹⁰⁺

sendNotice(noticeType: NoticeType, eventData: string): void

Sends a notification from the user authentication widget.

Required permissions: ohos.permission.SUPPORT_USER_AUTH

System capability: SystemCapability.UserIAM.UserAuth.Core

System API: This is a system API.

Parameters

Error codes

For details about the error codes, see User Authentication Error Codes.

Example

import { userAuth } from '@kit.UserAuthenticationKit';

interface  EventData {
  widgetContextId: number;
  event: string;
  version: string;
  payload: PayLoad;
}
interface PayLoad {
  type: Object[];
}
try {
  const eventData : EventData = {
    widgetContextId: 123456,
    event: 'EVENT_AUTH_TYPE_READY',
    version: '1',
    payload: {
      type: ['pin']
    } as PayLoad,
  };
  const jsonEventData = JSON.stringify(eventData);
  let noticeType = userAuth.NoticeType.WIDGET_NOTICE;
  userAuth.sendNotice(noticeType, jsonEventData);
  console.info('sendNotice success');
} catch (error) {
  console.error(`sendNotice catch error: ${JSON.stringify(error)}`);
}

UserAuthWidgetMgr¹⁰⁺

Provides APIs for managing the user authentication widget. You can use the APIs to register the user authentication widget with UserAuthWidgetMgr for management and scheduling.

on¹⁰⁺

on(type: ‘command’, callback: IAuthWidgetCallback): void

Subscribes to commands from the user authentication framework for the user authentication widget.

System capability: SystemCapability.UserIAM.UserAuth.Core

System API: This is a system API.

Parameters

Error codes

For details about the error codes, see User Authentication Error Codes.

Example

import { userAuth } from '@kit.UserAuthenticationKit';

const userAuthWidgetMgrVersion = 1;
try {
  let userAuthWidgetMgr = userAuth.getUserAuthWidgetMgr(userAuthWidgetMgrVersion);
  console.info('get userAuthWidgetMgr instance success');
  userAuthWidgetMgr.on('command', {
    sendCommand(cmdData) {
      console.info(`The cmdData is ${cmdData}`);
    }
  })
  console.info('subscribe authentication event success');
} catch (error) {
  console.error(`userAuth widgetMgr catch error: ${JSON.stringify(error)}`);
}

off¹⁰⁺

off(type: ‘command’, callback?: IAuthWidgetCallback): void

Unsubscribes from commands sent from the user authentication framework.

System capability: SystemCapability.UserIAM.UserAuth.Core

System API: This is a system API.

Parameters

Error codes

For details about the error codes, see User Authentication Error Codes.

Example

import { userAuth } from '@kit.UserAuthenticationKit';

const userAuthWidgetMgrVersion = 1;
try {
  let userAuthWidgetMgr = userAuth.getUserAuthWidgetMgr(userAuthWidgetMgrVersion);
  console.info('get userAuthWidgetMgr instance success');
  userAuthWidgetMgr.off('command', {
    sendCommand(cmdData) {
      console.info(`The cmdData is ${cmdData}`);
    }
  })
  console.info('cancel subscribe authentication event success');
} catch (error) {
  console.error(`userAuth widgetMgr catch error: ${JSON.stringify(error)}`);
}

userAuth.getUserAuthWidgetMgr¹⁰⁺

getUserAuthWidgetMgr(version: number): UserAuthWidgetMgr

Obtains a UserAuthWidgetMgr instance for user authentication.

NOTE
A UserAuthInstance instance can be used for an authentication only once.

Required permissions: ohos.permission.SUPPORT_USER_AUTH

System capability: SystemCapability.UserIAM.UserAuth.Core

System API: This is a system API.

Parameters

Return value

Error codes

For details about the error codes, see User Authentication Error Codes.

Example

import { userAuth } from '@kit.UserAuthenticationKit';

let userAuthWidgetMgrVersion = 1;
try {
  let userAuthWidgetMgr = userAuth.getUserAuthWidgetMgr(userAuthWidgetMgrVersion);
  console.info('get userAuthWidgetMgr instance success');
} catch (error) {
  console.error(`userAuth widgetMgr catch error: ${JSON.stringify(error)}`);
}

IAuthWidgetCallback¹⁰⁺

Provides the callback for returning the commands sent from the user authentication framework to the user authentication widget.

sendCommand¹⁰⁺

sendCommand(cmdData: string): void

Called to return the command sent from the user authentication framework to the user authentication widget.

System capability: SystemCapability.UserIAM.UserAuth.Core

System API: This is a system API.

Parameters

Example

import { userAuth } from '@kit.UserAuthenticationKit';

const userAuthWidgetMgrVersion = 1;
try {
  let userAuthWidgetMgr = userAuth.getUserAuthWidgetMgr(userAuthWidgetMgrVersion);
  console.info('get userAuthWidgetMgr instance success');
  userAuthWidgetMgr.on('command', {
    sendCommand(cmdData) {
      console.info(`The cmdData is ${cmdData}`);
    }
  })
  console.info('subscribe authentication event success');
} catch (error) {
  console.error(`userAuth widgetMgr catch error: ${JSON.stringify(error)}`);
}

UserAuthType⁸⁺

Enumerates the identity authentication types.

System capability: SystemCapability.UserIAM.UserAuth.Core

Example

Initiate private password authentication with the authentication trust level greater than or equal to ATL3.

import { BusinessError } from '@kit.BasicServicesKit';
import { cryptoFramework } from '@kit.CryptoArchitectureKit';
import { userAuth } from '@kit.UserAuthenticationKit';

try {
  const rand = cryptoFramework.createRandom();
  const len: number = 16;
  const randData: Uint8Array = rand?.generateRandomSync(len)?.data;
  const authParam: userAuth.AuthParam = {
    challenge: randData,
    authType: [userAuth.UserAuthType.PRIVATE_PIN],
    authTrustLevel: userAuth.AuthTrustLevel.ATL3,
  };
  const widgetParam: userAuth.WidgetParam = {
    title: 'Enter password',
  };

  const userAuthInstance = userAuth.getUserAuthInstance(authParam, widgetParam);
  console.info('get userAuth instance success');
  // The authentication result is returned by onResult() only after the authentication is started by start() of UserAuthInstance.
  userAuthInstance.on('result', {
    onResult (result) {
      console.info(`userAuthInstance callback result = ${JSON.stringify(result)}`);
    }
  });
  console.info('auth on success');
} catch (error) {
  const err: BusinessError = error as BusinessError;
  console.error(`auth catch error. Code is ${err?.code}, message is ${err?.message}`);
}

UserAuthResultCode¹⁸⁺

Enumerates the authentication result codes.

System capability: SystemCapability.UserIAM.UserAuth.Core

你可能感兴趣的鸿蒙文章

harmony 鸿蒙User Authentication Kit (User Authentication Service)

harmony 鸿蒙User Authentication Error Codes

harmony 鸿蒙@ohos.userIAM.faceAuth (Facial Authentication) (System API)

harmony 鸿蒙@ohos.userIAM.userAccessCtrl (User Access Control) (System API)

harmony 鸿蒙@ohos.userIAM.userAuth (User Authentication)

harmony 鸿蒙@ohos.userIAM.userAuthIcon (Embedded User Authentication Widget)