# @equinor/fusion-framework-module-msal 中文文档

规范地址：https://npmcn.com/package/%40equinor/fusion-framework-module-msal/

版本：12\.1\.0
npm 元数据更新时间：2026-11-12T09:59:08.489Z
中文译文更新时间：2026-11-13T20:13:51.552Z
软件包许可：ISC

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40equinor/fusion-framework-module-msal
原文对照：https://npmcn.com/package/%40equinor/fusion-framework-module-msal/?lang=original
源码仓库：https://github.com/equinor/fusion-framework

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：738 kB，154 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：1 个
- peer 依赖：zod ^4\.0\.0，semver ^7\.0\.0，typescript \>=5\.0\.0，@types/semver ^7\.0\.0，@equinor/fusion-framework-module ^6\.2\.0，@equinor/fusion-framework-module-telemetry ^8\.0\.0
- 首次发布：2022-01-14T12:18:17.197Z
- 最新版本发布：2026-11-12T09:59:07.494Z
- 近 30 天下载量：13463（2026-10-14 至 2026-11-12，npm 官方下载统计）
- 已发布版本数：183（近 12 个月 39 个）

## 中文简介

微软认证库(MSAL)Fusion框架集成模块

## 安装

```sh
npm install @equinor/fusion-framework-module-msal
```

也可以使用：`pnpm add @equinor/fusion-framework-module-msal`、`yarn add @equinor/fusion-framework-module-msal`、`bun add @equinor/fusion-framework-module-msal`

## README

# `@equinor/fusion-framework-module-msal`

`@equinor/fusion-framework-module-msal` 为使用微软的MSAL(微软认证库)的浏览器应用程序提供安全的Azure AD认证. 适合网络应用程序,SPA,以及需要用微软服务认证的React应用软件.

> **版本**: 此软件包现在使用 **MSAL 浏览器 v4**,提供了从微软获取的最新安全改进和功能.

## 特征

-   **单一签名( SSO)** 支持Microsoft Azure AD和Azure AD B2C
-   **托肯管理** 自动刷新和安全的缓存
-   **模块旋转** 跨适用范围共享认证状态
-   **静态认证** 用于无缝用户体验
-   **弹出方向流( R)** 不同认证设想方案
-   **0 配置** 有合理默认和可选择的定制
-   **MSAL v4 兼容性** 使用 v2 代理层进行后向兼容

## 快速启动

```bash
pnpm add @equinor/fusion-framework-module-msal
```

```typescript
import { enableMSAL, initialize, type IMsalProvider } from '@equinor/fusion-framework-module-msal';
import { ModulesConfigurator } from '@equinor/fusion-framework-module';

// 1. Configure the module
const configurator = new ModulesConfigurator();

enableMSAL(configurator, (builder) => {
  builder.setClientConfig({
    auth: {
      clientId: 'your-client-id',
      tenantId: 'your-tenant-id',
      redirectUri: 'https://your-app.com/callback'
    }
  });
  // With requiresAuth=true, the module will attempt automatic login during initialization
  // and await a valid authenticated account before initialization completes
  builder.setRequiresAuth(true);
});

// 2. Initialize the framework (auto-initializes auth provider)
const framework = await initialize(configurator);
const auth: IMsalProvider = framework.auth;

// 3. Optional: Handle authentication redirect manually (auto-called during initialization)
const redirectResult = await auth.handleRedirect();
if (redirectResult?.account) {
  console.log('Authenticated:', redirectResult.account.username);
}

// 4. Use authentication
// Option A: Token acquisition (v4 format - recommended)
const token = await auth.acquireAccessToken({ 
  request: { scopes: ['api://your-app-id/.default'] } 
});

// Option B: Legacy format (still supported via v2 proxy)
const legacyToken = await auth.acquireAccessToken({ 
  scopes: ['api://your-app-id/.default'] 
});

// Option C: Silent authentication with fallback
try {
  const result = await auth.login({ 
    request: { scopes: ['api://your-app-id/.default'] },
    silent: true  // Attempts SSO first
  });
} catch {
  // Fallback to interactive if silent fails
  await auth.login({ 
    request: { scopes: ['api://your-app-id/.default'] },
    behavior: 'popup'
  });
}
```

> \[大 这个 `@equinor/fusion-framework-app` 默认启用此软件包, 因此使用应用程序包的应用程序不需要手动启用此模块 .

## 文档

| 指南 | 封面 |
| --- | --- |
| [配置](https://npmcn.com/package/%40equinor/fusion-framework-module-msal/docs/api-reference.md) | `enableMSAL`,建造方法, `IMsalProvider`和类型定义 |
| [后端发行的 Auth 代码流](https://npmcn.com/package/%40equinor/fusion-framework-module-msal/docs/auth-code-flow.md) | 从后端发布的 SPA auth 代码中签名用户, 没有交互提示 |
| [测试](https://npmcn.com/package/%40equinor/fusion-framework-module-msal/docs/testing.md) | 这个 `/mock` 入境点:在程序内认证、确定标志和间谍 |
| [版本管理](https://npmcn.com/package/%40equinor/fusion-framework-module-msal/docs/version-management.md) | 版本分辨率、兼容性检查和相关错误 |
| [迁移 v2 到 v4](https://npmcn.com/package/%40equinor/fusion-framework-module-msal/docs/migration-v2-to-v4.md) | 从 MSAL 浏览器 v2 移动到 v4, 包括兼容性代理 |
| [解决问题](https://npmcn.com/package/%40equinor/fusion-framework-module-msal/docs/troubleshooting.md) | 常见的失败和寻求帮助的地方 |

## 配置

### 需要设置

| 设置 | 说明 | 需求 |
| --- | --- | --- |
| `auth.clientId` | Azure AD 应用程序客户端ID | ✅ |
| `auth.tenantId` | Azure AD 租户身份证 | ✅ |
| `auth.redirectUri` | 认证召回 URL | 可选 |

### 可选设置

| 设置 | 说明 | 默认 |
| --- | --- | --- |
| `requiresAuth` | 初始化时自动自动自动启动 | `false` |
| `version` | 强制特定 MSAL 版本 | `Latest` |

### 环境变量

```bash
# Required
AZURE_CLIENT_ID=your-client-id
AZURE_TENANT_ID=your-tenant-id

# Optional
AZURE_REDIRECT_URI=https://your-app.com/callback
```

## 操作遥测

当遥测模块可用时,提供者将安全终端结果记录为 `fusion.msal.<operation>.duration` 度量衡: `acquire-token`, (中文(简体) ), `login`, (中文(简体) ), `logout`, (中文(简体) ), `handle-redirect` 财务报告和审定财务报表 `exchange-auth-code`。结果 `success`, (中文(简体) ), `failure` 或者说 `cancelled`。 。 。 。 `user_cancelled` 错误和 MSAL 隐藏中的被压制的获取 iframe是取消。 失败会增加一个消毒器 `.failure` 例外,且失败 在交互式倒计时器添加一个前无声登录 `fusion.msal.silent-login-fallback` 警告 警告他们 脚本、范围、账户、用户名、登录提示、认证代码和原出错 从未被记录。 返回值和抛出的错误不变。 用于 遥测导出请求,标记为 `markTelemetryExportRequest`,没有记录,所以 使用认证的Fusion HTTP客户端的出口商不会生成要导出的记录.

这些记录取代了遗产 `module-msal.acquireToken` b. 衡量和衡量 `acquireToken-failed`, (中文(简体) ), `logout.failed`, (中文(简体) ), `handleRedirect.failed`, (中文(简体) ), `initialize.auth-code-exchange-failed` 财务报告和审定财务报表 `login.silent-failed` 例外情况。 剩余 遗产 `module-msal.*` 事件不再包括 `username`,请求或默认 `scopes`, (中文(简体) ), 登录 `redirectUri`,以及 `canLoginSilently` 是一个布尔.

## 测试

从 `@equinor/fusion-framework-module-msal/mock` 用于认证进程内而不是对 Entra ID 进行认证。 真正的配置器、提供者和计划验证仍在运行——只有接触Entra ID的客户端被替换.

```typescript
import { enableMsalMock } from '@equinor/fusion-framework-module-msal/mock';

enableMsalMock(configurator);
```

一个用户命名 `Test User` 符号是真实的JWT 刻制在进程中,并有固定的发行时间,所以它们在运行和机器上是相同的.

切入点有 **没有测试运行者的依赖性**并且船上没有嘲弄API自己——监视呼叫是你们试跑者的工作.

见 [测试](https://npmcn.com/package/%40equinor/fusion-framework-module-msal/docs/testing.md) 用于选择签名用户、签名退出行为和跑者指导,或 [`@equinor/fusion-framework/mock`](https://npmcn.com/package/framework/docs/testing.md) 以同时嘲笑每个框架边界.

## 模块旋转

该模块执行一种升起模式,即认证提供者在根层创建一次,并在所有子模块中共享。 这将确保整个应用程序的认证状态一致,同时保持安全和性能.

> \[大 **仅在根合并框架实例中配置认证模块** - 子公司将自动继承父公司的认证配置.

## 额外资源

### 正式文件

-   🔐 [Azure AD App 注册指南](https://docs.microsoft.com/en-us/azure/active-directory/develop/quickstart-register-app)
-   📚 [MSAL 浏览器文档](https://github.com/AzureAD/microsoft-authentication-library-for-js/tree/dev/lib/msal-browser)
-   🏗️ [组合框架文档](https://github.com/equinor/fusion-framework)
-   🌐 [微软身份平台概览](https://docs.microsoft.com/en-us/azure/active-directory/develop/)

### 学习资源

-   📖 [MSAL 烹饪手册实例](https://github.com/equinor/fusion-framework/tree/main/cookbooks/app-react-msal)
-   🎯 [OAuth 2.0 范围解释](https://docs.microsoft.com/en-us/azure/active-directory/develop/v2-permissions-and-consent)
-   🛠️ [MSAL 解决问题指南](https://github.com/AzureAD/microsoft-authentication-library-for-js/blob/dev/lib/msal-browser/docs/errors.md)
-   📖 [Azure AD API 权限指南](https://docs.microsoft.com/en-us/azure/active-directory/develop/scenario-protected-web-api-app-registration)

### 支助

-   问题: [融合框架讨论](https://github.com/equinor/fusion-framework/discussions)
-   QQ 报告错误 : [融合框架问题](https://github.com/equinor/fusion-framework/issues)
-   联系人:Equinor融合框架团队

## 常见问题

### @equinor/fusion-framework-module-msal 是什么？

微软认证库\(MSAL\)Fusion框架集成模块

### 如何安装 @equinor/fusion-framework-module-msal？

在项目目录运行 npm install @equinor/fusion-framework-module-msal，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：zod（^4\.0\.0）、semver（^7\.0\.0）、typescript（\>=5\.0\.0）、@equinor/fusion-framework-module（^6\.2\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @equinor/fusion-framework-module-msal 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @equinor/fusion-framework-module-msal 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @equinor/fusion-framework-module-msal 可以商用吗？

@equinor/fusion-framework-module-msal 使用 ISC 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @equinor/fusion-framework-module-msal 的下载量有多少？

根据 npm 官方下载统计，@equinor/fusion-framework-module-msal 在 2026/10/14 – 2026/11/12 这 30 天内被下载 13,463 次，日均约 449 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @equinor/fusion-framework-module-msal 还在维护吗？

最新版本 12\.1\.0 发布于 2026/11/12（1 天前）；至今共发布 183 个版本，其中过去 12 个月发布了 39 个；首次发布于 2022/01/14。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。