快速入門：適用於 .NET 的 Azure Key Vault 憑證用戶端程式庫

發行項
10/05/2024

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

Key Vault 用戶端程式庫資源：

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

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

Key Vault 概觀
憑證概觀。

必要條件

Azure 訂用帳戶 - 建立免費帳戶
.NET 6 SDK 或更新版本
Azure CLI
Key Vault - 您可以使用 Azure 入口網站、Azure CLI 或 Azure PowerShell 建立。

本快速入門使用的是 dotnet 和 Azure CLI。

設定

本快速入門會使用 Azure 身分識別程式庫搭配 Azure CLI，向 Azure 服務驗證使用者。開發人員也可以使用 Visual Studio 或 Visual Studio Code 來驗證其呼叫。如需詳細資訊，請參閱使用 Azure 身分識別用戶端程式庫驗證用戶端。

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

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

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

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

az role assignment create --role "Key Vault Certificate 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)。

建立新的 .NET 主控台應用程式

在命令殼層中，執行下列命令以建立名為 key-vault-console-app 的專案：
```
dotnet new console --name key-vault-console-app
```
變更為新建立的 key-vault-console-app 目錄，然後執行下列命令來建置專案：
```
dotnet build
```
建置輸出應該不會有警告或錯誤。
```
Build succeeded.
 0 Warning(s)
 0 Error(s)
```

安裝套件

從命令殼層安裝適用於 .NET 的 Azure Key Vault 憑證用戶端程式庫：

dotnet add package Azure.Security.KeyVault.Certificates

針對本快速入門，您也需要安裝 Azure Identity 用戶端程式庫：

dotnet add package Azure.Identity

設定環境變數

該應用程式會從名為 KEY_VAULT_NAME 的環境變數中取得金鑰保存庫名稱。

Windows

set KEY_VAULT_NAME=<your-key-vault-name>

Windows PowerShell

$Env:KEY_VAULT_NAME="<your-key-vault-name>"

macOS 或 Linux

export KEY_VAULT_NAME=<your-key-vault-name>

物件模型

適用於 .NET 的 Azure Key Vault 憑證用戶端程式庫可讓您管理憑證。程式碼範例一節說明如何建立用戶端、設定憑證、擷取憑證及刪除憑證。

程式碼範例

新增指示詞

將下列指示詞新增至 Program.cs 的上方：

using System;
using Azure.Identity;
using Azure.Security.KeyVault.Certificates;

驗證並建立用戶端

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

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

在此範例中，金鑰保存庫的名稱會以 https://<your-key-vault-name>.vault.azure.net 格式，擴充至金鑰保存庫 URI。如需對金鑰保存庫進行驗證的詳細資訊，請參閱開發人員指南。

string keyVaultName = Environment.GetEnvironmentVariable("KEY_VAULT_NAME");
var kvUri = "https://" + keyVaultName + ".vault.azure.net";

var client = new CertificateClient(new Uri(kvUri), new DefaultAzureCredential());

儲存憑證

在此範例中，為了簡單起見，您可以使用自我簽署憑證搭配預設發佈原則。針對這項工作，請使用 StartCreateCertificateAsync 方法。方法的參數接受憑證名稱和憑證原則。

var operation = await client.StartCreateCertificateAsync("myCertificate", CertificatePolicy.Default);
var certificate = await operation.WaitForCompletionAsync();

注意

如果憑證名稱存在，則上述程式碼會建立該憑證的新版本。

擷取憑證

您現在可以使用 GetCertificateAsync 方法擷取先前建立的憑證。

var certificate = await client.GetCertificateAsync("myCertificate");

刪除憑證

最後，讓我們從您的金鑰保存庫中，使用 StartDeleteCertificateAsync 和 PurgeDeletedCertificateAsync 方法來刪除並清除憑證。

var operation = await client.StartDeleteCertificateAsync("myCertificate");

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

var certificate = operation.Value;
await client.PurgeDeletedCertificateAsync("myCertificate");

範例指令碼

請完成下列步驟來修改 .NET 主控台應用程式，以與 Key Vault 互動：

將 Program.cs 中的程式碼取代為下列程式碼：

using System;
using System.Threading.Tasks;
using Azure.Identity;
using Azure.Security.KeyVault.Certificates;

namespace key_vault_console_app
{
    class Program
    {
        static async Task Main(string[] args)
        {
            const string certificateName = "myCertificate";
            var keyVaultName = Environment.GetEnvironmentVariable("KEY_VAULT_NAME");
            var kvUri = $"https://{keyVaultName}.vault.azure.net";

            var client = new CertificateClient(new Uri(kvUri), new DefaultAzureCredential());

            Console.Write($"Creating a certificate in {keyVaultName} called '{certificateName}' ...");
            CertificateOperation operation = await client.StartCreateCertificateAsync(certificateName, CertificatePolicy.Default);
            await operation.WaitForCompletionAsync();
            Console.WriteLine(" done.");

            Console.WriteLine($"Retrieving your certificate from {keyVaultName}.");
            var certificate = await client.GetCertificateAsync(certificateName);
            Console.WriteLine($"Your certificate version is '{certificate.Value.Properties.Version}'.");

            Console.Write($"Deleting your certificate from {keyVaultName} ...");
            DeleteCertificateOperation deleteOperation = await client.StartDeleteCertificateAsync(certificateName);
            // You only need to wait for completion if you want to purge or recover the certificate.
            await deleteOperation.WaitForCompletionAsync();
            Console.WriteLine(" done.");

            Console.Write($"Purging your certificate from {keyVaultName} ...");
            await client.PurgeDeletedCertificateAsync(certificateName);
            Console.WriteLine(" done.");
        }
    }
}

測試和驗證

執行下列命令來建置專案

dotnet build

隨即出現下列輸出的變化：

Creating a certificate in mykeyvault called 'myCertificate' ... done.
Retrieving your certificate from mykeyvault.
Your certificate version is '8532359bced24e4bb2525f2d2050738a'.
Deleting your certificate from mykeyvault ... done
Purging your certificate from mykeyvault ... done

下一步

在本快速入門中，您已建立金鑰保存庫、儲存憑證，並擷取該憑證。

若要深入了解 Key Vault 以及如何將其與應用程式整合，請參閱下列文章：

共用方式為