快速入門:適用於 .NET (SDK v4) 的 Azure Key Vault 憑證用戶端程式庫

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

Key Vault 用戶端程式庫資源:

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

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

必要條件

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

安裝程式

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

登入 Azure

  1. 執行 login 命令。

    az login
    

    如果 CLI 可以開啟預設瀏覽器,它會執行這項操作,並載入 Azure 登入頁面。

    否則,請在 https://aka.ms/devicelogin 中開啟瀏覽器頁面,並輸入顯示在終端機中的授權碼。

  2. 請在瀏覽器中使用您的帳戶認證登入。

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

建立金鑰保存庫的存取原則,將憑證權限授與服務主體

az keyvault set-policy --name <your-key-vault-name> --upn user@domain.com --certificate-permissions delete get list create purge

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

  1. 在命令殼層中,執行下列命令以建立名為 key-vault-console-app 的專案:

    dotnet new console --name key-vault-console-app
    
  2. 變更為新建立的 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 身分識別的 Azure SDK 用戶端程式庫:

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 的應用程式,應將受控識別指派給 App Service 或虛擬機器。如需詳細資訊,請參閱受控識別概觀

在下列範例中,金鑰保存庫的名稱展開成金鑰保存庫 URI,格式為 "https://<your-key-vault-name>.vault.azure.net"。 這個範例會使用來自 Azure 身分識別程式庫'DefaultAzureCredential()' 類別,允許在各種不同的環境中使用相同的程式碼,搭配不同的選項來提供身分識別。 如需對金鑰保存庫進行驗證的詳細資訊,請參閱開發人員指南

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

刪除憑證

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

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 Core 主控台應用程式,以與 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 以及如何將其與應用程式整合,請參閱下列文章: