@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 代理层进行后向兼容

快速启动

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

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 默认启用此软件包, 因此使用应用程序包的应用程序不需要手动启用此模块 .

文档

配置

需要设置

可选设置

环境变量

# 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的客户端被替换.

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

enableMsalMock(configurator);

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

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

见 测试 用于选择签名用户、签名退出行为和跑者指导,或 @equinor/fusion-framework/mock 以同时嘲笑每个框架边界.

模块旋转

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

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

额外资源

正式文件

• 🔐 Azure AD App 注册指南
• 📚 MSAL 浏览器文档
• 🏗️ 组合框架文档
• 🌐 微软身份平台概览

学习资源

• 📖 MSAL 烹饪手册实例
• 🎯 OAuth 2.0 范围解释
• 🛠️ MSAL 解决问题指南
• 📖 Azure AD API 权限指南

支助

• 问题: 融合框架讨论
• QQ 报告错误 : 融合框架问题
• 联系人:Equinor融合框架团队