# @equinor/fusion-framework-module-azure-identity 中文文档

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

版本：0\.4\.0
npm 元数据更新时间：2026-11-12T09:55:30.356Z
中文译文更新时间：2026-11-13T20:30:07.202Z
软件包许可：ISC

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

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

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

- 包体积（解压后）：419 kB，58 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：4 个
- 首次发布：2026-04-29T08:09:49.286Z
- 最新版本发布：2026-11-12T09:55:30.151Z
- 近 30 天下载量：8253（2026-10-14 至 2026-11-12，npm 官方下载统计）
- 已发布版本数：14（近 12 个月 14 个）

## 中文简介

使用 Azure 身份的Fusion框架认证模块. 支持环境证书(Default AzureCreditic),交互式浏览器登录,以及静态令牌模式.

## 安装

```sh
npm install @equinor/fusion-framework-module-azure-identity
```

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

## README

# @ equinor/ 组合框架- 模块- azure- 标识

Azure身份认证模块用于Fusion框架. 提供三种认证模式——环境证书、交互式浏览器登录和静态符牌——所有都登记在 `'auth'` 模块插槽作为滴入替换 `@equinor/fusion-framework-module-msal-node`。 。 。 .

## 何时使用

| 假设 | 模式 |
| --- | --- |
| CI/CD 与 OIDC (GitHub 动作) `azure/login`(阿苏雷管道) | `default_credential` |
| 管理身份(Azure VMS、App Service、集装箱Apps) | `default_credential` |
| Azure CLI 登录(`az login`自动流动 | `default_credential` |
| 需要用户通过浏览器登录的 CLI 工具 | `interactive` |
| 预取的脚本 `FUSION_TOKEN` | `token_only` |

本单元和 `@equinor/fusion-framework-module-msal-node` 登记 `'auth'` 插槽,所以每次只能有一个活动.

## 安装

```sh
pnpm add @equinor/fusion-framework-module-azure-identity
```

## 快开始

### 默认证书( CI/ CD, 有管理的身份)

不需要配置——证书由环境自动解决.

```typescript
import { enableAzureIdentityAuth } from '@equinor/fusion-framework-module-azure-identity';

enableAzureIdentityAuth(configurator);
```

### 交互式浏览器登录

为 Azure AD 登录打开用户的默认浏览器. 脚指和脚指 `AuthenticationRecord` 被缓存到 OS 键链中,所以以后的引用会默默解决.

```typescript
import { enableAzureIdentityInteractive } from '@equinor/fusion-framework-module-azure-identity';

enableAzureIdentityInteractive(configurator, {
  tenantId: '3aa4a235-...',
  clientId: 'a318b8e1-...',
  redirectPort: 49741,
  onOpen: (url) => console.log(`Open: ${url}`),
});
```

### 静态符号

使用预获取的访问符 。 不支持登录和关闭 .

```typescript
import { enableAzureIdentityTokenOnly } from '@equinor/fusion-framework-module-azure-identity';

enableAzureIdentityTokenOnly(configurator, process.env.FUSION_TOKEN!);
```

### 获取令牌

初始化后,获得与MSAL模块相同的符号:

```typescript
const token = await framework.auth.acquireAccessToken({
  request: { scopes: ['api://my-api/.default'] },
});
```

## 认证模式

### `default_credential` 环境环境

用途 `DefaultAzureCredential` 尝试这些源的顺序:

1.  **环境变量** (单位:千美元)`AZURE_CLIENT_ID`, (中文(简体) ), `AZURE_TENANT_ID`, (中文(简体) ), `AZURE_FEDERATED_TOKEN_FILE`页:1
2.  **工作量身份** (Kubernetes 舱与Azure 工作负荷身份)
3.  **管理身份** (Azure VMS, App Services, Container Apps) (英语)
4.  **阿苏尔CLI** (单位:千美元)`az login` 届会)
5.  **Azure 动力壳** (单位:千美元)`Connect-AzAccount` 届会)
6.  **Azure 开发者 CLI** (单位:千美元)`azd auth login` 届会)

在 GitHub 动作后 `azure/login@v3` 与 OIDC 连接,可自动使用选项1.

`login()` 财务报告和审定财务报表 `logout()` 抛出——没有交互式会话可管理.

### `interactive` ——基于浏览器的登录

用途 `InteractiveBrowserCredential` 授权代码通过本地主机重定向流出。 为CLI工具所设计(`ffc auth login`, (中文(简体) ), `ffc auth token`) (中文(简体) ).

-   首先打开 Azure AD 登录的浏览器
-   保存 `AuthenticationRecord` 通过 OS 级安全存储 `@azure/msal-node-extensions` (MacOS上的钥匙链,Windows上的DPAPI,Linux上的libsecret)
-   之后运行时, 将记录装入并默默从缓存证书中获取符号

```typescript
// Explicit login (opens browser)
const record = await framework.auth.login({
  request: { scopes: ['api://my-api/.default'] },
});
console.log('Logged in as', record.username);

// Silent token acquisition (no browser)
const token = await framework.auth.acquireAccessToken({
  request: { scopes: ['api://my-api/.default'] },
});

// Clear cached credentials
await framework.auth.logout();
```

### `token_only` ——静态访问符

返回一个预定义的符号字符串. `login()` 财务报告和审定财务报表 `logout()` 掷出.

## 操作遥测

当一个遥测模块与该模块一起注册时,提供者记录 `acquireToken` (哪个) `acquireAccessToken` 使用), `login` 财务报告和审定财务报表 `logout` 作为 `fusion.azure-identity.acquire-token.duration`, (中文(简体) ), `fusion.azure-identity.login.duration` 财务报告和审定财务报表 `fusion.azure-identity.logout.duration`用一个消毒 `.failure` 失败者除外. 磁盘、范围、账户、设备代码和原始错误从未记录,结果 错误不变。 静态 `token_only` 供应商从未安装过仪器,要求远程测量出口 请求,标记为 `markTelemetryExportRequest`,不记录。 无 遥测提供者未受影响;无论哪种方式,包都保持节点相容.

## 测试

`token_only` 模式已经避免了真实的 Azure AD 流量,但它是刚性:一个单 固定的代号,没有过期模拟,以及 `login`编号 :`logout` 总是扔。 测试 需要使用 `MockAuthProvider` 从 `/mock` 子路径 :

```typescript
import { enableAuthMock } from '@equinor/fusion-framework-module-azure-identity/mock';

// seed the identity/state up front; omit the callback for a default, already-signed-in identity
const auth = enableAuthMock(configurator, (auth) => {
  auth.setAccount({ username: 'ada@equinor.com', signedOut: true });
});

// drive login/logout and inspect the resulting tokens directly
await auth.login({ request: { scopes: ['User.Read'] } });
const token = await auth.acquireAccessToken({ request: { scopes: ['User.Read'] } });

// simulate an expired token, to exercise a consuming application's refresh path
auth.setExpiresOn(new Date(Date.now() - 1000));
```

`MockAuthProvider` 登记簿和任何其他的一样 `IAuthProvider` 执行 ——无特案接线——并实现无实 `@azure/identity` 网络呼叫.

## 切换缓存持续

模块登记册 `cachePersistencePlugin` 从 `@azure/identity-cache-persistence` 在加载时间时,启用加密的 OS 级令牌缓存 :

| 平台 | 后端 |
| --- | --- |
| 马科斯 | 键盘链 |
| 窗口 | 政治部 |
| 链接 | 自由机密 |

单位 `interactive` 模式,则 `AuthenticationRecord` (账号元数据显示缓存的要向上查找的符号的证书)通过 `@azure/msal-node-extensions` 坚持不懈.

## 配置 API

一般情况 `enableAzureIdentityAuth` 为完全控制接受回调:

```typescript
enableAzureIdentityAuth(configurator, (builder) => {
  // Option A — mode-specific setter
  builder.setInteractive({ tenantId, clientId, redirectPort: 49741 });

  // Option B — full config object (discriminated union)
  builder.setConfig({
    mode: 'interactive',
    tenantId,
    clientId,
    redirectPort: 49741,
  });

  // Option C — default credential (no args)
  builder.setDefaultCredential();

  // Option D — static token
  builder.setTokenOnly(token);
});
```

## 出口

| 导出 | 说明 |
| --- | --- |
| `enableAzureIdentityAuth` | 配置器调用通用辅助器 |
| `enableAzureIdentityDefaultCredential` | 用于 `default_credential` 模式 |
| `enableAzureIdentityInteractive` | 用于 `interactive` 模式 |
| `enableAzureIdentityTokenOnly` | 用于 `token_only` 模式 |
| `AzureIdentityAuthConfigurator` | 配置类型安全设置器 |
| `AzureIdentityAuthConfig` | 歧视的工会类型 |
| `InteractiveAuthOptions` | 交互式模式选项 |
| `AuthProviderDefaultCredential` | 环境证书提供者类别 |
| `AuthProviderInteractiveBrowser` | 浏览器登录的提供者类 |
| `AuthProviderTokenOnly` | 静态符号的提供者类别 |
| `IAuthProvider` | Auth 提供者接口 |
| `AzureIdentityModule` | 通用参数模块类型 |
| `azureIdentityModule` | 原始模块定义 |

### `/mock` 子路径

| 导出 | 说明 |
| --- | --- |
| `MockAuthProvider` | 可配置 `IAuthProvider` 测试双- `login`编号 :`logout` 工作、标志和过期时间可确定 |
| `MockAuthProviderOptions` | 用于 `MockAuthProvider` |
| `enableAuthMock` | 登记a `MockAuthProvider` 作为 `'auth'` 模块并返回 |
| `createAuthMockModule` | 构建给定的模拟模块描述符 `MockAuthProvider` |

## 常见问题

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

使用 Azure 身份的Fusion框架认证模块\. 支持环境证书\(Default AzureCreditic\),交互式浏览器登录,以及静态令牌模式\.

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

在项目目录运行 npm install @equinor/fusion-framework-module-azure-identity，或使用 pnpm add / yarn add / bun add。

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

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

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

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

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

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

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

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

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

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