Azure Key Vault 机密 TypeScript

azure-keyvault-secrets-ts
分类编程
作者Agentic Awesome Skills 社区
许可MIT
评分4.70/5
使用11.5K

Azure Key Vault Secrets SDK for TypeScript

使用 Azure Key Vault 管理机密。

安装

bash
# Secrets SDK
npm install @azure/keyvault-secrets @azure/identity

环境变量

bash
KEY_VAULT_URL=https://<vault-name>.vault.azure.net

或者

AZURE_KEYVAULT_NAME=<vault-name>

身份验证

typescript
import { DefaultAzureCredential } from "@azure/identity";
import { SecretClient } from "@azure/keyvault-secrets";

const credential = new DefaultAzureCredential();
const vaultUrl = https://${process.env.AZURE_KEYVAULT_NAME}.vault.azure.net;


const keyClient = new KeyClient(vaultUrl, credential);
const secretClient = new SecretClient(vaultUrl, credential);

机密操作 (Secrets Operations)

创建/设置机密

typescript
const secret = await secretClient.setSecret("MySecret", "secret-value");

// 包含属性
const secretWithAttrs = await secretClient.setSecret("MySecret", "value", {
  enabled: true,
  expiresOn: new Date("2025-12-31"),
  contentType: "application/json",
  tags: { environment: "production" }
});

获取机密

typescript
// 获取最新版本
const secret = await secretClient.getSecret("MySecret");
console.log(secret.value);

// 获取特定版本
const specificSecret = await secretClient.getSecret("MySecret", {
  version: secret.properties.version
});

列出机密

typescript
for await (const secretProperties of secretClient.listPropertiesOfSecrets()) {
  console.log(secretProperties.name);
}

// 列出版本
for await (const version of secretClient.listPropertiesOfSecretVersions("MySecret")) {
  console.log(version.version);
}

删除机密

typescript
// 软删除
const deletePoller = await secretClient.beginDeleteSecret("MySecret");
await deletePoller.pollUntilDone();

// 清除（永久删除）
await secretClient.purgeDeletedSecret("MySecret");


// 恢复
const recoverPoller = await secretClient.beginRecoverDeletedSecret("MySecret");
await recoverPoller.pollUntilDone();

密钥操作 (Keys Operations)

创建密钥

typescript
// 通用密钥
const key = await keyClient.createKey("MyKey", "RSA");

// 指定大小的 RSA 密钥
const rsaKey = await keyClient.createRsaKey("MyRsaKey", { keySize: 2048 });


// 椭圆曲线 (EC) 密钥
const ecKey = await keyClient.createEcKey("MyEcKey", { curve: "P-256" });


// 包含属性
const keyWithAttrs = await keyClient.createKey("MyKey", "RSA", {
  enabled: true,
  expiresOn: new Date("2025-12-31"),
  tags: { purpose: "encryption" },
  keyOps: ["encrypt", "decrypt", "sign", "verify"]
});

获取密钥

typescript
const key = await keyClient.getKey("MyKey");
console.log(key.name, key.keyType);

列出密钥

typescript
for await (const keyProperties of keyClient.listPropertiesOfKeys()) {
  console.log(keyProperties.name);
}

轮换密钥

typescript
// 手动轮换
const rotatedKey = await keyClient.rotateKey("MyKey");

// 设置轮换策略
await keyClient.updateKeyRotationPolicy("MyKey", {
  lifetimeActions: [{ action: "Rotate", timeBeforeExpiry: "P30D" }],
  expiresIn: "P90D"
});

删除密钥

typescript
const deletePoller = await keyClient.beginDeleteKey("MyKey");
await deletePoller.pollUntilDone();

// 清除

await keyClient.purgeDeletedKey("MyKey");
code
## 加密操作


创建 CryptographyClient
typescript import { CryptographyClient } from "@azure/keyvault-keys";

// 通过 key 对象创建
const cryptoClient = new CryptographyClient(key, credential);

// 通过 key ID 创建
const cryptoClient = new CryptographyClient(key.id!, credential);

code
### 加密/解密
typescript
// 加密
const encryptResult = await cryptoClient.encrypt({
algorithm: "RSA-OAEP",
plaintext: Buffer.from("My secret message")
});

// 解密
const decryptResult = await cryptoClient.decrypt({
algorithm: "RSA-OAEP",
ciphertext: encryptResult.result
});

console.log(decryptResult.result.toString());

code
### 签名/验证
typescript
import { createHash } from "node:crypto";

// 创建摘要
const hash = createHash("sha256").update("My message").digest();

// 签名
const signResult = await cryptoClient.sign("RS256", hash);

// 验证
const verifyResult = await cryptoClient.verify("RS256", hash, signResult.result);
console.log("Valid:", verifyResult.result);

code
### 密钥包裹/解包裹 (Wrap/Unwrap)
typescript
// 包裹密钥（加密以进行存储）
const wrapResult = await cryptoClient.wrapKey("RSA-OAEP", Buffer.from("key-material"));

// 解包裹
const unwrapResult = await cryptoClient.unwrapKey("RSA-OAEP", wrapResult.result);

code
## 备份与还原
typescript
// 备份
const keyBackup = await keyClient.backupKey("MyKey");
const secretBackup = await secretClient.backupSecret("MySecret");

// 还原（可还原至不同的存储库）
const restoredKey = await keyClient.restoreKeyBackup(keyBackup!);
const restoredSecret = await secretClient.restoreSecretBackup(secretBackup!);

code
## 密钥类型
typescript
import {
KeyClient,
KeyVaultKey,
KeyProperties,
DeletedKey,
CryptographyClient,
KnownEncryptionAlgorithms,
KnownSignatureAlgorithms
} from "@azure/keyvault-keys";

import {
SecretClient,
KeyVaultSecret,
SecretProperties,
DeletedSecret
} from "@azure/keyvault-secrets";

code
## 错误处理
typescript
try {
const secret = await secretClient.getSecret("NonExistent");
} catch (error: any) {
if (error.code === "SecretNotFound") {
console.log("Secret does not exist");
} else {
throw error;
}
}
```

最佳实践

1. 使用 DefaultAzureCredential - 兼容开发和生产环境
2. 启用软删除 (soft-delete) - 生产环境存储库的必要配置
3. 设置过期日期 - 密钥和机密均应设置
4. 使用密钥轮换策略 - 实现密钥自动轮换
5. 限制密钥操作 - 仅授予必要的权限（如加密、签名等）
6. 不支持浏览器 - 这些 SDK 仅适用于 Node.js

适用场景

本技能适用于执行概览中所描述的工作流或操作。

局限性

  • 仅在任务明确符合上述范围时使用此技能。
  • 不要将输出结果视为环境特定验证、测试或专家评审的替代方案。
  • 如果缺少必要的输入、权限、安全边界或成功标准，请停止并请求澄清。