共用方式為

適用於 JavaScript 的 Azure Key Vault 憑證用戶端連結庫 - 4.9.0 版

  • 發行項

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

如果您想要深入瞭解 Azure Key Vault，建議您檢閱：什麼是 Azure Key Vault？

在 Node.js 應用程式中，使用 Azure Key Vault 憑證的用戶端連結庫來：

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

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

主要連結：

開始

目前支持的環境

先決條件

安裝套件

使用 npm 安裝 Azure Key Vault 憑證用戶端連結庫

npm install @azure/keyvault-certificates

安裝身分識別連結庫

Key Vault 用戶端會使用 Azure 身分識別連結庫進行驗證。 使用 npm 安裝

npm install @azure/identity

設定 TypeScript

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

npm install @types/node

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

使用 Azure Active Directory 進行驗證

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

若要與 Azure Key Vault 服務互動，您必須建立 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);

重要概念

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

指定 Azure Key Vault 服務 API 版本

根據預設，此套件會使用最新的 Azure Key Vault 服務版本，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 Key Vault 憑證的一些常見工作。 這裡涵蓋的案例包括：

建立和設定憑證

beginCreateCertificate 建立要儲存在 Azure Key Vault 中的憑證。 如果已有相同名稱的憑證存在，則會建立新版本的憑證。

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();

取得 Key Vault 憑證

從保存庫讀取憑證的最簡單方式是依名稱取得憑證。 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 憑證時，也會使用相同的名稱來建立可尋址的金鑰和秘密。 Key Vault 金鑰允許金鑰作業，而 Key Vault 秘密允許擷取憑證值做為秘密。 Key Vault 憑證也包含公用 x509 憑證元數據。 來源：憑證的 組合。

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

// 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 的 Key Vault 服務在建立憑證時提供 contentType 屬性，以 PEM 格式建立和管理憑證。

下列範例示範如何使用 Key Vault 用戶端來建立和擷取 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 會列出 Key Vault 中的所有憑證。

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");

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

後續步驟

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

貢獻

如果您想要參與此連結庫，請閱讀 參與指南，以深入瞭解如何建置和測試程序代碼。

印象