@hms.core.authentication (华为账号应用统一认证服务)

模块概述

@hms.core.authentication模块提供华为账号应用统一认证能力，其中登录华为账号与获取华为账号用户信息为核心功能。

• 登录华为账号：获取华为账号用户（使用华为账号登录华为终端设备的用户，以下简称“华为账号用户”）的用户标识（UnionID/OpenID，可参考基本概念），用于与应用原有用户体系进行关联，实现基于华为账号的免注册快速登录。

• 获取华为账号用户信息：申请华为账号用户授权，获取其头像昵称、风险等级等扩展用户信息，用于完善用户个人资料。

在此基础之上，该模块也提供了获取华为账号登录状态、获取手机号一致性状态两种辅助能力，用于优化登录状态管理、完善应用安全风控处理逻辑。

• 获取华为账号登录状态：快速判断当前系统登录的华为账号是否与应用已获取的用户标识（UnionID/OpenID）相匹配，查询系统是否已登录华为账号。

• 获取手机号一致性状态：通过华为账号一键登录获取绑定手机号后，开发者可通过此能力判断开发者获取的手机号、系统华为账号绑定手机号与当前设备SIM卡之间的关系，辅助确认用户身份，用于安全风控处理。

开发者可通过HuaweiIDProvider与AuthenticationController协同实现华为账号统一认证的核心功能。

HuaweiIDProvider：华为账号服务认证工厂类，主要负责创建华为账号登录、授权、取消授权请求对象。开发者可根据具体业务场景灵活配置对象属性。

AuthenticationController：华为账号服务控制器类，负责接收并执行华为账号登录、授权、取消授权请求。开发者需将HuaweiIDProvider创建的请求对象作为入参，调用AuthenticationController.executeRequest方法请求华为账号服务。

[h2]基本概念

• OpenID：应用维度用户标识符，是华为账号用户在应用/元服务的唯一标识。不同应用/元服务（不管是否在同一个开发者账号下）获取到用户的OpenID不同。OpenID严格区分大小写。

• UnionID：开发者维度用户标识符，华为账号用户在同一开发者账号下的唯一标识。开发者有多个应用/元服务时，同一个开发者账号下的应用/元服务获取到用户的UnionID相同。UnionID严格区分大小写。

• Authorization Code：授权码，用户使用华为账号登录成功之后，可通过返回的结果解析出授权码。通过授权码可获取访问凭证Access Token、ID Token等，可参考开放接口调用凭证。

• ID Token：用户身份凭证，是OIDC (OpenID Connect) 协议相对于OAuth 2.0 协议扩展的一个用户身份凭证，包含用户信息。用户使用华为账号登录成功之后，可通过返回的凭据解析出Authorization Code、ID Token等数据。

• Access Token：访问凭证，是访问被权限管控资源的应用级凭证。可使用Access Token调用获取用户信息接口获取用户信息。

[h2]登录华为账号

@hms.core.authentication模块提供安全、便捷的华为账号登录能力。

开发者可通过登录能力获取授权码Authorization Code。应用服务端使用Authorization Code调用获取用户级凭证接口向华为账号服务器请求获取Access Token，使用Access Token调用解析凭证接口获取用户的UnionID/OpenID。应用服务端通过UnionID/OpenID判断该用户是否已关联其原有用户体系。如已关联，则完成用户登录；如未关联，则创建新用户，绑定UnionID/OpenID，完成用户登录。

开发者需使用HuaweiIDProvider构造华为账号登录请求对象，并通过AuthenticationController执行登录请求，流程伪代码如下：

provider = new authentication.HuaweiIDProvider();
loginWithHuaweiIDRequest = provider.createLoginWithHuaweiIDRequest();
controller = new authentication.AuthenticationController(context);
loginWithHuaweiIDResponse = controller.executeRequest(loginWithHuaweiIDRequest);
loginWithHuaweiIDCredential = loginWithHuaweiIDResponse?.data;
code = loginWithHuaweiIDCredential?.authorizationCode; // 由credential可解析出授权码Authorization Code
// 将Authorization Code上传应用服务端，应用服务端请求华为账号服务器获取UnionID/OpenID

[h2]获取华为账号用户信息

@hms.core.authentication模块提供了华为账号授权与取消授权能力，用于获取华为账号头像昵称、风险等级、华为账号绑定的匿名手机号等用户信息，以及管理用户与应用的授权关系。

开发者可通过授权能力申请获取用户信息访问权限，在用户授权后即可获得授权码Authorization Code。应用服务端使用Authorization Code通过获取用户级凭证、获取用户信息向华为账号服务器请求获取Access Token、用户信息。应用获取用户信息后，可用于完善并展示个人资料。

在获取到用户授权后，开发者可通过取消授权能力，主动解除用户授予应用的用户信息访问权限。

开发者需使用HuaweiIDProvider构造授权、取消授权请求对象，并通过AuthenticationController执行请求。流程伪代码如下：

// 授权：
provider = new authentication.HuaweiIDProvider();
authorizationWithHuaweiIDRequest = provider.createAuthorizationWithHuaweiIDRequest();
controller = new authentication.AuthenticationController(context);
authorizationWithHuaweiIDResponse = controller.executeRequest(authorizationWithHuaweiIDRequest);
authorizationWithHuaweiIDCredential = authorizationWithHuaweiIDResponse?.data;
code = authorizationWithHuaweiIDCredential?.authorizationCode; // 由credential可解析出授权码Authorization Code
// 将Authorization Code上传应用服务端，应用服务端请求华为账号服务器获取用户信息

// 取消授权：
cancelAuthorizationRequest = provider.createCancelAuthorizationRequest();
cancelAuthorizationResponse = controller.executeRequest(cancelAuthorizationRequest); // 取消授权成功时返回，失败时返回错误码

[h2]获取华为账号登录状态

@hms.core.authentication模块提供获取华为账号登录状态能力，用于判断当前系统是否已登录华为账号。 开发者获取用户标识（UnionID/OpenID）后，可通过该能力查询华为账号登录状态，不依赖网络连接。

开发者可创建获取华为账号登录状态请求对象，将已获取的用户标识（UnionID/OpenID）传入，查询登录状态。存在如下三种状态，具体可参考State：

• 华为账号未登录。

• 华为账号已登录且传入账号的UnionID/OpenID与当前账号一致。

• 华为账号已登录且传入账号的UnionID/OpenID与当前账号不一致。

[h2]获取手机号一致性状态

@hms.core.authentication模块提供手机号一致性状态校验能力，可校验应用通过华为账号一键登录获取的手机号是否与华为账号绑定的手机号、本机SIM卡一致。当应用登录后需要进行高风险操作时，可通过该能力查询手机号一致性状态，从而进行相应的安全风控处理。

开发者可创建请求对象，将已获取的手机号、用户标识（UnionID/OpenID）传入。Account Kit会判断开发者传入的手机号、华为账号绑定手机号、当前设备SIM卡之间的关系，存在如下三种一致性状态，具体可参考ConsistencyRequest：

• 华为账号已登录，传入的手机号与当前账号绑定的手机号一致，与当前设备任意一个SIM卡手机号一致。

• 华为账号已登录，传入的手机号与当前账号绑定的手机号一致，与当前设备任意一个SIM卡手机号均不一致或当前设备无SIM卡。

• 华为账号已登录，传入的手机号与当前账号绑定的手机号不一致。

起始版本： 4.0.0(10)

导入模块

import { authentication } from '@kit.AccountKit';

HuaweiIDProvider

HuaweiIDProvider为华为账号服务认证工厂类，主要负责创建华为账号登录（LoginWithHuaweiIDRequest）、授权（AuthorizationWithHuaweiIDRequest）、取消授权（CancelAuthorizationRequest）请求对象。开发者可根据业务场景修改对象属性，之后通过AuthenticationController执行请求。

此外，HuaweiIDProvider工厂类还提供了getHuaweiIDState和getMobileNumberConsistency方法，分别用以获取华为账号的登录状态和手机号一致性状态。开发者可根据业务信息，构造StateRequest和ConsistencyRequest作为入参，调用上述方法。

模型约束： 此接口仅可在Stage模型下使用。

元服务API： 从版本4.1.0(11)开始，该接口支持在元服务中使用。

系统能力： SystemCapability.AuthenticationServices.HuaweiID.Auth

起始版本： 4.0.0(10)

继承： HuaweiIDProvider继承自AuthenticationProvider。

[h2]createLoginWithHuaweiIDRequest

createLoginWithHuaweiIDRequest(): LoginWithHuaweiIDRequest

创建并返回华为账号登录请求对象LoginWithHuaweiIDRequest。

通过该方法创建并返回请求对象后，可将其作为入参调用AuthenticationController.executeRequest方法执行华为账号登录请求，获取用户标识（UnionID/OpenID）。

模型约束： 此接口仅可在Stage模型下使用。

元服务API： 从版本4.1.0(11)开始，该接口支持在元服务中使用。

系统能力： SystemCapability.AuthenticationServices.HuaweiID.Auth

起始版本： 4.0.0(10)

返回值：

示例：

参见LoginWithHuaweiIDResponse。

[h2]createAuthorizationWithHuaweiIDRequest

createAuthorizationWithHuaweiIDRequest(): AuthorizationWithHuaweiIDRequest

创建并返回华为账号授权请求对象AuthorizationWithHuaweiIDRequest。

通过该方法创建并返回请求对象后，可将其作为入参调用AuthenticationController.executeRequest方法执行华为账号授权请求，获取用户授权凭据。

模型约束： 此接口仅可在Stage模型下使用。

元服务API： 从版本5.0.0(12)开始，该接口支持在元服务中使用。

系统能力： SystemCapability.AuthenticationServices.HuaweiID.Auth

起始版本： 4.0.0(10)

返回值：

示例：

参见AuthorizationWithHuaweiIDResponse。

[h2]createCancelAuthorizationRequest

createCancelAuthorizationRequest(): CancelAuthorizationRequest

创建并返回华为账号取消授权请求对象CancelAuthorizationRequest。

通过该方法创建并返回请求对象后，可将其作为入参调用AuthenticationController.executeRequest方法执行取消授权请求，主动解除用户授予应用的用户信息访问权限。

模型约束： 此接口仅可在Stage模型下使用。

元服务API： 从版本5.0.0(12)开始，该接口支持在元服务中使用。

系统能力： SystemCapability.AuthenticationServices.HuaweiID.Auth

起始版本： 4.0.0(10)

返回值：

示例：

参见CancelAuthorizationResponse。

[h2]getHuaweiIDState

getHuaweiIDState(request: StateRequest): Promise<StateResult>

获取华为账号登录状态，此方法不依赖网络连接，使用Promise异步回调。

开发者可创建请求对象StateRequest，将已获取的用户标识（UnionID/OpenID）传入（UnionID、OpenID值可以通过登录华为账号、获取华为账号用户信息、华为账号Panel登录组件或华为账号Button登录组件获取）。Account Kit会判断系统是否已登录华为账号、已登录的华为账号是否与开发者传入的用户标识（UnionID/OpenID）相匹配。

存在如下三种状态，具体可参考State：

• 华为账号未登录。

• 华为账号已登录且传入账号的UnionID/OpenID与当前账号一致。

• 华为账号已登录且传入账号的UnionID/OpenID与当前账号不一致。

模型约束： 此接口仅可在Stage模型下使用。

元服务API： 从版本5.0.0(12)开始，该接口支持在元服务中使用。

系统能力： SystemCapability.AuthenticationServices.HuaweiID.Auth

起始版本： 5.0.0(12)

参数：

返回值：

错误码：

以下错误码的详细介绍请参见账号管理错误码和ArkTS错误码。

示例：

import { authentication } from '@kit.AccountKit';
import { hilog } from '@kit.PerformanceAnalysisKit';
import { BusinessError } from '@kit.BasicServicesKit';

// 创建请求参数
const stateRequest: authentication.StateRequest = {
  idType: authentication.IdType.UNION_ID,
  idValue: '<可通过华为账号登录接口获取>' // 该值可以通过华为账号登录接口获取
};
try {
  // 执行获取华为账号登录状态请求，并处理结果
  new authentication.HuaweiIDProvider().getHuaweiIDState(stateRequest).then((data: authentication.StateResult) => {
    hilog.info(0x0000, 'testTag', 'Succeeded in getting huaweiIdState result.');
    const state = data.state;
    // 处理state
  }).catch((error: BusinessError) => {
    dealAllError(error);
  });
} catch (error) {
  dealAllError(error);
}

// 错误处理
function dealAllError(error: BusinessError): void {
  hilog.error(0x0000, 'testTag', `Failed to get huaweiIdState, errorCode=${error.code}, errorMsg=${error.message}`);
}

[h2]getMobileNumberConsistency

getMobileNumberConsistency(request: ConsistencyRequest): Promise<ConsistencyResult>

获取手机号一致性状态，使用Promise异步回调。该方法可用于校验应用通过华为账号一键登录获取的手机号是否与华为账号绑定的手机号、本机SIM卡一致。

开发者可创建请求对象ConsistencyRequest，将已获取的手机号、用户标识（UnionID/OpenID）传入。Account Kit会判断开发者传入的手机号、华为账号绑定手机号、当前设备SIM卡之间的关系。

存在如下三种一致性状态，具体可参考ConsistencyState：

• 华为账号已登录，传入的手机号与当前账号绑定的手机号一致，与当前设备任意一个SIM卡手机号一致。

• 华为账号已登录，传入的手机号与当前账号绑定的手机号一致，与当前设备任意一个SIM卡手机号均不一致或当前设备无SIM卡。

• 华为账号已登录，传入的手机号与当前账号绑定的手机号不一致。

开发者在使用获取手机号一致性状态方法前，需要完成quickLoginMobilePhone（华为账号一键登录）的账号权限申请，详情参见开发前提。账号权限申请审批未完成或未通过，将报错1001502014 应用未申请scopes或permissions权限。

模型约束： 此接口仅可在Stage模型下使用。

系统能力： SystemCapability.AuthenticationServices.HuaweiID.Auth

设备行为差异： 对于6.1.1(24)及之前版本，该接口在Phone、PC/2in1、Tablet中可正常调用，在其他设备类型中返回801错误码。对于26.0.0及之后版本，该接口在Phone、PC/2in1、Tablet、TV中可正常调用，在其他设备类型中返回801错误码。

起始版本： 5.0.0(12)

参数：

返回值：

错误码：

以下错误码的详细介绍请参见通用错误码和ArkTS错误码。

示例：

import { authentication } from '@kit.AccountKit';
import { hilog } from '@kit.PerformanceAnalysisKit';
import { BusinessError } from '@kit.BasicServicesKit';

// 创建请求参数
const consistencyRequest: authentication.ConsistencyRequest = {
  idType: authentication.IdType.UNION_ID,
  idValue: '<可通过华为账号登录接口获取>', // 该值可以通过华为账号登录接口获取
  mobileNumber: '+86xxxxxxxxxxx' // 通过华为账号一键登录功能获取到的明文手机号
};
try {
  // 执行获取手机号一致性状态请求，并处理结果
  new authentication.HuaweiIDProvider().getMobileNumberConsistency(consistencyRequest)
    .then((data: authentication.ConsistencyResult) => {
      hilog.info(0x0000, 'testTag', `Succeeded in getting getMobileNumberConsistency result = ${data.state}`);
      const state = data.state;
      // 处理state
    })
    .catch((err: BusinessError) => {
      dealAllError(err);
    });
} catch (error) {
  dealAllError(error);
}

// 错误处理
function dealAllError(error: BusinessError): void {
  hilog.error(0x0000, 'testTag',
    `Failed to get mobileNumberConsistency, errorCode=${error.code}, errorMsg=${error.message}`);
}

LoginWithHuaweiIDRequest

华为账号登录请求类。

开发者可将请求类对象作为入参，通过调用AuthenticationController.executeRequest方法执行华为账号登录请求，成功时返回LoginWithHuaweiIDResponse登录响应对象，用于获取用户标识（UnionID/OpenID）。

可通过修改该类的属性以控制是否拉起华为账号登录页面、完善业务的安全校验逻辑，具体方式可参考其属性介绍。

模型约束： 此接口仅可在Stage模型下使用。

元服务API： 从版本4.1.0(11)开始，该接口支持在元服务中使用。

系统能力： SystemCapability.AuthenticationServices.HuaweiID.Auth

起始版本： 4.0.0(10)

继承： LoginWithHuaweiIDRequest继承自AuthenticationRequest。

示例：

参见LoginWithHuaweiIDResponse。

IdTokenSignAlgorithm

ID Token签名算法类型枚举。根据IdTokenSignAlgorithm的不同类型，对ID Token进行不同方式的加密。请应用根据实际安全要求、性能、系统环境兼容性进行选择。

模型约束： 此接口仅可在Stage模型下使用。

元服务API： 从版本4.1.0(11)开始，该接口支持在元服务中使用。

系统能力： SystemCapability.AuthenticationServices.HuaweiID.Auth

起始版本： 4.0.0(10)

示例：

参见LoginWithHuaweiIDResponse。

LoginWithHuaweiIDResponse

华为账号登录响应类，包含了属性data和state。属性data为华为账号登录凭据对象，用于获取授权码、用户标识（UnionID/OpenID）等数据；属性state则用于防止跨站攻击。

模型约束： 此接口仅可在Stage模型下使用。

元服务API： 从版本4.1.0(11)开始，该接口支持在元服务中使用。

系统能力： SystemCapability.AuthenticationServices.HuaweiID.Auth

起始版本： 4.0.0(10)

继承： LoginWithHuaweiIDResponse继承自AuthenticationResponse。

示例：

import { authentication } from '@kit.AccountKit';
import { hilog } from '@kit.PerformanceAnalysisKit';
import { util } from '@kit.ArkTS';
import { BusinessError } from '@kit.BasicServicesKit';

// 创建登录请求，并设置参数
const loginRequest = new authentication.HuaweiIDProvider().createLoginWithHuaweiIDRequest();
// 默认值为true，若账号未登录则强制拉起账号登录页
loginRequest.forceLogin = true;
loginRequest.idTokenSignAlgorithm = authentication.IdTokenSignAlgorithm.PS256;
loginRequest.state = util.generateRandomUUID(); // 建议使用generateRandomUUID生成state，可用于一致性比对，防止跨站攻击

// 执行登录请求，并处理结果
try {
  // 此示例为代码片段，实际需在自定义组件实例中使用，并传入有效的Context上下文对象
  const controller = new authentication.AuthenticationController(this.getUIContext().getHostContext());
  controller.executeRequest(loginRequest, (error: BusinessError<Object>, data) => {
    if (error) {
      dealAllError(error);
      return;
    }
    const loginWithHuaweiIDResponse = data as authentication.LoginWithHuaweiIDResponse;
    const state = loginWithHuaweiIDResponse.state;
    // state为空时，归一化处理为空字符串
    const normalizedRequestState = loginRequest.state || '';
    const normalizedState = state || '';
    if (normalizedRequestState !== normalizedState) {
      // state不一致，可能为跨站攻击，需重新登录
      hilog.error(0x0000, 'testTag', `Failed to login. The state is different, response state: ${state}`);
      return;
    }
    hilog.info(0x0000, 'testTag', 'Succeeded in login.');
    const loginWithHuaweiIDCredential = loginWithHuaweiIDResponse?.data;
    const authorizationCode = loginWithHuaweiIDCredential?.authorizationCode;
    const idToken = loginWithHuaweiIDCredential?.idToken;
    // 开发者处理authorizationCode, idToken
  });
} catch (error) {
  dealAllError(error);
}

// 错误处理
function dealAllError(error: BusinessError<Object>): void {
  hilog.error(0x0000, 'testTag', `Failed to login. Code: ${error.code}, message: ${error.message}`);
  // 在应用登录涉及UI交互场景下，建议按照如下错误码指导提示用户
  if (error.code === ErrorCode.ERROR_CODE_LOGIN_OUT) {
    // 用户未登录华为账号，请登录华为账号并重试或者尝试使用其他方式登录
  } else if (error.code === ErrorCode.ERROR_CODE_NETWORK_ERROR) {
    // 网络错误，请检查当前网络状态并重试
  } else if (error.code === ErrorCode.ERROR_CODE_INTERNAL_ERROR) {
    // 登录失败，请尝试使用其他方式登录
  } else if (error.code === ErrorCode.ERROR_CODE_USER_CANCEL) {
    // 用户取消授权
  } else if (error.code === ErrorCode.ERROR_CODE_SYSTEM_SERVICE) {
    // 系统服务异常，请稍后重试或者尝试使用其他方式登录
  } else if (error.code === ErrorCode.ERROR_CODE_REQUEST_REFUSE) {
    // 重复请求，应用无需处理
  } else {
    // 应用登录失败，请尝试使用其他方式登录
  }
}

export enum ErrorCode {
  // 账号未登录
  ERROR_CODE_LOGIN_OUT = 1001502001,
  // 网络错误
  ERROR_CODE_NETWORK_ERROR = 1001502005,
  // 内部错误
  ERROR_CODE_INTERNAL_ERROR = 1001502009,
  // 用户取消授权
  ERROR_CODE_USER_CANCEL = 1001502012,
  // 系统服务异常
  ERROR_CODE_SYSTEM_SERVICE = 12300001,
  // 重复请求
  ERROR_CODE_REQUEST_REFUSE = 1001500002
}

LoginWithHuaweiIDCredential

华为账号登录凭据。登录成功后返回的凭据结构体，可用于获取授权码Authorization Code、用户标识（UnionID/OpenID）等数据。

推荐使用Authorization Code，通过应用服务端与华为账号服务端交互获取UnionID/OpenID，可有效防范数据拦截、泄露等安全风险，交互流程可参考登录华为账号。此外，该类型同时也包含了属性OpenID、UnionID，开发者若选择直接使用，需自行保障数据安全。

模型约束： 此接口仅可在Stage模型下使用。

元服务API： 从版本4.1.0(11)开始，该接口支持在元服务中使用。

系统能力： SystemCapability.AuthenticationServices.HuaweiID.Auth

起始版本： 4.0.0(10)

示例：

参见LoginWithHuaweiIDResponse。

AuthorizationWithHuaweiIDRequest

华为账号授权请求类。

开发者可将请求类对象作为入参，通过调用AuthenticationController.executeRequest方法执行华为账号授权请求，成功时返回AuthorizationWithHuaweiIDResponse授权响应对象，用于获取用户授权凭据。

当执行华为账号授权请求且属性forceAuthorization设置为true时，若系统未登录华为账号，会先拉起华为账号登录页面以完成用户登录；若用户已登录华为账号且未授权，则会拉起华为账号授权页面。

可通过修改该类的属性以设置应用需要访问的用户信息范围，也可用于控制是否拉起登录、授权页面，以及完善业务的安全校验逻辑，具体方式可参考其属性介绍。

模型约束： 此接口仅可在Stage模型下使用。

系统能力： SystemCapability.AuthenticationServices.HuaweiID.Auth

起始版本： 4.0.0(10)

继承： AuthorizationWithHuaweiIDRequest继承自AuthenticationRequest。

示例：

参见AuthorizationWithHuaweiIDResponse。

AuthorizationWithHuaweiIDResponse

华为账号授权响应类，包含了属性data和state。属性data为用户授权凭据对象，用于获取授权码、用户信息等数据；属性state则用于防止跨站攻击。

模型约束： 此接口仅可在Stage模型下使用。

元服务API： 从版本5.0.0(12)开始，该接口支持在元服务中使用。

系统能力： SystemCapability.AuthenticationServices.HuaweiID.Auth

起始版本： 4.0.0(10)

继承： AuthorizationWithHuaweiIDResponse继承自AuthenticationResponse。

示例：

import { authentication } from '@kit.AccountKit';
import { hilog } from '@kit.PerformanceAnalysisKit';
import { util } from '@kit.ArkTS';
import { BusinessError } from '@kit.BasicServicesKit';

// 创建授权请求，并设置参数
const authRequest = new authentication.HuaweiIDProvider().createAuthorizationWithHuaweiIDRequest();
// 'openid'为默认值可不传，开发者若需要获取其他用户信息，可传入其他scope参数，具体请参考AuthorizationWithHuaweiIDRequest类说明
authRequest.scopes = ['openid'];
authRequest.permissions = ['idtoken', 'serviceauthcode'];
authRequest.forceAuthorization = true;
authRequest.state = util.generateRandomUUID(); // 建议使用generateRandomUUID生成state，可用于一致性比对，防止跨站攻击
authRequest.idTokenSignAlgorithm = authentication.IdTokenSignAlgorithm.PS256;

// 执行授权请求，并处理结果
try {
  // 此示例为代码片段，实际需在自定义组件实例中使用，并传入有效的Context上下文对象
  const controller = new authentication.AuthenticationController(this.getUIContext().getHostContext());
  controller.executeRequest(authRequest, (error: BusinessError<Object>, data) => {
    if (error) {
      dealAllError(error);
      return;
    }
    const authorizationWithHuaweiIDResponse = data as authentication.AuthorizationWithHuaweiIDResponse;
    const state = authorizationWithHuaweiIDResponse.state;
    // state为空时，归一化处理为空字符串
    const normalizedRequestState = authRequest.state || '';
    const normalizedState = state || '';
    if (normalizedRequestState !== normalizedState) {
      // state不一致，可能为跨站攻击，需重新授权
      hilog.error(0x0000, 'testTag', `Failed to authorize. The state is different, response state: ${state}`);
      return;
    }
    hilog.info(0x0000, 'testTag', 'Succeeded in authentication.');
    const authorizationWithHuaweiIDCredential = authorizationWithHuaweiIDResponse?.data;
    const authorizationCode = authorizationWithHuaweiIDCredential?.authorizationCode;
    const idToken = authorizationWithHuaweiIDCredential?.idToken;
    // 开发者处理authorizationCode, idToken等信息
  });
} catch (error) {
  dealAllError(error);
}

// 错误处理
function dealAllError(error: BusinessError<Object>): void {
  hilog.error(0x0000, 'testTag', `Failed to obtain userInfo. Code: ${error.code}, message: ${error.message}`);
  // 在涉及UI交互场景下，建议按照如下错误码指导提示用户
  if (error.code === ErrorCode.ERROR_CODE_LOGIN_OUT) {
    // 用户未登录华为账号，请登录华为账号并重试
  } else if (error.code === ErrorCode.ERROR_CODE_NETWORK_ERROR) {
    // 网络错误，请检查当前网络状态并重试
  } else if (error.code === ErrorCode.ERROR_CODE_USER_CANCEL) {
    // 用户取消授权
  } else if (error.code === ErrorCode.ERROR_CODE_SYSTEM_SERVICE) {
    // 系统服务异常，请稍后重试
  } else if (error.code === ErrorCode.ERROR_CODE_REQUEST_REFUSE) {
    // 重复请求，应用无需处理
  } else {
    // 获取用户信息失败，请稍后重试
  }
}

export enum ErrorCode {
  // 账号未登录
  ERROR_CODE_LOGIN_OUT = 1001502001,
  // 网络错误
  ERROR_CODE_NETWORK_ERROR = 1001502005,
  // 用户取消授权
  ERROR_CODE_USER_CANCEL = 1001502012,
  // 系统服务异常
  ERROR_CODE_SYSTEM_SERVICE = 12300001,
  // 重复请求
  ERROR_CODE_REQUEST_REFUSE = 1001500002
}

AuthorizationWithHuaweiIDCredential

华为账号授权凭据。授权成功后返回的结构体，可用于获取授权码、用户信息（例如头像昵称、邮箱、匿名手机号）等数据。

推荐使用Authorization Code，通过应用服务端与华为账号服务端交互获取用户信息，可有效防范数据拦截、泄露等安全风险，交互流程可参考获取华为账号用户信息。此外，该接口同时也包含了部分用户信息，开发者若选择直接使用，需自行保障数据安全。

模型约束： 此接口仅可在Stage模型下使用。

系统能力： SystemCapability.AuthenticationServices.HuaweiID.Auth

起始版本： 4.0.0(10)

示例：

参见AuthorizationWithHuaweiIDResponse。

CancelAuthorizationRequest

取消授权请求类。该类包含了属性state，用于防止跨站攻击。开发者可将请求类对象作为入参，通过调用AuthenticationController.executeRequest方法执行取消授权请求，主动解除用户授予应用的用户信息访问权限。

模型约束： 此接口仅可在Stage模型下使用。

元服务API： 从版本5.0.0(12)开始，该接口支持在元服务中使用。

系统能力： SystemCapability.AuthenticationServices.HuaweiID.Auth

起始版本： 4.0.0(10)

继承： CancelAuthorizationRequest继承自AuthenticationRequest。

示例：

参见CancelAuthorizationResponse。

CancelAuthorizationResponse

取消授权响应类。该类包含了属性state，用于防止跨站攻击。

模型约束： 此接口仅可在Stage模型下使用。

元服务API： 从版本5.0.0(12)开始，该接口支持在元服务中使用。

系统能力： SystemCapability.AuthenticationServices.HuaweiID.Auth

起始版本： 4.0.0(10)

继承： CancelAuthorizationResponse继承自AuthenticationResponse。

示例：

import { authentication } from '@kit.AccountKit';
import { hilog } from '@kit.PerformanceAnalysisKit';
import { util } from '@kit.ArkTS';
import { BusinessError } from '@kit.BasicServicesKit';

// 创建取消授权请求，并设置参数
const cancelRequest = new authentication.HuaweiIDProvider().createCancelAuthorizationRequest();
cancelRequest.state = util.generateRandomUUID(); // 建议使用generateRandomUUID生成state，可用于一致性比对，防止跨站攻击

// 执行取消授权请求，并处理结果
try {
  // 此示例为代码片段，实际需在自定义组件实例中使用，并传入有效的Context上下文对象
  const controller = new authentication.AuthenticationController(this.getUIContext().getHostContext());
  controller.executeRequest(cancelRequest, (error: BusinessError<Object>, data) => {
    if (error) {
      dealAllError(error);
      return;
    }
    const cancelAuthorizationResponse = data as authentication.CancelAuthorizationResponse;
    const state = cancelAuthorizationResponse.state;
    // state为空时，归一化处理为空字符串
    const normalizedRequestState = cancelRequest.state || '';
    const normalizedState = state || '';
    if (normalizedRequestState !== normalizedState) {
      // state不一致，可能为跨站攻击，需重新取消授权
      hilog.error(0x0000, 'testTag', `Failed to cancel. The state is different, response state: ${state}`);
      return;
    }
    hilog.info(0x0000, 'testTag', 'Succeeded in canceling.');
  });
} catch (error) {
  dealAllError(error);
}

// 错误处理
function dealAllError(error: BusinessError<Object>): void {
  hilog.error(0x0000, 'testTag', `Failed to cancel. Code: ${error.code}, message: ${error.message}`);
  // 在应用登录涉及UI交互场景下，建议按照如下错误码指导提示用户
  if (error.code === ErrorCode.ERROR_CODE_LOGIN_OUT) {
    // 用户未登录华为账号，请登录华为账号并重试或者尝试使用其他方式登录
  } else if (error.code === ErrorCode.ERROR_CODE_NETWORK_ERROR) {
    // 网络错误，请检查当前网络状态并重试
  } else if (error.code === ErrorCode.ERROR_CODE_INTERNAL_ERROR) {
    // 登录失败，请尝试使用其他方式登录
  } else if (error.code === ErrorCode.ERROR_CODE_USER_CANCEL) {
    // 用户取消授权
  } else if (error.code === ErrorCode.ERROR_CODE_SYSTEM_SERVICE) {
    // 系统服务异常，请稍后重试或者尝试使用其他方式登录
  } else if (error.code === ErrorCode.ERROR_CODE_REQUEST_REFUSE) {
    // 重复请求，应用无需处理
  } else {
    // 应用登录失败，请尝试使用其他方式登录
  }
}

export enum ErrorCode {
  // 账号未登录
  ERROR_CODE_LOGIN_OUT = 1001502001,
  // 网络错误
  ERROR_CODE_NETWORK_ERROR = 1001502005,
  // 内部错误
  ERROR_CODE_INTERNAL_ERROR = 1001502009,
  // 用户取消授权
  ERROR_CODE_USER_CANCEL = 1001502012,
  // 系统服务异常
  ERROR_CODE_SYSTEM_SERVICE = 12300001,
  // 重复请求
  ERROR_CODE_REQUEST_REFUSE = 1001500002
}

AuthenticationErrorCode

华为账号认证服务接口错误码枚举。应用可根据如下错误码进行不同的处理。

模型约束： 此接口仅可在Stage模型下使用。

系统能力： SystemCapability.AuthenticationServices.HuaweiID.Auth

起始版本： 4.0.0(10)

AuthenticationController

华为账号服务的控制器类，负责接收并执行华为账号登录（LoginWithHuaweiIDRequest）、授权（AuthorizationWithHuaweiIDRequest）、取消授权（CancelAuthorizationRequest）请求。开发者可将HuaweiIDProvider工厂类创建的请求对象作为入参，调用executeRequest方法请求华为账号服务。

模型约束： 此接口仅可在Stage模型下使用。

元服务API： 从版本4.1.0(11)开始，该接口支持在元服务中使用。

系统能力： SystemCapability.AuthenticationServices.HuaweiID.Auth

起始版本： 4.0.0(10)

[h2]constructor

constructor(context?: common.Context)

控制器类构造器，用于构造AuthenticationController实例。

模型约束： 此接口仅可在Stage模型下使用。

元服务API： 从版本4.1.0(11)开始，该接口支持在元服务中使用。

系统能力： SystemCapability.AuthenticationServices.HuaweiID.Auth

起始版本： 4.0.0(10)

参数：

示例：

参见AuthenticationController.executeRequest。

[h2]executeRequest

executeRequest(request: AuthenticationRequest, callback: AsyncCallback<AuthenticationResponse, Record<string, Object>>): void

执行请求方法，AuthenticationController类成员函数，使用callback异步回调。该方法用于接收并执行华为账号登录（LoginWithHuaweiIDRequest）、授权（AuthorizationWithHuaweiIDRequest）、取消授权（CancelAuthorizationRequest）请求，并返回华为账号登录（LoginWithHuaweiIDResponse）、授权（AuthorizationWithHuaweiIDResponse）、取消授权（CancelAuthorizationResponse）响应结果。

通过createLoginWithHuaweiIDRequest、createAuthorizationWithHuaweiIDRequest、createCancelAuthorizationRequest构造请求对象后，使用该方法执行请求。

通过该接口执行华为账号登录（LoginWithHuaweiIDRequest）或授权（AuthorizationWithHuaweiIDRequest）请求、且属性forceLogin或forceAuthorization设置为true时，若系统未登录华为账号，则会拉起华为账号登录页面；若已登录且用户未对应用授权，则会拉起华为账号授权页面。用户在页面中可长时间停留，完成登录/授权后，Account Kit才会向应用返回成功结果，其他场景（如用户点击关闭页面）则返回对应的错误码。开发者可根据此规则，合理规划接口的调用时机，避免因接口长时间未返回结果而导致业务逻辑阻塞。

模型约束： 此接口仅可在Stage模型下使用。

元服务API： 从版本4.1.0(11)开始，该接口支持在元服务中使用。

系统能力： SystemCapability.AuthenticationServices.HuaweiID.Auth

起始版本： 4.0.0(10)

参数：

错误码：

以下错误码的详细介绍请参见通用错误码、账号管理错误码和ArkTS错误码。

示例：

import { authentication } from '@kit.AccountKit';
import { hilog } from '@kit.PerformanceAnalysisKit';
import { util } from '@kit.ArkTS';
import { BusinessError } from '@kit.BasicServicesKit';

// 创建授权请求，并设置参数
const authRequest = new authentication.HuaweiIDProvider().createAuthorizationWithHuaweiIDRequest();
// 'openid'为默认值可不传，开发者若需要获取其他用户信息，可传入其他scope参数，具体请参考AuthorizationWithHuaweiIDRequest类说明
authRequest.scopes = ['openid'];
authRequest.permissions = ['idtoken', 'serviceauthcode'];
authRequest.forceAuthorization = true;
authRequest.state = util.generateRandomUUID(); // 建议使用generateRandomUUID生成state，可用于一致性比对，防止跨站攻击
authRequest.idTokenSignAlgorithm = authentication.IdTokenSignAlgorithm.PS256;

// 执行授权请求，并处理结果
try {
  // 此示例为代码片段，实际需在自定义组件实例中使用，并传入有效的Context上下文对象
  const controller = new authentication.AuthenticationController(this.getUIContext().getHostContext());
  controller.executeRequest(authRequest, (error: BusinessError<Object>, data) => {
    if (error) {
      dealAllError(error);
      return;
    }
    const authorizationWithHuaweiIDResponse = data as authentication.AuthorizationWithHuaweiIDResponse;
    const state = authorizationWithHuaweiIDResponse.state;
    // state为空时，归一化处理为空字符串
    const normalizedRequestState = authRequest.state || '';
    const normalizedState = state || '';
    if (normalizedRequestState !== normalizedState) {
      // state不一致，可能为跨站攻击，需重新授权
      hilog.error(0x0000, 'testTag', `Failed to authorize. The state is different, response state: ${state}`);
      return;
    }
    hilog.info(0x0000, 'testTag', 'Succeeded in authentication.');
    const authorizationWithHuaweiIDCredential = authorizationWithHuaweiIDResponse?.data;
    const authorizationCode = authorizationWithHuaweiIDCredential?.authorizationCode;
    const idToken = authorizationWithHuaweiIDCredential?.idToken;
    // 开发者处理authorizationCode, idToken等信息
  });
} catch (error) {
  dealAllError(error);
}

// 错误处理
function dealAllError(error: BusinessError<Object>): void {
  hilog.error(0x0000, 'testTag', `Failed to obtain userInfo. Code: ${error.code}, message: ${error.message}`);
  // 在涉及UI交互场景下，建议按照如下错误码指导提示用户
  if (error.code === ErrorCode.ERROR_CODE_LOGIN_OUT) {
    // 用户未登录华为账号，请登录华为账号并重试
  } else if (error.code === ErrorCode.ERROR_CODE_NETWORK_ERROR) {
    // 网络错误，请检查当前网络状态并重试
  } else if (error.code === ErrorCode.ERROR_CODE_USER_CANCEL) {
    // 用户取消授权
  } else if (error.code === ErrorCode.ERROR_CODE_SYSTEM_SERVICE) {
    // 系统服务异常，请稍后重试
  } else if (error.code === ErrorCode.ERROR_CODE_REQUEST_REFUSE) {
    // 重复请求，应用无需处理
  } else {
    // 获取用户信息失败，请稍后重试
  }
}

export enum ErrorCode {
  // 账号未登录
  ERROR_CODE_LOGIN_OUT = 1001502001,
  // 网络错误
  ERROR_CODE_NETWORK_ERROR = 1001502005,
  // 用户取消授权
  ERROR_CODE_USER_CANCEL = 1001502012,
  // 系统服务异常
  ERROR_CODE_SYSTEM_SERVICE = 12300001,
  // 重复请求
  ERROR_CODE_REQUEST_REFUSE = 1001500002
}

[h2]executeRequest

executeRequest(request: AuthenticationRequest): Promise<AuthenticationResponse>

执行请求方法，AuthenticationController类成员函数，该方法用于接收并执行华为账号登录（LoginWithHuaweiIDRequest）、授权（AuthorizationWithHuaweiIDRequest）、取消授权（CancelAuthorizationRequest）请求，并返回华为账号登录（LoginWithHuaweiIDResponse）、授权（AuthorizationWithHuaweiIDResponse）、取消授权（CancelAuthorizationResponse）响应结果。 使用Promise异步回调。

通过createLoginWithHuaweiIDRequest、createAuthorizationWithHuaweiIDRequest、createCancelAuthorizationRequest构造请求对象后，使用该方法执行请求。

通过该接口执行华为账号登录（LoginWithHuaweiIDRequest）或授权（AuthorizationWithHuaweiIDRequest）请求、且属性forceLogin或forceAuthorization设置为true时，若系统未登录华为账号，则会拉起华为账号登录页面；若已登录且用户未对应用授权，则会拉起华为账号授权页面。用户在页面中可长时间停留，完成登录/授权后，Account Kit才会向应用返回成功结果，其他场景（如用户点击关闭）则返回对应的错误码。开发者可根据此规则，合理规划接口的调用时机，避免因接口长时间未返回结果而导致业务逻辑阻塞。

模型约束： 此接口仅可在Stage模型下使用。

元服务API： 从版本4.1.0(11)开始，该接口支持在元服务中使用。

系统能力： SystemCapability.AuthenticationServices.HuaweiID.Auth

起始版本： 4.0.0(10)

参数：

返回值：

错误码：

以下错误码的详细介绍请参见通用错误码、账号管理错误码和ArkTS错误码。

示例：

import { authentication } from '@kit.AccountKit';
import { hilog } from '@kit.PerformanceAnalysisKit';
import { util } from '@kit.ArkTS';
import { BusinessError } from '@kit.BasicServicesKit';

// 创建授权请求，并设置参数
const authRequest = new authentication.HuaweiIDProvider().createAuthorizationWithHuaweiIDRequest();
// 'openid'为默认值可不传，开发者若需要获取其他用户信息，可传入其他scope参数，具体请参考AuthorizationWithHuaweiIDRequest类说明
authRequest.scopes = ['openid'];
authRequest.permissions = ['idtoken', 'serviceauthcode'];
authRequest.forceAuthorization = true;
authRequest.state = util.generateRandomUUID(); // 建议使用generateRandomUUID生成state，可用于一致性比对，防止跨站攻击
authRequest.idTokenSignAlgorithm = authentication.IdTokenSignAlgorithm.PS256;

// 执行授权请求，并处理结果
try {
  // 此示例为代码片段，实际需在自定义组件实例中使用，并传入有效的Context上下文对象
  const controller = new authentication.AuthenticationController(this.getUIContext().getHostContext());
  controller.executeRequest(authRequest).then((data) => {
    const authorizationWithHuaweiIDResponse = data as authentication.AuthorizationWithHuaweiIDResponse;
    const state = authorizationWithHuaweiIDResponse.state;
    // state为空时，归一化处理为空字符串
    const normalizedRequestState = authRequest.state || '';
    const normalizedState = state || '';
    if (normalizedRequestState !== normalizedState) {
      // state不一致，可能为跨站攻击，需重新授权
      hilog.error(0x0000, 'testTag', `Failed to authorize. The state is different, response state: ${state}`);
      return;
    }
    hilog.info(0x0000, 'testTag', 'Succeeded in authentication.');
    const authorizationWithHuaweiIDCredential = authorizationWithHuaweiIDResponse?.data;
    const authorizationCode = authorizationWithHuaweiIDCredential?.authorizationCode;
    const idToken = authorizationWithHuaweiIDCredential?.idToken;
    // 开发者处理authorizationCode, idToken等信息
  }).catch((err: BusinessError) => {
    dealAllError(err);
  });
} catch (error) {
  dealAllError(error);
}

// 错误处理
function dealAllError(error: BusinessError): void {
  hilog.error(0x0000, 'testTag', `Failed to obtain userInfo. Code: ${error.code}, message: ${error.message}`);
  // 在涉及UI交互场景下，建议按照如下错误码指导提示用户
  if (error.code === ErrorCode.ERROR_CODE_LOGIN_OUT) {
    // 用户未登录华为账号，请登录华为账号并重试
  } else if (error.code === ErrorCode.ERROR_CODE_NETWORK_ERROR) {
    // 网络错误，请检查当前网络状态并重试
  } else if (error.code === ErrorCode.ERROR_CODE_USER_CANCEL) {
    // 用户取消授权
  } else if (error.code === ErrorCode.ERROR_CODE_SYSTEM_SERVICE) {
    // 系统服务异常，请稍后重试
  } else if (error.code === ErrorCode.ERROR_CODE_REQUEST_REFUSE) {
    // 重复请求，应用无需处理
  } else {
    // 获取用户信息失败，请稍后重试
  }
}

export enum ErrorCode {
  // 账号未登录
  ERROR_CODE_LOGIN_OUT = 1001502001,
  // 网络错误
  ERROR_CODE_NETWORK_ERROR = 1001502005,
  // 用户取消授权
  ERROR_CODE_USER_CANCEL = 1001502012,
  // 系统服务异常
  ERROR_CODE_SYSTEM_SERVICE = 12300001,
  // 重复请求
  ERROR_CODE_REQUEST_REFUSE = 1001500002
}

AuthenticationRequest

华为账号认证请求抽象基类。该类不包含实际业务属性，具体认证请求请参考其派生类。派生类包含LoginWithHuaweiIDRequest、AuthorizationWithHuaweiIDRequest、CancelAuthorizationRequest。

模型约束： 此接口仅可在Stage模型下使用。

元服务API： 从版本4.1.0(11)开始，该接口支持在元服务中使用。

系统能力： SystemCapability.AuthenticationServices.HuaweiID.Auth

起始版本： 4.0.0(10)

AuthenticationResponse

华为账号认证响应抽象基类。该类不包含实际业务属性，具体响应结果请参考其派生类。派生类包含LoginWithHuaweiIDResponse、AuthorizationWithHuaweiIDResponse、CancelAuthorizationResponse。

模型约束： 此接口仅可在Stage模型下使用。

元服务API： 从版本4.1.0(11)开始，该接口支持在元服务中使用。

系统能力： SystemCapability.AuthenticationServices.HuaweiID.Auth

起始版本： 4.0.0(10)

AuthenticationProvider

华为账号认证工厂抽象基类。该类不包含实际业务属性，具体实现请参考其派生类。派生类包含HuaweiIDProvider。

模型约束： 此接口仅可在Stage模型下使用。

元服务API： 从版本4.1.0(11)开始，该接口支持在元服务中使用。

系统能力： SystemCapability.AuthenticationServices.HuaweiID.Auth

起始版本： 4.0.0(10)

IdType

华为账号用户标识类型枚举。

模型约束： 此接口仅可在Stage模型下使用。

元服务API： 从版本5.0.0(12)开始，该接口支持在元服务中使用。

系统能力： SystemCapability.AuthenticationServices.HuaweiID.Auth

起始版本： 5.0.0(12)

State

华为账号登录状态类型枚举。标识系统是否已登录华为账号、已登录的华为账号是否与开发者传入的用户标识（UnionID/OpenID）相一致。

模型约束： 此接口仅可在Stage模型下使用。

元服务API： 从版本5.0.0(12)开始，该接口支持在元服务中使用。

系统能力： SystemCapability.AuthenticationServices.HuaweiID.Auth

起始版本： 5.0.0(12)

StateRequest

获取华为账号登录状态请求。请求需包含idType、idValue属性，用于指定华为账号用户标识类型并传入实际的用户标识（UnionID/OpenID）。将该请求对象作为入参，通过调用getHuaweiIDState方法，即可判断系统是否已登录华为账号、已登录的华为账号是否与开发者传入的用户标识相匹配。

模型约束： 此接口仅可在Stage模型下使用。

元服务API： 从版本5.0.0(12)开始，该接口支持在元服务中使用。

系统能力： SystemCapability.AuthenticationServices.HuaweiID.Auth

起始版本： 5.0.0(12)

示例：

参见getHuaweiIDState。

StateResult

获取华为账号登录状态响应。getHuaweiIDState方法返回值。标识系统是否已登录华为账号、已登录的华为账号是否与开发者传入的用户标识（UnionID/OpenID）相匹配。

模型约束： 此接口仅可在Stage模型下使用。

元服务API： 从版本5.0.0(12)开始，该接口支持在元服务中使用。

系统能力： SystemCapability.AuthenticationServices.HuaweiID.Auth

起始版本： 5.0.0(12)

示例：

参见getHuaweiIDState。

ConsistencyState

手机号一致性状态枚举。标识开发者传入的手机号、华为账号绑定手机号、当前设备SIM卡之间的关系。应用可根据结果进行相应风控处理。

模型约束： 此接口仅可在Stage模型下使用。

系统能力： SystemCapability.AuthenticationServices.HuaweiID.Auth

起始版本： 5.0.0(12)

ConsistencyRequest

获取手机号一致性状态请求。请求需包含idType、idValue、mobileNumber属性。用于指定华为账号用户标识类型（UnionID/OpenID）、传入实际的用户标识UnionID/OpenID值以及手机号。将请求对象作为入参，通过调用getMobileNumberConsistency方法，即可获取开发者传入的手机号、华为账号绑定手机号、当前设备SIM卡之间的关系。

模型约束： 此接口仅可在Stage模型下使用。

系统能力： SystemCapability.AuthenticationServices.HuaweiID.Auth

起始版本： 5.0.0(12)

示例：

参见getMobileNumberConsistency。

ConsistencyResult

获取手机号一致性状态响应。getMobileNumberConsistency方法返回值。标识开发者传入的手机号、华为账号绑定手机号、当前设备SIM卡之间的关系。应用可根据结果进行相应风控处理。

模型约束： 此接口仅可在Stage模型下使用。

系统能力： SystemCapability.AuthenticationServices.HuaweiID.Auth

起始版本： 5.0.0(12)

示例：

参见getMobileNumberConsistency。