Краткое руководство. Использование клиентской библиотеки секретов Azure Key Vault для .NET (пакет SDK версии 4)

Начало работы с клиентской библиотекой секретов Azure Key Vault для .NET. Azure Key Vault — это облачная служба, которая предоставляет защищенное хранилище для секретов. Вы можете безопасно хранить ключи, пароли, сертификаты и другие секреты. Создать хранилища Azure Key Vault и управлять ими можно на портале Azure. В рамках этого краткого руководства вы узнаете, как создавать, извлекать и удалять секреты в Azure Key Vault с помощью клиентской библиотеки .NET.

Ресурсы клиентской библиотеки 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 можно запустить браузер по умолчанию, откроется браузер со страницей входа.

    Если нет, самостоятельно откройте в браузере страницу 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-store-console-app и выполните следующую команду, чтобы начать сборку проекта.

    dotnet build
    

    Выходные данные сборки не должны содержать предупреждений или ошибок.

    Build succeeded.
     0 Warning(s)
     0 Error(s)
    

Установка пакетов

Из командной оболочки установите клиентскую библиотеку секретов Azure Key Vault для .NET:

dotnet add package Azure.Security.KeyVault.Secrets

Для этого краткого руководства вам также потребуется установить клиентскую библиотеку Azure SDK для Удостоверения Azure:

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>

Объектная модель

Клиентская библиотека секретов Azure Key Vault для .NET позволяет управлять секретами. В разделе Примеры кода показано, как создать клиент, задать секрет, получить секрет и удалить секрет.

Примеры кода

Добавление директив

Добавьте следующие директивы в начало Program.cs.

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

Аутентификация и создание клиента

В этом кратком руководстве пользователь, вошедший в систему, проходит проверку подлинности в хранилище ключей, который является предпочтительным методом при локальной разработке. Для приложений, развернутых в Azure, службе приложений или виртуальной машине должно быть назначено управляемое удостоверение. Дополнительные сведения см. в разделе Обзор управляемых удостоверений.

В примере ниже имя хранилища ключей расширяется до универсального кода ресурса (URI) хранилища ключей в формате "https://<имя_хранилища_ключей>.vault.azure.net". В этом примере показан класс DefaultAzureCredential() из библиотеки удостоверений Azure, который для предоставления удостоверения позволяет использовать один и тот же код в различных средах с различными параметрами. Дополнительные сведения о проверке подлинности в хранилище ключей см. в руководстве для разработчиков.

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.

Удаление секрета.

Наконец, мы удалим секрет из хранилища ключей с помощью методов StartDeleteSecretAsync и PurgeDeletedSecretAsync.

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 для взаимодействия с Azure 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.

Дальнейшие действия

Дополнительные сведения об Azure Key Vault и о том, как интегрировать его с вашими приложениями, см. в следующих статьях: