@ohos.userIAM.userAuth (用户认证)(系统接口)

提供用户认证能力，可应用于设备解锁、支付、应用登录等身份认证场景。

说明：

• 本模块首批接口从API version 6开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。
• 当前页面仅包含本模块的系统接口，其他公开接口参见@ohos.userIAM.userAuth (用户认证)。

导入模块

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

AuthParam¹⁰⁺

用户认证相关参数。

系统能力：SystemCapability.UserIAM.UserAuth.Core

WindowModeType¹⁰⁺

用户认证界面的显示类型。

系统能力：SystemCapability.UserIAM.UserAuth.Core

系统接口: 此接口为系统接口。

WidgetParam¹⁰⁺

用户认证界面配置相关参数。

系统能力：SystemCapability.UserIAM.UserAuth.Core

NoticeType¹⁰⁺

用户身份认证的通知类型。

系统能力：SystemCapability.UserIAM.UserAuth.Core

系统接口: 此接口为系统接口。

userAuth.sendNotice¹⁰⁺

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

在使用统一身份认证控件进行用户身份认证时，用于接收来自统一身份认证控件的通知。

需要权限：ohos.permission.SUPPORT_USER_AUTH

系统能力：SystemCapability.UserIAM.UserAuth.Core

系统接口: 此接口为系统接口。

参数：

错误码：

以下错误码的详细介绍请参见用户认证错误码。

示例：

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¹⁰⁺

组件管理接口，可将用身份认证控件注册到UserAuthWidgetMgr中，由UserAuthWidgetMgr进行管理、调度。

on¹⁰⁺

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

身份认证控件订阅来自用户认证框架的命令。

系统能力：SystemCapability.UserIAM.UserAuth.Core

系统接口: 此接口为系统接口。

参数：

错误码：

以下错误码的详细介绍请参见用户认证错误码。

示例：

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

身份认证控件取消订阅来自用户认证框架的命令。

系统能力：SystemCapability.UserIAM.UserAuth.Core

系统接口: 此接口为系统接口。

参数：

错误码：

以下错误码的详细介绍请参见用户认证错误码。

示例：

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

获取UserAuthWidgetMgr对象，用于执行用户身份认证。

说明： 每个UserAuthInstance只能进行一次认证，若需要再次进行认证则需重新获取UserAuthInstance。

需要权限：ohos.permission.SUPPORT_USER_AUTH

系统能力：SystemCapability.UserIAM.UserAuth.Core

系统接口: 此接口为系统接口。

参数：

返回值：

错误码：

以下错误码的详细介绍请参见用户认证错误码。

示例：

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¹⁰⁺

认证组件通过该回调获取用户认证框架发送的命令。

sendCommand¹⁰⁺

sendCommand(cmdData: string): void

回调函数，用于用户认证框架向组件发送命令。

系统能力：SystemCapability.UserIAM.UserAuth.Core

系统接口: 此接口为系统接口。

参数：

示例：

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⁸⁺

表示身份认证的凭据类型枚举。

系统能力：SystemCapability.UserIAM.UserAuth.Core

示例：

发起用户认证，采用认证可信等级≥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: '请输入密码',
  };

  const userAuthInstance = userAuth.getUserAuthInstance(authParam, widgetParam);
  console.info('get userAuth instance success');
  // 需要调用UserAuthInstance的start()接口，启动认证后，才能通过onResult获取到认证结果。
  userAuthInstance.on('result', {
    onResult (result) {
      console.info(`userAuthInstance callback result = ${JSON.stringify(result)}`);
    }
  });
  console.info('auth on success');
  userAuthInstance.start();
  console.info('auth start success');
} catch (error) {
  const err: BusinessError = error as BusinessError;
  console.error(`auth catch error. Code is ${err?.code}, message is ${err?.message}`);
}

UserAuthResultCode¹⁸⁺

表示返回码的枚举。

系统能力：SystemCapability.UserIAM.UserAuth.Core

你可能感兴趣的鸿蒙文章

harmony 鸿蒙User Authentication Kit（用户认证服务）

harmony 鸿蒙用户认证错误码

harmony 鸿蒙@ohos.userIAM.faceAuth (人脸认证)(系统接口)

harmony 鸿蒙@ohos.userIAM.userAccessCtrl (用户访问控制)(系统接口)

harmony 鸿蒙@ohos.userIAM.userAuth (用户认证)

harmony 鸿蒙@ohos.userIAM.userAuthIcon (嵌入式用户身份认证控件)