適用於 JavaScript 的 Azure 金鑰保存庫憑證用戶端連結庫 - 4.8.0 版

發行項
02/26/2024

Azure 金鑰保存庫是雲端服務，可提供整個雲端應用程式所使用的憑證安全記憶體和自動化管理。多個憑證和相同憑證的多個版本都可以保留在 Azure 金鑰保存庫中。保存庫中的每一個憑證都有與其相關聯的原則，可控制憑證的發行和存留期，以及即將到期作為憑證採取的動作。

如果您想要深入瞭解 Azure 金鑰保存庫，您可以檢閱：什麼是 Azure 金鑰保存庫？

在 Node.js 應用程式中使用適用於 Azure 金鑰保存庫憑證的用戶端連結庫，以：

取得、設定和刪除憑證。
更新憑證、其屬性、簽發者、原則、作業和聯繫人。
備份和還原憑證。
取得、清除或復原已刪除的憑證。
取得憑證的所有版本。
取得所有憑證。
取得所有已刪除的憑證。

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

重要連結：

開始使用

目前支援的環境

Node.js 的 LTS 版本

必要條件

Azure 訂用帳戶
現有的 Azure 金鑰保存庫。如果您需要建立金鑰保存庫，您可以依照本文件中的步驟，在 Azure 入口網站中執行此動作。或者，依照下列步驟使用 Azure CLI。

安裝套件

使用 npm 安裝 Azure 金鑰保存庫憑證用戶端連結庫

npm install @azure/keyvault-certificates

安裝身分識別連結庫

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

npm install @azure/identity

設定 TypeScript

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

npm install @types/node

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

使用 Azure Active Directory 進行驗證

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

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

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

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

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

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

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

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 certificates client and connect to the service
const client = new CertificateClient(url, credential);

重要概念

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

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

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

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

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 CertificateClient(url, credential, {
  serviceVersion: "7.0",
});

範例

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

建立和設定憑證。
取得金鑰保存庫憑證。
取得憑證的完整資訊。
PEM 格式的憑證。
列出所有憑證。
更新憑證。
刪除憑證。
反覆運算憑證清單。

建立和設定憑證

beginCreateCertificate會建立要儲存在 Azure 金鑰保存庫中的憑證。如果具有相同名稱的憑證已經存在，則會建立新版本的憑證。

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

const credential = new DefaultAzureCredential();

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

const client = new CertificateClient(url, credential);

const certificateName = "MyCertificateName";

async function main() {
  // Note: Sending `Self` as the `issuerName` of the certificate's policy will create a self-signed certificate.
  await client.beginCreateCertificate(certificateName, {
    issuerName: "Self",
    subject: "cn=MyCert",
  });
}

main();

除了憑證名稱和原則的名稱之外，您也可以在具有選擇性值的第三個自變數中傳遞下列屬性：

enabled：布爾值，決定是否可以使用憑證。
tags：任何可用來搜尋和篩選憑證的索引鍵/值集。

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

const credential = new DefaultAzureCredential();

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

const client = new CertificateClient(url, credential);

const certificateName = "MyCertificateName";

// Note: Sending `Self` as the `issuerName` of the certificate's policy will create a self-signed certificate.
const certificatePolicy = {
  issuerName: "Self",
  subject: "cn=MyCert",
};
const enabled = true;
const tags = {
  myCustomTag: "myCustomTagsValue",
};

async function main() {
  await client.beginCreateCertificate(certificateName, certificatePolicy, {
    enabled,
    tags,
  });
}

main();

beginCreateCertificate以相同名稱呼叫會建立新版的相同憑證，此憑證將具有最新的提供屬性。

由於憑證需要一些時間才能完整建立，因此會傳迴輪詢器物件， beginCreateCertificate 以根據我們的指導方針來追蹤基礎長時間執行作業： https://azure.github.io/azure-sdk/typescript_design.html#ts-lro

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

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

const credential = new DefaultAzureCredential();

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

const client = new CertificateClient(url, credential);

const certificateName = "MyCertificateName";
const certificatePolicy = {
  issuerName: "Self",
  subject: "cn=MyCert",
};

async function main() {
  const poller = await client.beginCreateCertificate(certificateName, certificatePolicy);

  // You can use the pending certificate immediately:
  const pendingCertificate = poller.getResult();

  // Or you can wait until the certificate finishes being signed:
  const keyVaultCertificate = await poller.pollUntilDone();
  console.log(keyVaultCertificate);
}

main();

另一種等候憑證簽署的方式是執行個別呼叫，如下所示：

const { DefaultAzureCredential } = require("@azure/identity");
const { CertificateClient } = require("@azure/keyvault-certificates");
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 CertificateClient(url, credential);

const certificateName = "MyCertificateName";
const certificatePolicy = {
  issuerName: "Self",
  subject: "cn=MyCert",
};

async function main() {
  const poller = await client.beginCreateCertificate(certificateName, certificatePolicy);

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

  console.log(`The certificate ${certificateName} is fully created`);
}

main();

取得金鑰保存庫憑證

從保存庫讀取憑證的最簡單方式是依名稱取得憑證。 getCertificate 將會擷取最新版的憑證，以及憑證的原則。如果您指定版本，您可以選擇性地取得不同版本的憑證 getCertificateVersion 。 getCertificateVersion 不會傳回憑證的原則。

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

const credential = new DefaultAzureCredential();

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

const client = new CertificateClient(url, credential);

const certificateName = "MyCertificateName";

async function main() {
  const latestCertificate = await client.getCertificate(certificateName);
  console.log(`Latest version of the certificate ${certificateName}: `, latestCertificate);
  const specificCertificate = await client.getCertificateVersion(
    certificateName,
    latestCertificate.properties.version
  );
  console.log(
    `The certificate ${certificateName} at the version ${latestCertificate.properties.version}: `,
    specificCertificate
  );
}

main();

取得憑證的完整資訊

Azure 金鑰保存庫的設計會區分密鑰、秘密和憑證。金鑰保存庫服務的憑證功能是設計成利用其密鑰和秘密功能。讓我們評估金鑰保存庫憑證的組合：

建立 Key Vault 憑證時，可定址的金鑰和秘密也會以相同名稱建立。 Key Vault 金鑰可讓金鑰作業和 Key Vault 秘密允許擷取憑證值作為秘密。 Key Vault 憑證也會包含公用 x509 憑證的中繼資料。 來源：憑證的組成。

知道私鑰儲存在金鑰保存庫秘密中，並包含公開憑證，我們可以使用金鑰保存庫 Secrets 用戶端來擷取它。

// Using the same credential object we used before,
// and the same keyVaultUrl,
// let's create a SecretClient
import { SecretClient } from "@azure/keyvault-secrets";

const secretClient = new SecretClient(keyVaultUrl, credential);

// Assuming you've already created a Key Vault certificate,
// and that certificateName contains the name of your certificate
const certificateSecret = await secretClient.getSecret(certificateName);

// Here we can find both the private key and the public certificate, in PKCS 12 format:
const PKCS12Certificate = certificateSecret.value!;

// You can write this into a file:
fs.writeFileSync("myCertificate.p12", PKCS12Certificate);

請注意，根據預設，憑證的內容類型是 PKCS 12。藉由指定憑證的內容類型，您將能夠以 PEM 格式擷取憑證。在示範如何建立 PEM 憑證之前，讓我們先探索如何先從 PKCS 12 憑證擷取 PEM 秘密密鑰。

使用 openssl，您可以使用下列命令，以 PEM 格式擷取公開憑證：

openssl pkcs12 -in myCertificate.p12 -out myCertificate.crt.pem -clcerts -nokeys

您也可以使用 openssl 來擷取私鑰，如下所示：

openssl pkcs12 -in myCertificate.p12 -out myCertificate.key.pem -nocerts -nodes

請注意，在這兩種情況下，openssl 會要求您輸入用來建立憑證的密碼。我們到目前為止使用的範例程式代碼尚未指定密碼，因此您可以附加 -passin 'pass:' 至每個命令的結尾。

PEM 格式的憑證

如果您想要使用 PEM 格式的憑證，您可以指示 Azure 的金鑰保存庫服務在建立憑證時提供 contentType 屬性，以 PEM 格式建立和管理憑證。

下列範例示範如何使用憑證和秘密的金鑰保存庫用戶端，建立和擷取 PEM 格式化憑證的公用和私人部分：

// Creating the certificate
const certificateName = "MyCertificate";
const createPoller = await client.beginCreateCertificate(certificateName, {
  issuerName: "Self",
  subject: "cn=MyCert",
  contentType: "application/x-pem-file", // Here you specify you want to work with PEM certificates.
});
const keyVaultCertificate = await createPoller.pollUntilDone();

// Getting the PEM formatted private key and public certificate:
const certificateSecret = await secretClient.getSecret(certificateName);
const PEMPair = certificateSecret.value!;

console.log(PEMPair);

請記住，您的公開憑證會與您的私鑰位於相同的內容 Blob 中。您可以使用 PEM 標頭據以擷取它們。

列出所有憑證

listPropertiesOfCertificates將會列出金鑰保存庫中的所有憑證。

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

const credential = new DefaultAzureCredential();

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

const client = new CertificateClient(url, credential);

async function main() {
  for await (let certificateProperties of client.listPropertiesOfCertificates()) {
    console.log("Certificate properties: ", certificateProperties);
  }
}

main();

更新憑證

您可以使用將憑證屬性更新為現有的憑證版本 updateCertificate，如下所示：

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

const credential = new DefaultAzureCredential();

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

const client = new CertificateClient(url, credential);

const certificateName = "MyCertificateName";

async function main() {
  const result = await client.getCertificate(certificateName);
  await client.updateCertificateProperties(certificateName, result.properties.version, {
    enabled: false,
    tags: {
      myCustomTag: "myCustomTagsValue",
    },
  });
}

main();

您也可以使用 updateCertificatePolicy個別更新憑證的原則，如下所示：

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

const credential = new DefaultAzureCredential();

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

const client = new CertificateClient(url, credential);

const certificateName = "MyCertificateName";

async function main() {
  const result = client.getCertificate(certificateName);
  // Note: Sending `Self` as the `issuerName` of the certificate's policy will create a self-signed certificate.
  await client.updateCertificatePolicy(certificateName, {
    issuerName: "Self",
    subject: "cn=MyCert",
  });
}

main();

刪除憑證

方法會 beginDeleteCertificate 設定要刪除的憑證。一旦有可用的必要資源，此程式就會在背景中發生。

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

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

const credential = new DefaultAzureCredential();

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

const client = new CertificateClient(url, credential);

const certificateName = "MyCertificateName";

async function main() {
  const poller = await client.beginDeleteCertificate(certificateName);

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

  // The certificate 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 certificate this way:
  await client.getDeletedCertificate(certificateName);

  // Deleted certificates can also be recovered or purged.

  // recoverDeletedCertificate returns a poller, just like beginDeleteCertificate.
  // const recoverPoller = await client.beginRecoverDeletedCertificate(certificateName);
  // await recoverPoller.pollUntilDone();

  // If a certificate is done and the Key Vault has soft-delete enabled, the certificate can be purged with:
  await client.purgeDeletedCertificate(certificateName);
}

main();

由於刪除憑證不會立即發生，因此呼叫方法之後需要一些時間， beginDeleteCertificate 才能讀取、復原或清除已刪除的憑證。

反覆運算憑證清單

使用 CertificateClient，您可以擷取並逐一查看 Certificate Vault 中的所有憑證，以及透過所有已刪除的憑證和特定憑證的版本。以下是可用的 API 方法：

listPropertiesOfCertificates 只會依其名稱列出所有未刪除的憑證，僅適用於最新版本。
listDeletedCertificates 只會依其名稱列出所有已刪除的憑證，僅適用於其最新版本。
listPropertiesOfCertificateVersions 會根據憑證名稱列出憑證的所有版本。

這可如下所示使用：

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

const credential = new DefaultAzureCredential();

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

const client = new CertificateClient(url, credential);

const certificateName = "MyCertificateName";

async function main() {
  for await (let certificateProperties of client.listPropertiesOfCertificates()) {
    console.log("Certificate properties: ", certificateProperties);
  }
  for await (let deletedCertificate of client.listDeletedCertificates()) {
    console.log("Deleted certificate: ", deletedCertificate);
  }
  for await (let certificateProperties of client.listPropertiesOfCertificateVersions(
    certificateName
  )) {
    console.log("Certificate properties: ", certificateProperties);
  }
}

main();

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

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

const credential = new DefaultAzureCredential();

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

const client = new CertificateClient(url, credential);

const certificateName = "MyCertificateName";

async function main() {
  for await (let page of client.listPropertiesOfCertificates().byPage()) {
    for (let certificateProperties of page) {
      console.log("Certificate properties: ", certificateProperties);
    }
  }
  for await (let page of client.listDeletedCertificates().byPage()) {
    for (let deletedCertificate of page) {
      console.log("Deleted certificate: ", deletedCertificate);
    }
  }
  for await (let page of client.listPropertiesOfCertificateVersions(certificateName).byPage()) {
    for (let certificateProperties of page) {
      console.log("Properties of certificate: ", certificateProperties);
    }
  }
}

main();

疑難排解

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

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

setLogLevel("info");

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

下一步

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

參與

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

曝光數

適用於 JavaScript 的 Azure 金鑰保存庫憑證用戶端連結庫 - 4.8.0 版

開始使用

目前支援的環境

必要條件

安裝套件

安裝身分識別連結庫

設定 TypeScript

使用 Azure Active Directory 進行驗證

重要概念

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

範例

建立和設定憑證

取得金鑰保存庫憑證

取得憑證的完整資訊

PEM 格式的憑證

列出所有憑證

更新憑證

刪除憑證

反覆運算憑證清單

疑難排解

下一步

參與

意見反應

其他資源

適用於 JavaScript 的 Azure 金鑰保存庫 憑證用戶端連結庫 - 4.8.0 版

開始使用

目前支援的環境

必要條件

安裝套件

安裝身分識別連結庫

設定 TypeScript

使用 Azure Active Directory 進行驗證

重要概念

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

範例

建立和設定憑證

取得 金鑰保存庫 憑證

取得憑證的完整資訊

PEM 格式的憑證

列出所有憑證

更新憑證

刪除憑證

反覆運算憑證清單

疑難排解

下一步

參與

意見反應

其他資源

適用於 JavaScript 的 Azure 金鑰保存庫憑證用戶端連結庫 - 4.8.0 版

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

取得金鑰保存庫憑證