HarmonyOS 原生微软身份登录 SDK,以编译好的 HAR 产物分发。
下载最新版本 · English · 发布说明 · 安装集成 · API 参考 · H5 JSBridge · 问题排查
非 Microsoft 官方项目。 本项目是社区维护的 HarmonyOS 原生实现, 与 Microsoft Corporation 没有隶属或背书关系。Microsoft、Microsoft Entra、 MSAL 是 Microsoft Corporation 的商标。使用前请阅读 免责声明。
这是一个产物分发仓库:只包含编译后的 .har、类型声明、文档和校验和,
不包含 SDK 的 ArkTS 实现源码。
msal-harmony-0.1.0.har
├── package/ets/modules.abc # 编译后的 ArkTS 字节码
├── package/src/**/*.d.ets # 公开类型声明
├── package/Index.d.ets # 入口声明
└── package/oh-package.json5 # @msal/harmony@0.1.0
HAR 已按 buildMode=release 构建(debug=false),不包含实现源码或 source map。
类型声明用于 DevEco Studio 的代码补全和 ArkTS 类型检查。
- Authorization Code + PKCE(S256) 公共客户端登录,不保存 client secret
- 系统浏览器登录:通过 Implicit Want 打开默认浏览器,回调 URI 交回 SDK
- ArkWeb 内嵌登录:
createAuthorizationRequest()+Web.onLoadIntercept() - 静默令牌:access token 缓存命中、refresh token 续期
- 多账户缓存:按
homeAccountId/username查询账户 - OIDC 登出:可清理本地缓存,也可打开 end-session 清理浏览器会话
- Asset Store 持久化:默认使用 HarmonyOS 硬件级加密的 Asset Store
- 可插拔缓存:实现
MsalCacheStorage即可接入企业密钥库 - Authority 支持:AAD、B2C、CIAM、ADFS,以及中国云、US Gov、德国云、法国云
- 安全校验:state、nonce、PKCE、id_token
aud/azp/exp - 可控日志:日志级别和回调;SDK 本身不输出 token、code 或 claims 原文
- 30 个主机侧协议单元测试通过
适合:
- HarmonyOS 原生 App 需要微软 / Microsoft Entra 账号登录
- 需要把 Microsoft access token 换成自有服务端 token 的业务
- 需要在 H5 容器里通过 JSBridge 复用原生微软登录
- 需要系统浏览器或 ArkWeb 两种登录体验
不适合:
- 需要 Microsoft Authenticator broker / 设备 SSO / Intune 的高保障场景
- 需要 POP(Proof of Possession)令牌
- 需要 Native Authentication(邮箱 OTP / 原生密码)
- 需要进程被杀后恢复浏览器登录会话
- 需要服务端校验 Microsoft token 的场景(服务端仍应自行校验签名、issuer、audience)
| 项目 | 要求 |
|---|---|
| 运行时 | HarmonyOS / OpenHarmony API 17+(compatibleSdkVersion: 17) |
| HAR 构建目标 | OpenHarmony SDK 20 |
| 推荐 IDE | DevEco Studio 5.0.5+;0.1.0 使用 DevEco Studio 26.0.0 验证 |
| 语言 | ArkTS |
| 网络权限 | ohos.permission.INTERNET |
| 回调方式 | 自定义 scheme + launchType: singleton |
HAR 的
compatibleSdkVersion是 17。实际项目可以用更高的 compileSdk / targetSdk; 0.1.0 在 HarmonyOS 6(API 26)工程中完成过编译和真机回调验证。
当前只通过 GitHub Releases 分发,未发布到 ohpm 公共仓库。
从 Releases 下载:
msal-harmony-0.1.0.har
放到工程的公共目录,例如:
libs/msal-harmony-0.1.0.har
在需要使用 SDK 的模块的 oh-package.json5 中:
{
"dependencies": {
"@msal/harmony": "file:../libs/msal-harmony-0.1.0.har"
}
}file: 路径是相对于该模块 oh-package.json5 的路径,请按实际目录调整。
然后执行:
ohpm install在 entry/src/main/module.json5 中:
{
"module": {
"requestPermissions": [
{ "name": "ohos.permission.INTERNET" }
],
"abilities": [
{
"name": "EntryAbility",
"srcEntry": "./ets/entryability/EntryAbility.ets",
"launchType": "singleton",
"exported": true,
"skills": [
{
"actions": ["ohos.want.action.viewData"],
"entities": ["entity.system.browsable"],
"uris": [
{
"scheme": "msal11111111-2222-3333-4444-555555555555",
"host": "auth"
}
]
}
]
}
]
}
}scheme 必须和 config.redirectUri 完全一致。默认重定向 URI 格式是:
msal<clientId>://auth
例如 clientId 是 11111111-2222-3333-4444-555555555555:
msal11111111-2222-3333-4444-555555555555://auth
这是 HarmonyOS 社区版的默认格式。它与 MSAL iOS 的
msauth.<bundleId>://auth不同。如果要复用已有 iOS / Android 注册, 请显式设置config.redirectUri,并在module.json5注册对应 scheme。
- 注册应用,选择 Mobile and desktop applications。
- 添加自定义 Redirect URI:
msal<clientId>://auth(或你自己的显式 URI)。 - 在 API permissions 添加所需 scope,例如
User.Read。 - 不需要 client secret:这是公共客户端,使用 PKCE。
SDK 的 MsalPublicClientApplication 必须保持为同一个实例,否则浏览器回调回来时
找不到 pending 的 state / code_verifier。
// MsalService.ets
import { common } from '@kit.AbilityKit';
import {
MsalAuthority,
MsalPublicClientApplication,
MsalPublicClientApplicationConfig
} from '@msal/harmony';
const CLIENT_ID = 'YOUR_CLIENT_ID';
const AUTHORITY = 'https://login.microsoftonline.com/YOUR_TENANT_ID';
const REDIRECT_URI = `msal${CLIENT_ID}://auth`;
let app: MsalPublicClientApplication | undefined;
export function getMsalApp(context?: common.UIAbilityContext): MsalPublicClientApplication {
if (app !== undefined) {
return app;
}
if (context === undefined) {
throw new Error('MsalPublicClientApplication requires a UIAbilityContext.');
}
const config = new MsalPublicClientApplicationConfig(
CLIENT_ID,
MsalAuthority.parse(AUTHORITY),
REDIRECT_URI
);
app = new MsalPublicClientApplication(config, context);
return app;
}import { MsalInteractiveTokenParameters, MsalPromptType } from '@msal/harmony';
const msal = getMsalApp();
const parameters = new MsalInteractiveTokenParameters(['User.Read']);
parameters.promptType = MsalPromptType.SELECT_ACCOUNT;
const result = await msal.acquireTokenInteractive(parameters);
console.info(`signed in: ${result.account.username}`);
console.info(`expires: ${result.expiresOn.toISOString()}`);acquireTokenInteractive() 会打开系统浏览器,并返回一个 Promise。Promise 在宿主 App
把回调 URI 传给 handleResponse() 后完成。
在 EntryAbility 的 onCreate 和 onNewWant 中都要处理:
import { AbilityConstant, UIAbility, Want } from '@kit.AbilityKit';
import { MsalPublicClientApplication } from '@msal/harmony';
import { getMsalApp } from '../service/MsalService';
export default class EntryAbility extends UIAbility {
onCreate(want: Want, launchParam: AbilityConstant.LaunchParam): void {
const msal = getMsalApp(this.context);
this.forwardMsalResponse(msal, want);
}
onNewWant(want: Want, launchParam: AbilityConstant.LaunchParam): void {
const msal = getMsalApp(this.context);
this.forwardMsalResponse(msal, want);
}
private forwardMsalResponse(msal: MsalPublicClientApplication, want: Want): void {
if (want.uri !== undefined && want.uri.length > 0) {
const handled = msal.handleResponse(want.uri);
if (handled) {
return;
}
}
// 继续处理 AppLink / 其他 deep link
}
}handleResponse() 返回 true 表示这是当前 MSAL 会话的回调,并已被消费;
返回 false 时宿主可以继续处理其他 URI。
import { MsalSilentTokenParameters } from '@msal/harmony';
const account = await msal.accountForIdentifier(result.account.identifier);
if (account === undefined) {
// 缓存被清理,需要重新交互登录
} else {
const silent = new MsalSilentTokenParameters(['User.Read'], account);
const refreshed = await msal.acquireTokenSilent(silent);
}acquireTokenSilent() 的行为:
- 命中未过期的 access token,直接返回;
- 否则用 refresh token 换新 token;
- refresh token 失效(
invalid_grant)时返回INTERACTION_REQUIRED,应重新交互登录。
import { MsalSignoutParameters } from '@msal/harmony';
const accounts = await msal.allAccounts();
const account = await msal.accountForUsername('user@contoso.com');
if (account !== undefined) {
const signout = new MsalSignoutParameters();
signout.signoutFromBrowser = true; // 同时打开 OIDC end-session,清浏览器 cookie
await msal.signoutWithAccount(account, signout);
}系统浏览器是推荐路径。如果产品必须把登录页嵌在 App 内:
import { webview } from '@kit.ArkWeb';
import { MsalInteractiveTokenParameters } from '@msal/harmony';
const controller = new webview.WebviewController();
const msal = getMsalApp();
const request = await msal.createAuthorizationRequest(
new MsalInteractiveTokenParameters(['User.Read'])
);
Web({ src: request.url, controller: controller })
.onLoadIntercept((event) => {
const url = event.data.getRequestUrl();
if (msal.handleResponse(url)) {
return true; // 拦截回调,阻止 Web 继续导航
}
return false;
});
const result = await request.result;注意:
- 同一时间只允许一个 pending 交互会话;
- 回调被拦截后关闭
Web组件即可实现“登录后自动 dismiss”; - 内嵌 WebView 可能被 Conditional Access 策略拒绝;生产环境优先系统浏览器;
acquireTokenInteractive()不能驱动内嵌组件,内嵌必须使用 上面的createAuthorizationRequest()。
HAR 只负责原生 OAuth/MSAL,不包含某个 H5 容器的 bridge。社区版文档给出了
msLogin / msLogout 的推荐契约和原生侧实现方式:
核心原则:
- H5 不接触 Microsoft access token;
- 原生完成 MSAL 登录后,用 Microsoft token 调业务服务端换取 B 端 token;
msLogin只把业务 token 返回给 H5;msLogout清理 MSAL 缓存和业务 token。
默认使用 MsalAssetCacheStorage:
- 数据写入 HarmonyOS Asset Store;
- 由系统使用硬件级密钥保护;
- 仅当前 App 可访问;
- 设备首次解锁后可读(
DEVICE_FIRST_UNLOCKED)。
测试或特殊场景可替换为内存缓存:
import { MsalMemoryCacheStorage } from '@msal/harmony';
config.cacheConfig.storage = new MsalMemoryCacheStorage();企业密钥库 / 文件兜底等场景实现接口即可:
import { MsalCacheStorage } from '@msal/harmony';
export class MyCacheStorage implements MsalCacheStorage {
async read(): Promise<string | undefined> { /* ... */ }
async write(data: string): Promise<void> { /* ... */ }
async clear(): Promise<void> { /* ... */ }
}缓存里包含 access token、refresh token、id token、账户和 claims。 不要打印、上传或跨用户共享缓存内容。
import { MsalError, MsalErrorCode, MsalLogger, MsalLogLevel } from '@msal/harmony';
MsalLogger.setLogLevel(MsalLogLevel.INFO);
MsalLogger.setLogCallback((level, message, containsPii) => {
// SDK 不输出 token / code / claims;这里也不要额外打印它们
console.info(`[MSAL] ${message}`);
});
try {
await msal.acquireTokenSilent(parameters);
} catch (error) {
if (error instanceof MsalError) {
if (error.code === MsalErrorCode.INTERACTION_REQUIRED) {
// 重新走交互式登录
}
console.error(`${error.code} ${error.message} ${error.oauthError ?? ''}`);
}
}常见错误:
| 错误码 | 含义 | 处理 |
|---|---|---|
INTERACTION_REQUIRED |
需要重新登录/同意 | 重新交互登录 |
USER_CANCELED |
用户取消/超时 | 提示后重试 |
INVALID_GRANT |
refresh token 失效 | 清缓存后重新登录 |
INVALID_STATE |
回调 state 不匹配 | 拒绝回调,重新发起 |
INVALID_RESPONSE |
token / id_token 格式异常 | 记录 correlationId 排查 |
NETWORK_ERROR |
网络失败 | 重试或提示 |
FAILED_AUTHORITY_VALIDATION |
authority 未通过校验 | 加 knownAuthorities 或修正配置 |
CACHE_ERROR |
Asset Store 读写失败 | 检查设备能力,改用自定义缓存 |
INTERACTIVE_SESSION_ALREADY_RUNNING |
已有 pending 登录 | 先 cancel 或等待完成 |
| 类型 | 作用 |
|---|---|
MsalPublicClientApplication |
登录、静默令牌、账户、登出入口 |
MsalPublicClientApplicationConfig |
clientId、authority、redirectUri、缓存、端点 |
MsalAuthority |
AAD / B2C / CIAM / ADFS authority |
MsalInteractiveTokenParameters |
交互式登录参数 |
MsalSilentTokenParameters |
静默令牌参数 |
MsalSignoutParameters |
登出参数 |
MsalResult |
access token、id token、账户、authority、correlationId |
MsalAccount |
账户标识、username、tenant profiles |
MsalCacheStorage |
自定义 token 缓存接口 |
MsalLogger / MsalError |
日志和错误 |
完整说明见 API 参考。
本 SDK 参考 MSAL iOS 的公开 API、OAuth 2.0 / OIDC 行为和令牌缓存模型, 用 ArkTS 重新实现 HarmonyOS 平台层:
| iOS MSAL | HarmonyOS 社区版 |
|---|---|
ASWebAuthenticationSession / Safari |
系统浏览器 + Implicit Want |
WKWebView |
createAuthorizationRequest() + ArkWeb Web |
| Keychain | Asset Store |
NSURLSession |
@ohos.net.http |
| Objective-C completion block | Promise / async |
handleMSALResponse |
handleResponse(url) |
这不是 Objective-C 代码的逐行翻译,也不包含 Microsoft 的源代码。
- 未经过第三方安全审计;
- 不支持 Authenticator broker / 设备 SSO / SSO extension;
- 不支持 POP、Intune / MAM / WPJ;
- 不支持 Native Authentication;
- 不做 authority metadata discovery,端点按 AAD v2.0 规则拼接,可用
MsalAuthorityEndpoints覆盖; - 不支持进程被杀后的登录会话恢复;
- 内嵌 WebView 可能受 Conditional Access 限制;
- 只支持 Bearer token,不支持 POP;
- 日志和错误信息不包含 token,但集成方仍需避免记录敏感数据。
请阅读 SECURITY.md。关键点:
- 只使用授权码 + PKCE,不保存 client secret;
state、nonce、code_verifier使用系统安全随机数;- 回调校验 state;id_token 校验 nonce、aud、exp;
- token 缓存默认在 Asset Store;
- SDK 不记录 token、code、refresh token 或 raw claims;
- 服务端仍需验证 access token 的签名、issuer、audience、scope;
- 本 SDK 尚未经过独立安全审计。
shasum -a 256 -c SHA256SUMSartifacts/SHA256SUMS 包含 HAR 的 SHA-256。发布页同时提供
msal-harmony-0.1.0.zip 和校验和。
- 包名:
@msal/harmony - 当前版本:
0.1.0 - 版本遵循 SemVer;
0.x阶段不保证 API 完全稳定。 - 升级前请阅读 CHANGELOG.md,并重新执行
ohpm install。
- Bug / 集成问题:使用 GitHub Issues,并附上 DevEco Studio / SDK / 设备版本,
以及脱敏后的
MsalLogger日志。 - 安全漏洞:不要公开提交 Issue,请阅读 SECURITY.md。
- 本仓库只分发产物,不接受 SDK 实现源码 PR;功能建议和集成问题欢迎反馈。
本项目是独立的社区项目,不是 Microsoft 官方产品,也未获得 Microsoft 的认可或支持。 Microsoft、Microsoft Entra、MSAL 及相关标识是 Microsoft Corporation 的商标。 使用本 SDK 即表示你理解并接受:你需要自行评估其安全性、合规性和适用性, 并自行承担使用风险。SDK 按 “AS IS” 提供,不附带任何明示或暗示担保。
MIT。详见 LICENSE。
参与本项目即表示同意遵守 CODE_OF_CONDUCT.md。