共用方式為

適用于 .NET 的 Azure 金鑰保存庫 憑證用戶端程式庫 - 4.5.1 版

  • 發行項

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

Azure 金鑰保存庫憑證用戶端程式庫可讓您以程式設計方式管理憑證、提供方法來建立、更新、列出和刪除憑證、原則、簽發者和連絡人。 此程式庫也支援管理擱置的憑證作業和管理已刪除的憑證。

| 原始程式碼套件 (NuGet) | API 參考檔 | 產品檔 | 樣品 | 移轉指南

開始使用

安裝套件

使用NuGet安裝適用于 .NET 的 Azure 金鑰保存庫憑證用戶端程式庫：

dotnet add package Azure.Security.KeyVault.Certificates

必要條件

  • Azure 訂用帳戶。
  • 現有的 Azure 金鑰保存庫。 如果您需要建立 Azure 金鑰保存庫，您可以使用 Azure 入口網站或Azure CLI。
  • 使用RBAC (建議) 或存取控制授權給現有的 Azure 金鑰保存庫。

如果您使用 Azure CLI，請將 和 <your-key-vault-name> 取代 <your-resource-group-name> 為您自己的唯一名稱：

az keyvault create --resource-group <your-resource-group-name> --name <your-key-vault-name>

驗證用戶端

若要與 Azure 金鑰保存庫 服務互動，您必須建立CertificateClient類別的實例。 您需要保存 庫 URL，您可能會在入口網站中看到「DNS 名稱」，以及具現化用戶端物件的認證。

以下顯示的範例會使用 DefaultAzureCredential ，適用于大部分案例，包括本機開發和生產環境。 此外，我們建議在生產環境中使用受控識別進行驗證。 您可以在 Azure 身分識別 檔中，找到不同驗證方式及其對應認證類型的詳細資訊。

若要使用如下所示的 DefaultAzureCredential 提供者，或其他 Azure SDK 提供的認證提供者，您必須先安裝 Azure.Identity 套件：

dotnet add package Azure.Identity

建立 CertificateClient

具現化 DefaultAzureCredential 以傳遞至用戶端。 如果權杖認證的實例會使用相同的身分識別進行驗證，則可以與多個用戶端搭配使用。

// Create a new certificate client using the default credential from Azure.Identity using environment variables previously set,
// including AZURE_CLIENT_ID, AZURE_CLIENT_SECRET, and AZURE_TENANT_ID.
var client = new CertificateClient(vaultUri: new Uri(vaultUrl), credential: new DefaultAzureCredential());

重要概念

KeyVaultCertificate

KeyVaultCertificate是 Azure 金鑰保存庫內的基本資源。 您將使用憑證來加密和驗證已加密或已簽署的資料。

CertificateClient

您可以使用 從 CertificateClient 保存庫取得憑證、建立新的憑證和新版本的現有憑證、更新憑證中繼資料，以及刪除憑證。 您也可以管理憑證的憑證簽發者、連絡人和管理原則。 以下範例將說明這一點。

執行緒安全

我們保證所有用戶端實例方法都是安全線程，且彼此獨立 (指導方針) 。 這可確保重複使用用戶端實例的建議一律是安全的，即使是跨執行緒也一樣。

其他概念

用戶端選項 | 存取回應 | 長時間執行的作業 | 處理失敗 | 診斷 | 嘲笑 | 用戶端存留期

範例

Azure.Security.KeyVault.Certificates 套件支援同步和非同步 API。

下一節提供 client 使用上述所建立的數個程式碼片段，涵蓋一些最常見的 Azure 金鑰保存庫憑證服務相關工作：

同步範例

非同步範例

建立憑證

StartCreateCertificate會建立要儲存在 Azure 金鑰保存庫中的憑證。 如果已有相同名稱的憑證存在，則會建立新版本的憑證。 建立憑證時，使用者可以指定控制憑證存留期的原則。 如果未指定任何原則，則會使用預設原則。 作業會 StartCreateCertificate 傳 CertificateOperation 回 。 下列範例會建立具有預設原則的自我簽署憑證。

// Create a certificate. This starts a long running operation to create and sign the certificate.
CertificateOperation operation = client.StartCreateCertificate("MyCertificate", CertificatePolicy.Default);

// You can await the completion of the create certificate operation.
// You should run UpdateStatus in another thread or do other work like pumping messages between calls.
while (!operation.HasCompleted)
{
    Thread.Sleep(2000);

    operation.UpdateStatus();
}

KeyVaultCertificateWithPolicy certificate = operation.Value;

注意：根據憑證簽發者和驗證方法，建立憑證和簽署可能需要不確定的時間。 只有在應用程式範圍內可合理完成作業時，使用者才應該等候憑證作業，例如使用自我簽署憑證或具有已知回應時間的簽發者。

擷取憑證

GetCertificate擷取 Azure 金鑰保存庫中儲存的最新版本憑證及其 CertificatePolicy 。

KeyVaultCertificateWithPolicy certificateWithPolicy = client.GetCertificate("MyCertificate");

GetCertificateVersion 會擷取保存庫中特定版本的憑證。

KeyVaultCertificate certificate = client.GetCertificateVersion(certificateWithPolicy.Name, certificateWithPolicy.Properties.Version);

更新現有的憑證

UpdateCertificate會更新儲存在 Azure 金鑰保存庫 中的憑證。

CertificateProperties certificateProperties = new CertificateProperties(certificate.Id);
certificateProperties.Tags["key1"] = "value1";

KeyVaultCertificate updated = client.UpdateCertificateProperties(certificateProperties);

列出憑證

GetCertificates 列舉保存庫中的憑證，並傳回憑證的選取屬性。 將不會傳回憑證的敏感性欄位。 此作業需要憑證/清單許可權。

Pageable<CertificateProperties> allCertificates = client.GetPropertiesOfCertificates();

foreach (CertificateProperties certificateProperties in allCertificates)
{
    Console.WriteLine(certificateProperties.Name);
}

刪除憑證

DeleteCertificate會刪除儲存在 Azure 金鑰保存庫中的所有憑證版本。 當 Azure 金鑰保存庫未啟用虛刪除時，此作業會永久刪除憑證。 如果啟用虛刪除，憑證會標示為要刪除，而且可以選擇性地清除或復原，直到其排程清除日期為止。

DeleteCertificateOperation operation = client.StartDeleteCertificate("MyCertificate");

// You only need to wait for completion if you want to purge or recover the certificate.
// You should call `UpdateStatus` in another thread or after doing additional work like pumping messages.
while (!operation.HasCompleted)
{
    Thread.Sleep(2000);

    operation.UpdateStatus();
}

DeletedCertificate certificate = operation.Value;
client.PurgeDeletedCertificate(certificate.Name);

以非同步方式建立憑證

非同步 API 與其同步對應專案相同，但會傳回非同步方法的一般 「Async」 尾碼，並傳回 Task 。

此範例會在具有指定選擇性引數的 Azure 金鑰保存庫中建立憑證。

// Create a certificate. This starts a long running operation to create and sign the certificate.
CertificateOperation operation = await client.StartCreateCertificateAsync("MyCertificate", CertificatePolicy.Default);

// You can await the completion of the create certificate operation.
KeyVaultCertificateWithPolicy certificate = await operation.WaitForCompletionAsync();

以非同步方式列出憑證

列出憑證不依賴等候 GetPropertiesOfCertificatesAsync 方法，而是傳回 AsyncPageable<CertificateProperties> 您可以搭配 await foreach 語句使用的 ：

AsyncPageable<CertificateProperties> allCertificates = client.GetPropertiesOfCertificatesAsync();

await foreach (CertificateProperties certificateProperties in allCertificates)
{
    Console.WriteLine(certificateProperties.Name);
}

以非同步方式刪除憑證

在清除憑證之前，以非同步方式刪除憑證時，您可以等候 WaitForCompletionAsync 作業上的 方法。 根據預設，此迴圈會無限期地執行，但您可以傳遞 CancellationToken 來取消它。

DeleteCertificateOperation operation = await client.StartDeleteCertificateAsync("MyCertificate");

// You only need to wait for completion if you want to purge or recover the certificate.
await operation.WaitForCompletionAsync();

DeletedCertificate certificate = operation.Value;
await client.PurgeDeletedCertificateAsync(certificate.Name);

疑難排解

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

一般

當您使用 .NET SDK 與 Azure 金鑰保存庫 憑證用戶端程式庫互動時，服務傳回的錯誤會對應至針對REST API要求傳回的相同 HTTP 狀態碼。

例如，如果您嘗試擷取 Azure 金鑰保存庫中不存在的金鑰， 404 則會傳回錯誤，指出 Not Found 。

try
{
    KeyVaultCertificateWithPolicy certificateWithPolicy = client.GetCertificate("SomeCertificate");
}
catch (RequestFailedException ex)
{
    Console.WriteLine(ex.ToString());
}

您會發現會記錄其他資訊，例如作業的用戶端要求識別碼。

Message:
    Azure.RequestFailedException : Service request failed.
    Status: 404 (Not Found)
Content:
    {"error":{"code":"CertificateNotFound","message":"Certificate not found: MyCertificate"}}

Headers:
    Cache-Control: no-cache
    Pragma: no-cache
    Server: Microsoft-IIS/10.0
    x-ms-keyvault-region: westus
    x-ms-request-id: 625f870e-10ea-41e5-8380-282e5cf768f2
    x-ms-keyvault-service-version: 1.1.0.866
    x-ms-keyvault-network-info: addr=131.107.174.199;act_addr_fam=InterNetwork;
    X-AspNet-Version: 4.0.30319
    X-Powered-By: ASP.NET
    Strict-Transport-Security: max-age=31536000;includeSubDomains
    X-Content-Type-Options: nosniff
    Date: Tue, 18 Jun 2019 16:02:11 GMT
    Content-Length: 75
    Content-Type: application/json; charset=utf-8
    Expires: -1

下一步

此 GitHub 存放庫中有數個 Azure 金鑰保存庫 憑證用戶端程式庫範例可供您使用。 這些範例提供使用 Azure 金鑰保存庫時常見之其他案例的範例程式碼：

  • Sample1_HelloWorld.md - 用於使用 Azure 金鑰保存庫 憑證，包括：

    • 建立憑證
    • 取得現有的憑證
    • 更新現有的憑證
    • 刪除憑證

  • Sample2_GetCertificates.md - 使用 Azure 金鑰保存庫 憑證的範例程式碼，包括：

    • 建立憑證
    • 列出金鑰保存庫中的所有憑證
    • 列出指定憑證的版本
    • 從金鑰保存庫中刪除憑證
    • 列出金鑰保存庫中刪除的憑證

其他文件

參與

如需建 置 、測試及參與這些程式庫的詳細資訊，請參閱 CONTRIBUTING.md。

此專案歡迎參與和提供建議。 大部分的參與都要求您同意「參與者授權合約 (CLA)」，宣告您有權且確實授與我們使用投稿的權利。 如需詳細資料，請前往 https://cla.microsoft.com 。

當您提交提取要求時，CLA Bot 會自動判斷您是否需要提供 CLA，並適當地裝飾 PR (例如標籤、註解)。 請遵循 bot 提供的指示。 您只需要使用我們的 CLA 在所有存放庫上執行此動作一次。

此專案採用 Microsoft Open Source Code of Conduct (Microsoft 開放原始碼管理辦法)。 如需詳細資訊，請參閱管理辦法常見問題集，如有任何其他問題或意見請連絡 opencode@microsoft.com。

曝光數