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

開始使用適用於 .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 <YourKeyVaultName> --upn user@domain.com --secret-permissions delete get list set 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.Secrets

針對本快速入門,您也需要安裝適用於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.Secrets;

驗證並建立用戶端

在本快速入門中,已登入的使用者是用來向金鑰保存庫進行驗證,這是本機開發的慣用方法。 針對部署至 Azure 的應用程式,應將受控識別指派給 App Service 或虛擬機器。如需詳細資訊,請參閱受控識別概觀

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

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

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

儲存秘密

既然主控台應用程式已通過驗證,請將秘密新增至金鑰保存庫。 針對這項工作,使用 SetSecretAsync 方法。 在此範例中,方法的第一個參數會接受密碼—"mySecret" 的名稱。

await client.SetSecretAsync(secretName, secretValue);

注意

如果秘密名稱存在,則上述程式碼會建立該秘密的新版本。

擷取祕密

您現在可以使用 GetSecretAsync 方法來擷取先前設定的值。

var secret = await client.GetSecretAsync(secretName);

您的祕密現在已另存為 secret.Value

刪除祕密

最後,讓我們使用 StartDeleteSecretAsyncPurgeDeletedSecretAsync 方法,從您的金鑰保存庫中刪除祕密。

var operation = await client.StartDeleteSecretAsync("mySecret");
// You only need to wait for completion if you want to purge or recover the key.
await operation.WaitForCompletionAsync();

await client.PurgeDeletedKeyAsync("mySecret");

範例程式碼

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

  1. Program.cs 中的程式碼取代為下列程式碼:

    using System;
    using System.Threading.Tasks;
    using Azure.Identity;
    using Azure.Security.KeyVault.Secrets;
    
    namespace key_vault_console_app
    {
        class Program
        {
            static async Task Main(string[] args)
            {
                const string secretName = "mySecret";
                var keyVaultName = Environment.GetEnvironmentVariable("KEY_VAULT_NAME");
                var kvUri = $"https://{keyVaultName}.vault.azure.net";
    
                var client = new SecretClient(new Uri(kvUri), new DefaultAzureCredential());
    
                Console.Write("Input the value of your secret > ");
                var secretValue = Console.ReadLine();
    
                Console.Write($"Creating a secret in {keyVaultName} called '{secretName}' with the value '{secretValue}' ...");
                await client.SetSecretAsync(secretName, secretValue);
                Console.WriteLine(" done.");
    
                Console.WriteLine("Forgetting your secret.");
                secretValue = string.Empty;
                Console.WriteLine($"Your secret is '{secretValue}'.");
    
                Console.WriteLine($"Retrieving your secret from {keyVaultName}.");
                var secret = await client.GetSecretAsync(secretName);
                Console.WriteLine($"Your secret is '{secret.Value.Value}'.");
    
                Console.Write($"Deleting your secret from {keyVaultName} ...");
                DeleteSecretOperation operation = await client.StartDeleteSecretAsync(secretName);
                // You only need to wait for completion if you want to purge or recover the secret.
                await operation.WaitForCompletionAsync();
                Console.WriteLine(" done.");
    
                Console.Write($"Purging your secret from {keyVaultName} ...");
                await client.PurgeDeletedSecretAsync(secretName);
                Console.WriteLine(" done.");
            }
        }
    }
    

測試和驗證

  1. 執行下列命令來執行應用程式。

    dotnet run
    
  2. 當系統提示時,輸入祕密值。 例如,mySecretPassword。

下列輸出的變化會出現:

Input the value of your secret > mySecretPassword
Creating a secret in <your-unique-keyvault-name> called 'mySecret' with the value 'mySecretPassword' ... done.
Forgetting your secret.
Your secret is ''.
Retrieving your secret from <your-unique-keyvault-name>.
Your secret is 'mySecretPassword'.
Deleting your secret from <your-unique-keyvault-name> ... done.    
Purging your secret from <your-unique-keyvault-name> ... done.

後續步驟

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