快速入門 - 適用於 JavaScript 的 Azure Key Vault 祕密用戶端程式庫

發行項
11/01/2024

開始使用適用於 JavaScript 的 Azure Key Vault 秘密用戶端程式庫。 Azure Key Vault 是一項雲端服務，可為祕密提供安全的存放區。您也可以安全地儲存金鑰、密碼、憑證和其他祕密。您可以透過 Azure 入口網站建立和管理 Azure 金鑰保存庫。在本快速入門中，您會了解如何使用 JavaScript 用戶端程式庫，從 Azure Key Vault 建立、擷取和刪除祕密。

Key Vault 用戶端程式庫資源：

API 參考文件 | 程式庫原始程式碼 | 套件 (npm)

如需有關 Key Vault 及秘密的詳細資訊，請參閱：

必要條件

Azure 訂用帳戶 - 建立免費帳戶。
目前的 Node.js LTS。
Azure CLI

必要條件

Azure 訂用帳戶 - 建立免費帳戶。
目前的 Node.js LTS。
TypeScript 5+
Azure CLI。

本快速入門假設您執行 Azure CLI。

執行 login 命令。
```
az login
```
如果此 CLI 可以開啟您的預設瀏覽器，它會開啟瀏覽器並載入 Azure 登入頁面。

否則，請在 https://aka.ms/devicelogin 中開啟瀏覽器頁面，並輸入顯示在您的終端機中的授權碼。
請在瀏覽器中使用您的帳戶認證登入。

請使用 az group create 命令以建立資源群組：
```
az group create --name myResourceGroup --location eastus
```
您也可以將 "eastus" 變更為更接近您的位置。
使用 az keyvault create 建立金鑰保存庫：
```
az keyvault create --name <your-unique-keyvault-name> --resource-group myResourceGroup
```
以 Azure 中的唯一名稱取代 <your-unique-keyvault-name>。您通常會使用個人或公司名稱，以及其他數字和識別碼。

請使用 New-AzResourceGroup 命令以建立資源群組：
```
New-AzResourceGroup -Name myResourceGroup -Location eastus
```
您也可以將 "eastus" 變更為更接近您的位置。
使用 New-AzKeyVault 建立金鑰保存庫：
```
New-AzKeyVault -Name <your-unique-keyvault-name> -ResourceGroupName myResourceGroup -Location eastus
```
以 Azure 中的唯一名稱取代 <your-unique-keyvault-name>。您通常會使用個人或公司名稱，以及其他數字和識別碼。

授與對金鑰保存庫的存取權

若要透過角色型存取控制 (RBAC) 取得金鑰保存庫的權限，請使用 Azure CLI 命令 az role assignment create 將角色指派給「使用者主體名稱」(UPN)。

az role assignment create --role "Key Vault Secrets Officer" --assignee "<upn>" --scope "/subscriptions/<subscription-id>/resourceGroups/<resource-group-name>/providers/Microsoft.KeyVault/vaults/<your-unique-keyvault-name>"

以實際值取代 <upn>、<subscription-id>、<resource-group-name> 和 <your-unique-keyvault-name>。您 UPN 的格式通常是電子郵件地址 (例如，username@domain.com)。

建立新的 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 套件

使用終端機，針對 Node.js 安裝 Azure Key Vault 祕密用戶端程式庫 @azure/keyvault-secrets。
```
npm install @azure/keyvault-secrets
```
安裝 Azure 身分識別用戶端程式庫 @azure/identity 封裝，以向 Key Vault 進行驗證。
```
npm install @azure/identity
```

授與對金鑰保存庫的存取權

若要透過角色型存取控制 (RBAC) 取得金鑰保存庫的權限，請使用 Azure CLI 命令 az role assignment create 將角色指派給「使用者主體名稱」(UPN)。

az role assignment create --role "Key Vault Secrets Officer" --assignee "<upn>" --scope "/subscriptions/<subscription-id>/resourceGroups/<resource-group-name>/providers/Microsoft.KeyVault/vaults/<your-unique-keyvault-name>"

以實際值取代 <upn>、<subscription-id>、<resource-group-name> 和 <your-unique-keyvault-name>。您 UPN 的格式通常是電子郵件地址 (例如，username@domain.com)。

設定環境變數

此應用程式正使用金鑰保存庫端點作為稱為 KEY_VAULT_URL 的環境變數。

set KEY_VAULT_URL=<your-key-vault-endpoint>

Windows PowerShell

$Env:KEY_VAULT_URL="<your-key-vault-endpoint>"

export KEY_VAULT_URL=<your-key-vault-endpoint>

驗證並建立用戶端

對大部分 Azure 服務的應用程式要求都必須獲得授權。在程式碼中實作對 Azure 服務的無密碼連線時，建議使用 Azure.Identity 用戶端程式庫提供的 DefaultAzureCredential 方法。 DefaultAzureCredential 支援多個驗證方法，並在執行階段判斷應該使用哪個方法。此方法可讓您的應用程式在不同的環境中 (本機或實際執行環境) 使用不同的驗證方法，而不需要實作環境特有的程式碼。

在本快速入門中，DefaultAzureCredential 使用已登入 Azure CLI 之本機開發使用者的認證向金鑰保存庫進行驗證。將應用程式部署至 Azure 時，相同的 DefaultAzureCredential 程式碼可以自動探索並使用指派給 App Service、虛擬機器或其他服務的受控識別。如需詳細資訊，請參閱受控識別概觀。

在此程式碼中，金鑰保存庫的端點會用來建立金鑰保存庫用戶端。端點格式看起來就像 https://<your-key-vault-name>.vault.azure.net，但主權雲端可能會變更。如需對金鑰保存庫進行驗證的詳細資訊，請參閱開發人員指南。

程式碼範例

以下的程式碼範例會示範如何建立用戶端、設定祕密、擷取祕密，以及刪除秘密。

此程式碼會使用下列 Key Vault 祕密類別和方法：

設定應用程式架構

建立新的文字檔，並將下列程式碼貼到 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 Azure Active Directory
  // - 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.net/secrets/secret1637692472606/YOUR-VERSION",
        "vaultUrl": "https: //YOUR-KEYVAULT-ENDPOINT.vault.azure.net",
        "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.js 檔案中。

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.net/secrets/secret1637692472606/YOUR-VERSION",
        "vaultUrl": "https: //YOUR-KEYVAULT-ENDPOINT.vault.azure.net",
        "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 祕密識別碼。如果您使用 Key Vault 的應用程式組態參考，則必須如此。 App Config 會儲存 Key Vault 祕密識別碼。您需要 parseKeyVaultSecretIdentifier 方法來剖析該識別碼，以取得祕密名稱。有了祕密名稱之後，您就可以使用此快速入門中的程式碼來取得目前的祕密值。

下一步

在本快速入門中，您已建立金鑰保存庫、儲存秘密，並擷取該秘密。若要深入了解 Key Vault 以及要如何將其與應用程式整合，請繼續閱讀下列文章。

共用方式為

快速入門 - 適用於 JavaScript 的 Azure Key Vault 祕密用戶端程式庫

必要條件

必要條件

建立資源群組和金鑰保存庫

授與對金鑰保存庫的存取權

建立新的 Node.js 應用程式

安裝 Key Vault 套件

授與對金鑰保存庫的存取權

設定環境變數

驗證並建立用戶端

程式碼範例

設定應用程式架構

執行範例應用程式

執行範例應用程式

與應用程式組態整合

下一步

意見反應

其他資源