共用方式為

適用於 JavaScript 的 Azure 金鑰保存庫 秘密客戶端連結庫 - 4.8.0 版

  • 發行項

Azure 金鑰保存庫 是一項服務，可讓您使用安全密鑰來加密驗證金鑰、記憶體帳戶密鑰、數據加密金鑰、.pfx 檔案和密碼。 如果您想要深入瞭解 Azure 金鑰保存庫，您可以檢閱：什麼是 Azure 金鑰保存庫？

Azure 金鑰保存庫 秘密管理可讓您安全地儲存及嚴格控制令牌、密碼、憑證、API 密鑰和其他秘密的存取。

在 Node.js 應用程式中使用 Azure 金鑰保存庫 秘密的用戶端連結庫來：

  • 取得、設定和刪除秘密。
  • 更新秘密，且其為屬性。
  • 備份和還原秘密。
  • 取得、清除或復原已刪除的秘密。
  • 取得秘密的所有版本。
  • 取得所有秘密。
  • 取得所有已刪除的秘密。

注意：由於 Azure 金鑰保存庫 服務限制，此套件無法在瀏覽器中使用，請參閱本檔以取得指引。

重要連結：

開始使用

目前支援的環境

必要條件

安裝套件

使用 npm 安裝 Azure 金鑰保存庫 秘密客戶端連結庫：

npm install @azure/keyvault-secrets

安裝身分識別連結庫

金鑰保存庫 用戶端會使用 Azure 身分識別連結庫進行驗證。 使用 npm 安裝

npm install @azure/identity

設定 TypeScript

TypeScript 用戶必須安裝 Node 類型定義：

npm install @types/node

您也需要在tsconfig.json中開啟 compilerOptions.allowSyntheticDefaultImports 。 請注意，如果您已啟用 compilerOptions.esModuleInterop， allowSyntheticDefaultImports 預設會啟用 。 如需詳細資訊 ，請參閱 TypeScript 的編譯程式選項手冊 。

重要概念

  • 秘密用戶端是與來自 JavaScript 應用程式之 Azure 金鑰保存庫 API 中秘密相關的 API 方法互動的主要介面。 初始化之後，它會提供一組基本方法，可用來建立、讀取、更新和刪除秘密。
  • 秘密版本是 金鑰保存庫 中的秘密版本。 每次使用者將值指派給唯一的秘密名稱時，就會建立新 版 的秘密。 除非提供特定版本給查詢，否則依名稱擷取秘密一律會傳回指派的最新值。
  • 虛刪除 可讓 Key Vault 支援刪除和清除為兩個不同的步驟，因此刪除的秘密不會立即遺失。 只有當 金鑰保存庫 已啟用虛刪除時，才會發生這種情況。
  • 秘密備份可以從任何建立的秘密產生。 這些備份是二進位數據，而且只能用來重新產生先前刪除的秘密。

使用 Azure Active Directory 進行驗證

金鑰保存庫 服務依賴 Azure Active Directory 來驗證其 API 的要求。 套件 @azure/identity 提供各種認證類型，可供您的應用程式用來執行此動作。 的 自述檔 @azure/identity 提供更多詳細數據和範例供您開始使用。

若要與 Azure 金鑰保存庫 服務互動，您必須建立 類別的SecretClient實例、保存庫 URL 和認證物件。 本檔中所示的範例會使用名為 的 DefaultAzureCredential認證物件，適用於大部分案例，包括本機開發和生產環境。 此外，我們建議在生產環境中使用 受控識別 進行驗證。

您可以在 Azure 身分識別檔中找到不同驗證方式及其對應認證類型的詳細資訊。

以下是快速範例。 首先，匯入 DefaultAzureCredential 和 SecretClient：

const { DefaultAzureCredential } = require("@azure/identity");
const { SecretClient } = require("@azure/keyvault-secrets");

匯入這些之後，我們可以接著連線到 金鑰保存庫 服務：

const { DefaultAzureCredential } = require("@azure/identity");
const { SecretClient } = require("@azure/keyvault-secrets");

const credential = new DefaultAzureCredential();

// Build the URL to reach your key vault
const vaultName = "<YOUR KEYVAULT NAME>";
const url = `https://${vaultName}.vault.azure.net`;

// Lastly, create our secrets client and connect to the service
const client = new SecretClient(url, credential);

指定 Azure 金鑰保存庫 服務 API 版本

根據預設，此套件會使用最新的 Azure 金鑰保存庫 服務版本，也就是 7.1。 唯一支援的其他版本是 7.0。 您可以藉由在用戶端建構函式中設定 選項 serviceVersion 來變更所使用的服務版本，如下所示：

const { DefaultAzureCredential } = require("@azure/identity");
const { SecretClient } = require("@azure/keyvault-secrets");

const credential = new DefaultAzureCredential();

const vaultName = "<YOUR KEYVAULT NAME>";
const url = `https://${vaultName}.vault.azure.net`;

// Change the Azure Key Vault service API version being used via the `serviceVersion` option
const client = new SecretClient(url, credential, {
  serviceVersion: "7.0",
});

範例

下列各節提供代碼段，這些代碼段涵蓋使用 Azure 金鑰保存庫 秘密的一些常見工作。 這裡涵蓋的案例包括：

建立和設定秘密

setSecret 將提供的 值指派給指定的秘密名稱。 如果具有相同名稱的秘密已經存在，則會建立新版本的秘密。

const { DefaultAzureCredential } = require("@azure/identity");
const { SecretClient } = require("@azure/keyvault-secrets");

const credential = new DefaultAzureCredential();

const vaultName = "<YOUR KEYVAULT NAME>";
const url = `https://${vaultName}.vault.azure.net`;

const client = new SecretClient(url, credential);

const secretName = "MySecretName";

async function main() {
  const result = await client.setSecret(secretName, "MySecretValue");
  console.log("result: ", result);
}

main();

取得秘密

從保存庫讀取秘密的最簡單方式是依名稱取得秘密。 這會擷取最新版的秘密。 如果您將其指定為選擇性參數的一部分，您可以選擇性地取得不同的密鑰版本。

const { DefaultAzureCredential } = require("@azure/identity");
const { SecretClient } = require("@azure/keyvault-secrets");

const credential = new DefaultAzureCredential();

const vaultName = "<YOUR KEYVAULT NAME>";
const url = `https://${vaultName}.vault.azure.net`;

const client = new SecretClient(url, credential);

const secretName = "MySecretName";

async function main() {
  const latestSecret = await client.getSecret(secretName);
  console.log(`Latest version of the secret ${secretName}: `, latestSecret);
  const specificSecret = await client.getSecret(secretName, { version: latestSecret.properties.version! });
  console.log(`The secret ${secretName} at the version ${latestSecret.properties.version!}: `, specificSecret);
}

main();

使用屬性建立和更新秘密

秘密可以有比其名稱及其值更多的資訊。 它們也可以包含下列屬性：

  • tags：任何可用來搜尋和篩選秘密的索引鍵值集。
  • contentType：可用來協助秘密接收者瞭解如何使用秘密值的任何字串。
  • enabled：布爾值，決定是否可以讀取秘密值。
  • notBefore：指定日期，之後可以擷取秘密值。
  • expiresOn：指定日期，之後無法擷取秘密值。

具有這些屬性的物件可以傳送為 的第三個參數 setSecret，緊接在秘密的名稱和值之後，如下所示：

const { DefaultAzureCredential } = require("@azure/identity");
const { SecretClient } = require("@azure/keyvault-secrets");

const credential = new DefaultAzureCredential();

const vaultName = "<YOUR KEYVAULT NAME>";
const url = `https://${vaultName}.vault.azure.net`;

const client = new SecretClient(url, credential);

const secretName = "MySecretName";

async function main() {
  const result = await client.setSecret(secretName, "MySecretValue", {
    enabled: false,
  });
}

main();

這會建立新版的相同秘密，其中包含最新的提供屬性。

屬性也可以使用 更新為現有的秘密版本 updateSecretProperties，如下所示：

const { DefaultAzureCredential } = require("@azure/identity");
const { SecretClient } = require("@azure/keyvault-secrets");

const credential = new DefaultAzureCredential();

const vaultName = "<YOUR KEYVAULT NAME>";
const url = `https://${vaultName}.vault.azure.net`;

const client = new SecretClient(url, credential);

const secretName = "MySecretName";

async function main() {
  const result = await client.getSecret(secretName);
  await client.updateSecretProperties(secretName, result.properties.version, { enabled: false });
}

main();

刪除秘密

方法 beginDeleteSecret 會開始刪除秘密。 只要有必要的資源可供使用，此程式就會在背景中發生。

const { DefaultAzureCredential } = require("@azure/identity");
const { SecretClient } = require("@azure/keyvault-secrets");

const credential = new DefaultAzureCredential();

const vaultName = "<YOUR KEYVAULT NAME>";
const url = `https://${vaultName}.vault.azure.net`;

const client = new SecretClient(url, credential);

const secretName = "MySecretName";

async function main() {
  await client.beginDeleteSecret(secretName);
}

main();

如果啟用 金鑰保存庫 的虛刪除，此作業只會將秘密標示為已刪除的秘密。 無法更新已刪除的秘密。 它們只能讀取、復原或清除。

const { DefaultAzureCredential } = require("@azure/identity");
const { SecretClient } = require("@azure/keyvault-secrets");

const credential = new DefaultAzureCredential();

const vaultName = "<YOUR KEYVAULT NAME>";
const url = `https://${vaultName}.vault.azure.net`;

const client = new SecretClient(url, credential);

const secretName = "MySecretName";

async function main() {
  const poller = await client.beginDeleteSecret(secretName);

  // You can use the deleted secret immediately:
  const deletedSecret = poller.getResult();

  // The secret is being deleted. Only wait for it if you want to restore it or purge it.
  await poller.pollUntilDone();

  // You can also get the deleted secret this way:
  await client.getDeletedSecret(secretName);

  // Deleted secrets can also be recovered or purged.

  // recoverDeletedSecret returns a poller, just like beginDeleteSecret.
  const recoverPoller = await client.beginRecoverDeletedSecret(secretName);
  await recoverPoller.pollUntilDone();

  // And then, to purge the deleted secret:
  await client.purgeDeletedSecret(secretName);
}

main();

由於秘密需要一些時間才能完全刪除，因此會傳回 Poller 物件， beginDeleteSecret 以根據我們的指導方針來追蹤基礎長時間執行作業： https://azure.github.io/azure-sdk/typescript_design.html#ts-lro

接收的輪詢器可讓您透過呼叫 poller.getResult()來取得已刪除的秘密。 您也可以等到刪除完成，方法是執行個別服務呼叫，直到刪除秘密，或等到程式完成為止：

const { DefaultAzureCredential } = require("@azure/identity");
const { SecretClient } = require("@azure/keyvault-secrets");

const credential = new DefaultAzureCredential();

const vaultName = "<YOUR KEYVAULT NAME>";
const url = `https://${vaultName}.vault.azure.net`;

const client = new SecretClient(url, credential);

const secretName = "MySecretName";

async function main() {
  const poller = await client.beginDeleteSecret(secretName);

  // You can use the deleted secret immediately:
  let deletedSecret = poller.getResult();

  // Or you can wait until the secret finishes being deleted:
  deletedSecret = await poller.pollUntilDone();
  console.log(deletedSecret);
}

main();

另一種等待秘密完全刪除的方式是執行個別呼叫，如下所示：

const { DefaultAzureCredential } = require("@azure/identity");
const { SecretClient } = require("@azure/keyvault-secrets");
const { delay } = require("@azure/core-util");

const credential = new DefaultAzureCredential();

const vaultName = "<YOUR KEYVAULT NAME>";
const url = `https://${vaultName}.vault.azure.net`;

const client = new SecretClient(url, credential);

const secretName = "MySecretName";

async function main() {
  const poller = await client.beginDeleteSecret(secretName);

  while (!poller.isDone()) {
    await poller.poll();
    await delay(5000);
  }

  console.log(`The secret ${secretName} is fully deleted`);
}

main();

反覆運算秘密清單

使用 SecretClient，您可以擷取並逐一查看 金鑰保存庫 中的所有秘密，以及透過所有已刪除的秘密和特定秘密的版本。 下列 API 方法可供使用：

  • listPropertiesOfSecrets 只會依其名稱列出所有未刪除的秘密，只列出其最新版本。
  • listDeletedSecrets 只會依其名稱列出所有已刪除的秘密，只列出其最新版本。
  • listPropertiesOfSecretVersions 會根據秘密名稱列出秘密的所有版本。

可用方式如下：

const { DefaultAzureCredential } = require("@azure/identity");
const { SecretClient } = require("@azure/keyvault-secrets");

const credential = new DefaultAzureCredential();

const vaultName = "<YOUR KEYVAULT NAME>";
const url = `https://${vaultName}.vault.azure.net`;

const client = new SecretClient(url, credential);

const secretName = "MySecretName";

async function main() {
  for await (let secretProperties of client.listPropertiesOfSecrets()) {
    console.log("Secret properties: ", secretProperties);
  }
  for await (let deletedSecret of client.listDeletedSecrets()) {
    console.log("Deleted secret: ", deletedSecret);
  }
  for await (let versionProperties of client.listPropertiesOfSecretVersions(secretName)) {
    console.log("Version properties: ", versionProperties);
  }
}

main();

所有這些方法都會一次傳回 所有可用的結果 。 若要依頁面擷取它們，請在叫用您想要使用的 API 方法之後新增 .byPage() ，如下所示：

const { DefaultAzureCredential } = require("@azure/identity");
const { SecretClient } = require("@azure/keyvault-secrets");

const credential = new DefaultAzureCredential();

const vaultName = "<YOUR KEYVAULT NAME>";
const url = `https://${vaultName}.vault.azure.net`;

const client = new SecretClient(url, credential);

const secretName = "MySecretName";

async function main() {
  for await (let page of client.listPropertiesOfSecrets().byPage()) {
    for (let secretProperties of page) {
      console.log("Secret properties: ", secretProperties);
    }
  }
  for await (let page of client.listDeletedSecrets().byPage()) {
    for (let deletedSecret of page) {
      console.log("Deleted secret: ", deletedSecret);
    }
  }
  for await (let page of client.listPropertiesOfSecretVersions(secretName).byPage()) {
    for (let versionProperties of page) {
      console.log("Version properties: ", versionProperties);
    }
  }
}

main();

疑難排解

如需如何診斷各種失敗案例的詳細資訊，請參閱我們的 疑難解答指南 。

啟用記錄有助於找出失敗的相關實用資訊。 若要查看 HTTP 的要求和回應記錄，請將 AZURE_LOG_LEVEL 環境變數設定為 info。 或者，您可以在 @azure/logger 中呼叫 setLogLevel，以在執行階段啟用記錄：

import { setLogLevel } from "@azure/logger";

setLogLevel("info");

後續步驟

您可以透過下列連結找到更多程式碼範例：

參與

如果您希望向此程式庫投稿，請參閱投稿指南，深入瞭解如何組建與測試程式碼。

曝光數