# @eqxjs/azure-manage-identity 中文文档

规范地址：https://npmcn.com/package/%40eqxjs/azure-manage-identity/

版本：1\.5\.0
npm 元数据更新时间：2026-07-08T04:10:25.506Z
中文译文更新时间：2026-11-13T20:19:07.735Z
软件包许可：ISC

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

原始 npm 页面：https://www.npmjs.com/package/%40eqxjs/azure-manage-identity
原文对照：https://npmcn.com/package/%40eqxjs/azure-manage-identity/?lang=original

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

- 包体积（解压后）：46.2 kB，32 个文件
- 模块格式：CommonJS
- TypeScript 类型：包内自带
- Node.js 要求：\>=22
- 运行依赖：6 个
- 首次发布：2023-05-26T01:41:10.769Z
- 最新版本发布：2026-07-08T04:10:25.291Z
- 近 30 天下载量：18416（2026-10-14 至 2026-11-12，npm 官方下载统计）
- 已发布版本数：19（近 12 个月 6 个）

## 中文简介

获取 Azure 密钥的密钥

## 安装

```sh
npm install @eqxjs/azure-manage-identity
```

也可以使用：`pnpm add @eqxjs/azure-manage-identity`、`yarn add @eqxjs/azure-manage-identity`、`bun add @eqxjs/azure-manage-identity`

## README

# @eqxjs/azure-manage-dentity (英语)

一个TypeScript库,用于使用Azure管理的身份管理 Azure Key Vault 机密和加密操作.

节点 : `>=22`

## 说明

这个库提供了一个简单的接口,与Azure Key Vault进行互动,用于秘密管理,JWT令牌验证/签名,以及数据加密/解密操作. 它使用Azure的"默认Azure证书"来进行有被管理身份的无缝认证.

## 安装

```bash
npm install @eqxjs/azure-manage-identity
```

## 特征

-   **秘密管理**: 获取、设置、列出并删除 Azure 密钥
-   **JWT业务**: 使用 Azure 密钥断层键验证并签名 JWT 令牌
-   **数据加密**: 使用 Azure 密钥对数据进行加密和解密
-   **管理身份**: 使用 Azure 管理的身份自动认证

## 职能

### 秘密管理

#### `getSecret(keyvaultURL: string, secretName: string, secretOpt?: GetSecretOptions)`

从Azure Key Vault处获取一个秘密.

**参数:**

-   `keyvaultURL` - Azure 键断层的URL(例如, `https://your-keyvault.vault.azure.net/`(中文(简体) )
-   `secretName` - 取回的秘密名称
-   `secretOpt` - 获取秘密的可选设置

**回返情况:** `Promise<KeyVaultSecret>`

**示例**

```typescript
import { getSecret } from '@eqxjs/azure-manage-identity';

const secret = await getSecret(
  'https://your-keyvault.vault.azure.net/',
  'my-secret',
);
console.log(secret.value);
```

* * *

#### `setSecret(keyvaultURL: string, secretName: string, secretValue: string, secretOpt?: SetSecretOptions)`

在 Azure 密钥断层中创建或更新密钥 .

**参数:**

-   `keyvaultURL` - Azure 键断层的 URL
-   `secretName` - 要设置的秘密名称
-   `secretValue` - 隐藏在秘密中的价值
-   `secretOpt` - 设置秘密的可选设置

**回返情况:** `Promise<KeyVaultSecret>`

**示例**

```typescript
import { setSecret } from '@eqxjs/azure-manage-identity';

const secret = await setSecret(
  'https://your-keyvault.vault.azure.net/',
  'my-secret',
  'my-secret-value',
);
```

* * *

#### `listSecretVersion(keyvaultURL: string, secretName: string, secretOpt?: ListPropertiesOfSecretVersionsOptions)`

列出特定秘密的所有版本.

**参数:**

-   `keyvaultURL` - Azure 键断层的 URL
-   `secretName` - 秘密的名称
-   `secretOpt` - 列出秘密版本的可选设置

**回返情况:** `PagedAsyncIterableIterator<SecretProperties>`

**示例**

```typescript
import { listSecretVersion } from '@eqxjs/azure-manage-identity';

const versions = await listSecretVersion(
  'https://your-keyvault.vault.azure.net/',
  'my-secret',
);

for await (const version of versions) {
  console.log(version.version);
}
```

* * *

#### `removeSecret(keyvaultURL: string, secretName: string, secretOpt?: BeginDeleteSecretOptions, clientOptions?: SecretClientOptions)`

从 Azure 密钥断层中删除密钥并等待删除完成 .

**参数:**

-   `keyvaultURL` - Azure 键断层的 URL
-   `secretName` - 要删除的秘密名称
-   `secretOpt` - 删除操作的可选设置
-   `clientOptions` - 保密客户端的可选配置

**回返情况:** `Promise<DeletedSecret>`

**示例**

```typescript
import { removeSecret } from '@eqxjs/azure-manage-identity';

const deleted = await removeSecret(
  'https://your-keyvault.vault.azure.net/',
  'my-secret',
);
console.log(deleted.deletedOn);
```

* * *

### JWT 调试操作

#### `verifyJWTToken(keyURL: string, keyName: string, algorithm: string, jwtToken: string)`

使用 Azure 密钥密钥验证 JWT 令牌 .

**参数:**

-   `keyURL` - Azure 键断层的 URL
-   `keyName` - 用于核查的密钥名称
-   `algorithm` - 签名算法(例如“RS256”)
-   `jwtToken` - JWT证明书

**回返情况:** `Promise<VerifyResult>`

**示例**

```typescript
import { verifyJWTToken } from '@eqxjs/azure-manage-identity';

const result = await verifyJWTToken(
  'https://your-keyvault.vault.azure.net/',
  'my-key',
  'RS256',
  'eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...',
);
console.log(result.result); // true or false
```

* * *

#### `verifyJWTTokenBySecret(keyURL: string, secretName: string, jwtToken: string)`

使用存储在 Azure Key Vault 的公钥验证 JWT 令牌。 支持JWKS(JSON Web Key Set)格式.

**参数:**

-   `keyURL` - Azure 键断层的 URL
-   `secretName` - 包含公用钥匙/JWKS的秘密名称
-   `jwtToken` - JWT证明书

**回返情况:** `Promise<VerifyResult>`

**示例**

```typescript
import { verifyJWTTokenBySecret } from '@eqxjs/azure-manage-identity';

const result = await verifyJWTTokenBySecret(
  'https://your-keyvault.vault.azure.net/',
  'jwks-secret',
  'eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...',
);
```

* * *

#### `signJWTToken(keyURL: string, keyName: string, algorithm: string, payload: string)`

使用 Azure 密钥密钥签署 JWT 有效载荷.

**参数:**

-   `keyURL` - Azure 键断层的 URL
-   `keyName` - 用于签名的密钥名称
-   `algorithm` - 签名算法(例如“RS256”)
-   `payload` - 签字的有效载荷

**回返情况:** `Promise<string>` - Base64URL编码签名

**示例**

```typescript
import { signJWTToken } from '@eqxjs/azure-manage-identity';

const signature = await signJWTToken(
  'https://your-keyvault.vault.azure.net/',
  'my-key',
  'RS256',
  'header.payload',
);
```

* * *

### 数据加密/解密

#### `encryptData(keyURL: string, keyName: string, payload: string, ivSecretName: string)`

使用AES-256-CBC加密数据,并使用Azure键断层键加密数据.

**参数:**

-   `keyURL` - Azure 键断层的 URL
-   `keyName` - 用于加密的密钥名称
-   `payload` - 要加密的数据
-   `ivSecretName` - 包含初始化矢量的秘密名称(IV)

**回返情况:** `Promise<string>` - Base64URL编码加密数据

**示例**

```typescript
import { encryptData } from '@eqxjs/azure-manage-identity';

const encrypted = await encryptData(
  'https://your-keyvault.vault.azure.net/',
  'encryption-key',
  'sensitive data',
  'iv-secret',
);
```

* * *

#### `decryptData(keyURL: string, keyName: string, payloadBase64: string, ivSecretName: string)`

使用AES-256-CBC加密加密的数据解密.

**参数:**

-   `keyURL` - Azure 键断层的 URL
-   `keyName` - 用于解密的密钥名称
-   `payloadBase64` - Base64URL加密数据
-   `ivSecretName` - 包含初始化矢量的秘密名称(IV)

**回返情况:** `Promise<string>` - 已解密的纯文本数据

**示例**

```typescript
import { decryptData } from '@eqxjs/azure-manage-identity';

const decrypted = await decryptData(
  'https://your-keyvault.vault.azure.net/',
  'encryption-key',
  'base64url-encoded-ciphertext',
  'iv-secret',
);
```

* * *

## 认证

这个图书馆使用Azure的 `DefaultAzureCredential` 用于认证,自动处理:

-   管理身份(用于Azure托管的应用程序)
-   Azure CLI 证书
-   环境变量
-   视觉工作室代码证书
-   其他Azure认证方法

确保您的应用程序有访问 Azure 密钥断层资源的适当权限 .

## 需要的 Azure 密钥断层权限

您管理的身份或服务主机需要以下权限:

### 对于秘密行动 :

-   `Get` - 读取秘密
-   `Set` - 创造/更新秘密
-   `List` - 列出秘密版本
-   `Delete` - 清除秘密

### 对于密钥操作 :

-   `Get` - 找回钥匙
-   `Sign` - 签署数据/JWT标志
-   `Verify` - 核查签名
-   `Encrypt` - 加密数据
-   `Decrypt` - 解密数据

## 依赖关系

这个库取决于:

-   `@azure/identity` - Azure认证
-   `@azure/keyvault-keys` - 关键断层关键操作
-   `@azure/keyvault-secrets` - 关键断层秘密行动
-   `jsonwebtoken` - JWT业务
-   `base64url` - 基础64URL编码/解码

## 许可证

公务员制度委员会

## 作者

精华

## 常见问题

### @eqxjs/azure-manage-identity 是什么？

获取 Azure 密钥的密钥

### 如何安装 @eqxjs/azure-manage-identity？

在项目目录运行 npm install @eqxjs/azure-manage-identity，或使用 pnpm add / yarn add / bun add。

### @eqxjs/azure-manage-identity 支持 TypeScript 吗？

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

### @eqxjs/azure-manage-identity 支持 ESM 还是 CommonJS？

以 CommonJS 形式发布，可以直接 require\(\)；在 ES Module 项目中也可以用 import 引入（Node\.js 会把 module\.exports 作为默认导出）。

### @eqxjs/azure-manage-identity 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=22。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @eqxjs/azure-manage-identity 可以商用吗？

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

### @eqxjs/azure-manage-identity 的下载量有多少？

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

### @eqxjs/azure-manage-identity 还在维护吗？

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