Краткое руководство. Клиентская библиотека секретов Azure Key Vault для .NET

Статья
04/08/2024

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

Ресурсы клиентской библиотеки Key Vault:

Справочная документация по API | Исходный код библиотеки | Пакет (NuGet).

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

Необходимые компоненты

Подписка Azure — создайте бесплатную учетную запись.
Пакет SDK для .NET 6 или более поздней версии
Azure CLI или Azure PowerShell.
Key Vault — вы можете создать его с помощью портал Azure, Azure CLI или Azure PowerShell

В этом кратком руководстве используется dotnet и Azure CLI или Azure PowerShell

В этом кратком руководстве используется библиотека удостоверений Azure и Azure CLI для проверки подлинности пользователя в службах Azure. Разработчики также могут использовать Visual Studio или Visual Studio Code для проверки подлинности своих вызовов. Дополнительные сведения см. в статье Проверка подлинности клиента с помощью клиентской библиотеки удостоверений Azure.

Выполните команду az login.
```
az login
```
Если в CLI можно запустить браузер по умолчанию, откроется браузер со страницей входа.

В противном случае самостоятельно откройте в браузере страницу https://aka.ms/devicelogin и введите код авторизации, отображаемый в терминале.
Выполните вход в браузере с помощью учетных данных.

Предоставление доступа к хранилищу ключей

Azure CLI
Azure PowerShell

Чтобы предоставить приложению разрешения для хранилища ключей с помощью контроль доступа на основе ролей (RBAC), назначьте роль с помощью команды Azure CLI az role assignment create.

az role assignment create --role "Key Vault Secrets User" --assignee "<app-id>" --scope "/subscriptions/<subscription-id>/resourceGroups/<resource-group-name>/providers/Microsoft.KeyVault/vaults/<your-unique-keyvault-name>"

Чтобы предоставить приложению разрешения для хранилища ключей с помощью контроль доступа на основе ролей (RBAC), назначьте роль с помощью командлета Azure PowerShell New-AzRoleAssignment.

New-AzRoleAssignment -ObjectId "<app-id>" -RoleDefinitionName "Key Vault Secrets User" -Scope "/subscriptions/<subscription-id>/resourceGroups/<resource-group-name>/providers/Microsoft.KeyVault/vaults/<your-unique-keyvault-name>"

Замените app-id>, subscription-id>, <<resource-group-name и <your-unique-keyvault-name>> фактическими значениями.< <Идентификатор приложения — это идентификатор> приложения (клиента) зарегистрированного приложения в Azure AD.

В этом кратком руководстве используется библиотека удостоверений Azure и Azure PowerShell для проверки подлинности пользователя в службах Azure. Разработчики также могут использовать Visual Studio или Visual Studio Code для проверки подлинности своих вызовов. Дополнительные сведения см. в статье Проверка подлинности клиента с помощью клиентской библиотеки удостоверений Azure.

Выполните команду Connect-AzAccount.
```
Connect-AzAccount
```
Если PowerShell имеет возможность запустить браузер по умолчанию, он откроет в нем страницу входа в Azure.

В противном случае самостоятельно откройте в браузере страницу https://aka.ms/devicelogin и введите код авторизации, отображаемый в терминале.
Выполните вход в браузере с помощью учетных данных.

Предоставление доступа к хранилищу ключей

Azure CLI
Azure PowerShell

az role assignment create --role "Key Vault Secrets User" --assignee "<app-id>" --scope "/subscriptions/<subscription-id>/resourceGroups/<resource-group-name>/providers/Microsoft.KeyVault/vaults/<your-unique-keyvault-name>"

New-AzRoleAssignment -ObjectId "<app-id>" -RoleDefinitionName "Key Vault Secrets User" -Scope "/subscriptions/<subscription-id>/resourceGroups/<resource-group-name>/providers/Microsoft.KeyVault/vaults/<your-unique-keyvault-name>"

Создание консольного приложения .NET

В командной оболочке выполните следующую команду, чтобы создать проект с именем key-vault-console-app.
```
dotnet new console --name key-vault-console-app
```
Перейдите ко вновь созданному каталогу 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:

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

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

В этом примере имя хранилища ключей расширяется в URI хранилища ключей в формате https://<your-key-vault-name>.vault.azure.net. Дополнительные сведения о проверке подлинности в хранилище ключей см. в руководстве для разработчиков.

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

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

Сохранение секрета

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

Первый параметр метода принимает имя секрета. В этом примере переменная secretName сохраняет строку mySecret.

Второй параметр метода принимает значение секрета. В этом примере секрет вводится пользователем с помощью командной строки и хранится в переменной secretValue.

await client.SetSecretAsync(secretName, secretValue);

Примечание.

Если имя секрета существует, код создаст новую версию этого секрета.

Получение секрета

Теперь вы можете получить ранее заданное значение с помощью метода GetSecretAsync.

var secret = await client.GetSecretAsync(secretName);

Секрет теперь сохраняется как secret.Value.

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

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

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

await client.PurgeDeletedSecretAsync(secretName);

Пример кода

Измените консольное приложение .NET для взаимодействия с Key Vault, выполнив следующие действия:

Замените код файла 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.");
        }
    }
}

Тестирование и проверка

Выполните следующую команду для запуска этого приложения.
```
dotnet run
```
При появлении запроса введите значение секрета. Например, 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 и о том, как интегрировать его с вашими приложениями, см. в следующих статьях:

Краткое руководство. Клиентская библиотека секретов Azure Key Vault для .NET

Необходимые компоненты

Настройка

Вход в Azure

Предоставление доступа к хранилищу ключей

Создание консольного приложения .NET

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

Настройка переменных среды

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

Примеры кода

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

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

Сохранение секрета

Получение секрета

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

Пример кода

Тестирование и проверка

Следующие шаги

Дополнительные ресурсы