快速入门:适用于 JavaScript 的 Azure Key Vault 机密客户端库
适用于 JavaScript 的 Azure Key Vault 机密客户端库入门。 Azure Key Vault 是一项云服务,它为机密提供了安全的存储。 可以安全地存储密钥、密码、证书和其他机密。 可以通过 Azure 门户创建和管理 Azure Key Vault。 本快速入门介绍如何使用 JavaScript 客户端库在 Azure 密钥保管库中创建、检索和删除机密。
Key Vault 客户端库资源:
有关 Key Vault 和机密的详细信息,请参阅:
先决条件
- Azure 订阅 - 创建试用版订阅。
- 当前 Node.js LTS。
- Azure CLI
- 现有的 Key Vault - 可以使用以下方法创建一个:
先决条件
- Azure 订阅。
- 当前 Node.js LTS。
- TypeScript 5+
- Azure CLI。
- 现有的 Key Vault - 可以使用以下方法创建一个:
本快速入门假设你运行 Azure CLI。
登录 Azure
运行
login
命令。az cloud set -n AzureChinaCloud az login # az cloud set -n AzureCloud //means return to Public Azure.
如果 CLI 可以打开默认浏览器,它将这样做并加载 Azure 登录页。
否则,请在 https://aka.ms/deviceloginchina 处打开浏览器页,然后输入终端中显示的授权代码。
在浏览器中使用帐户凭据登录。
创建新的 Node.js 应用程序
创建一个使用密钥保管库的 Node.js 应用程序。
在终端中,创建一个名为
key-vault-node-app
的文件夹并更改为该文件夹:mkdir key-vault-node-app && cd key-vault-node-app
初始化 Node.js 项目:
npm init -y
安装 Key Vault 包
使用终端安装 Azure Key Vault 机密客户端库(适用于 Node.js 的 @azure/keyvault-secrets)。
npm install @azure/keyvault-secrets
安装 Azure 标识库(@azure/identity 包)以对密钥保管库进行身份验证。
npm install @azure/identity
授予对 Key Vault 的访问权限
若要通过基于角色的访问控制 (RBAC) 授予应用程序对密钥保管库的权限,请使用 Azure CLI 命令 az role assignment create 分配角色。
az role assignment create --role "Key Vault Secrets User" --assignee "<app-id>" --scope "/subscriptions/<subscription-id>/resourceGroups/<resource-group-name>/providers/Microsoft.KeyVault/vaults/<your-unique-keyvault-name>"
将 <app-id>
、<subscription-id>
、<resource-group-name>
和 <your-unique-keyvault-name>
替换为实际值。 <app-id>
是在 Azure Entra 中注册的应用程序的应用程序(客户端)ID。
设置环境变量
此应用程序使用密钥保管库终结点作为名为 KEY_VAULT_URL
的环境变量。
set KEY_VAULT_URL=<your-key-vault-endpoint>
进行身份验证并创建客户端
对大多数 Azure 服务的应用程序请求必须获得授权。 要在代码中实现与 Azure 服务的无密码连接,推荐使用由 Azure 标识客户端库提供的 DefaultAzureCredential 方法。 DefaultAzureCredential
支持多种身份验证方法,并确定应在运行时使用哪种方法。 通过这种方法,你的应用可在不同环境(本地与生产)中使用不同的身份验证方法,而无需实现特定于环境的代码。
在本快速入门中,DefaultAzureCredential
使用登录到 Azure CLI 的本地开发用户的凭据对密钥保管库进行身份验证。 将应用程序部署到 Azure 时,相同的 DefaultAzureCredential
代码可以自动发现并使用分配给应用服务、虚拟机或其他服务的托管标识。 有关详细信息,请参阅托管标识概述。
在此代码中,密钥保管库的终结点用于创建密钥保管库客户端。 终结点格式类似于 https://<your-key-vault-name>.vault.azure.cn
,但可能会根据不同的主权云而变化。 有关向密钥保管库进行身份验证的详细信息,请参阅开发人员指南。
代码示例
以下代码示例演示如何创建客户端以及设置、检索和删除机密。
此代码使用以下密钥保管库机密类和方法:
设置应用框架
创建新文本文件并将以下代码粘贴到 index.js 文件中。
const { SecretClient } = require("@azure/keyvault-secrets"); const { DefaultAzureCredential } = require("@azure/identity"); async function main() { // If you're using MSI, DefaultAzureCredential should "just work". // Otherwise, DefaultAzureCredential expects the following three environment variables: // - AZURE_TENANT_ID: The tenant ID in Microsoft Entra ID // - AZURE_CLIENT_ID: The application (client) ID registered in the AAD tenant // - AZURE_CLIENT_SECRET: The client secret for the registered application const credential = new DefaultAzureCredential(); const keyVaultUrl = process.env["KEY_VAULT_URL"]; if(!keyVaultUrl) throw new Error("KEY_VAULT_URL is empty"); const client = new SecretClient(keyVaultUrl, credential); // Create a secret // The secret can be a string of any kind. For example, // a multiline text block such as an RSA private key with newline characters, // or a stringified JSON object, like `JSON.stringify({ mySecret: 'MySecretValue'})`. const uniqueString = new Date().getTime(); const secretName = `secret${uniqueString}`; const result = await client.setSecret(secretName, "MySecretValue"); console.log("result: ", result); // Read the secret we created const secret = await client.getSecret(secretName); console.log("secret: ", secret); // Update the secret with different attributes const updatedSecret = await client.updateSecretProperties(secretName, result.properties.version, { enabled: false }); console.log("updated secret: ", updatedSecret); // Delete the secret immediately without ability to restore or purge. await client.beginDeleteSecret(secretName); } main().catch((error) => { console.error("An error occurred:", error); process.exit(1); });
运行示例应用程序
运行应用:
node index.js
create 和 get 方法为机密返回完整的 JSON 对象:
{ "value": "MySecretValue", "name": "secret1637692472606", "properties": { "createdOn": "2021-11-23T18:34:33.000Z", "updatedOn": "2021-11-23T18:34:33.000Z", "enabled": true, "recoverableDays": 90, "recoveryLevel": "Recoverable+Purgeable", "id": "https: //YOUR-KEYVAULT-ENDPOINT.vault.azure.cn/secrets/secret1637692472606/YOUR-VERSION", "vaultUrl": "https: //YOUR-KEYVAULT-ENDPOINT.vault.azure.cn", "version": "YOUR-VERSION", "name": "secret1637692472606" } }
update 方法返回 properties 名称/值对:
"createdOn": "2021-11-23T18:34:33.000Z", "updatedOn": "2021-11-23T18:34:33.000Z", "enabled": true, "recoverableDays": 90, "recoveryLevel": "Recoverable+Purgeable", "id": "https: //YOUR-KEYVAULT-ENDPOINT/secrets/secret1637692472606/YOUR-VERSION", "vaultUrl": "https: //YOUR-KEYVAULT-ENDPOINT", "version": "YOUR-VERSION", "name": "secret1637692472606"
创建新的文本文件,并将以下代码粘贴到 index.ts 文件中。
import {
SecretClient,
KeyVaultSecret,
SecretProperties,
} from "@azure/keyvault-secrets";
import { DefaultAzureCredential } from "@azure/identity";
import "dotenv/config";
// Passwordless credential
const credential = new DefaultAzureCredential();
// Get Key Vault name from environment variables
// such as `https://${keyVaultName}.vault.azure.net`
const keyVaultUrl = process.env.KEY_VAULT_URL;
if (!keyVaultUrl) throw new Error("KEY_VAULT_URL is empty");
function printSecret(secret: KeyVaultSecret): void {
const { name, value, properties } = secret;
const { enabled, expiresOn, createdOn } = properties;
console.log("Secret: ", { name, value, enabled, expiresOn, createdOn });
}
function printSecretProperties(secret: SecretProperties): void {
const { name, enabled, expiresOn, createdOn } = secret;
console.log("Secret: ", { name, enabled, expiresOn, createdOn });
}
async function main(): Promise<void> {
// Create a new SecretClient
const client = new SecretClient(keyVaultUrl, credential);
// Create a unique secret name
const uniqueString = new Date().getTime().toString();
const secretName = `secret${uniqueString}`;
// Create a secret
const createSecretResult = await client.setSecret(
secretName,
"MySecretValue"
);
printSecret(createSecretResult);
// Get the secret by name
const getSecretResult = await client.getSecret(secretName);
printSecret(getSecretResult);
// Update properties
const updatedSecret = await client.updateSecretProperties(
secretName,
getSecretResult.properties.version,
{
enabled: false,
}
);
printSecretProperties(updatedSecret);
// Delete secret (without immediate purge)
const deletePoller = await client.beginDeleteSecret(secretName);
await deletePoller.pollUntilDone();
}
main().catch((error) => {
console.error("An error occurred:", error);
process.exit(1);
});
运行示例应用程序
构建 TypeScript 应用:
tsc
运行应用:
node index.js
create 和 get 方法为机密返回完整的 JSON 对象:
{ "value": "MySecretValue", "name": "secret1637692472606", "properties": { "createdOn": "2021-11-23T18:34:33.000Z", "updatedOn": "2021-11-23T18:34:33.000Z", "enabled": true, "recoverableDays": 90, "recoveryLevel": "Recoverable+Purgeable", "id": "https: //YOUR-KEYVAULT-ENDPOINT.vault.azure.cn/secrets/secret1637692472606/YOUR-VERSION", "vaultUrl": "https: //YOUR-KEYVAULT-ENDPOINT.vault.azure.cn", "version": "YOUR-VERSION", "name": "secret1637692472606" } }
update 方法返回 properties 名称/值对:
"createdOn": "2021-11-23T18:34:33.000Z", "updatedOn": "2021-11-23T18:34:33.000Z", "enabled": true, "recoverableDays": 90, "recoveryLevel": "Recoverable+Purgeable", "id": "https: //YOUR-KEYVAULT-ENDPOINT/secrets/secret1637692472606/YOUR-VERSION", "vaultUrl": "https: //YOUR-KEYVAULT-ENDPOINT", "version": "YOUR-VERSION", "name": "secret1637692472606"
与应用配置集成
Azure SDK 提供了一个帮助程序方法 parseKeyVaultSecretIdentifier,用于解析给定的 Key Vault 机密 ID。 如果使用对 Key Vault 的应用配置引用,这是必要的。 应用配置存储 Key Vault 机密 ID。 需要 parseKeyVaultSecretIdentifier 方法来解析该 ID 以获取机密名称。 获得机密名称后,可以使用本快速入门中的代码获取当前的机密值。
后续步骤
在本快速入门中,你创建了一个密钥保管库、存储了一个机密,然后检索了该机密。 若要详细了解 Key Vault 以及如何将其与应用程序集成,请继续阅读以下文章。