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

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

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

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

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

• Общие сведения о Key Vault
• Общие сведения о ключах.

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

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

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

Настройка

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

Вход в Azure

1. Выполните команду login.

   az login
   

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

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

2. Выполните вход в браузере с помощью учетных данных.

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

Azure CLI

Чтобы предоставить приложению разрешения для хранилища ключей с помощью контроль доступа на основе ролей (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>"

Azure PowerShell

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

Создание консольного приложения .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.Keys

В этом кратком руководстве также необходимо установить клиентскую библиотеку удостоверений 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.Keys;

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

Запросы приложений к большинству служб Azure должны быть авторизованы. Использование класса DefaultAzureCredential, предоставленного клиентской библиотекой удостоверений Azure, является рекомендуемым подходом для реализации бессерверных подключений к службам Azure в коде. DefaultAzureCredential поддерживает несколько способов проверки подлинности и определяет, какой из них следует использовать в среде выполнения. Такой подход позволяет приложению использовать различные способы проверки подлинности в разных средах (локальной и рабочей) без реализации кода для конкретной среды.

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

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

var keyVaultName = Environment.GetEnvironmentVariable("KEY_VAULT_NAME");
var kvUri = $"https://{keyVaultName}.vault.azure.net";

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

Сохранение ключа

Для этой задачи используйте метод CreateKeyAsync. Параметры метода принимают имя и тип ключа.

var key = await client.CreateKeyAsync("myKey", KeyType.Rsa);

Примечание.

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

Получение ключа

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

var key = await client.GetKeyAsync("myKey");

Удаление ключа

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

var operation = await client.StartDeleteKeyAsync("myKey");

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

var key = operation.Value;
await client.PurgeDeletedKeyAsync("myKey");

Пример кода

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

• Замените код файла Program.cs на код, приведенный ниже:

  using System;
  using System.Threading.Tasks;
  using Azure.Identity;
  using Azure.Security.KeyVault.Keys;
  
  namespace key_vault_console_app
  {
      class Program
      {
          static async Task Main(string[] args)
          {
              const string keyName = "myKey";
              var keyVaultName = Environment.GetEnvironmentVariable("KEY_VAULT_NAME");
              var kvUri = $"https://{keyVaultName}.vault.azure.net";
  
              var client = new KeyClient(new Uri(kvUri), new DefaultAzureCredential());
  
              Console.Write($"Creating a key in {keyVaultName} called '{keyName}' ...");
              var createdKey = await client.CreateKeyAsync(keyName, KeyType.Rsa);
              Console.WriteLine("done.");
  
              Console.WriteLine($"Retrieving your key from {keyVaultName}.");
              var key = await client.GetKeyAsync(keyName);
              Console.WriteLine($"Your key version is '{key.Value.Properties.Version}'.");
  
              Console.Write($"Deleting your key from {keyVaultName} ...");
              var deleteOperation = await client.StartDeleteKeyAsync(keyName);
              // You only need to wait for completion if you want to purge or recover the key.
              await deleteOperation.WaitForCompletionAsync();
              Console.WriteLine("done.");
  
              Console.Write($"Purging your key from {keyVaultName} ...");
              await client.PurgeDeletedKeyAsync(keyName);
              Console.WriteLine(" done.");
          }
      }
  }
  

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

1. Чтобы создать проект, выполните указанную ниже команду.

   dotnet build
   

2. Выполните следующую команду для запуска этого приложения.

   dotnet run
   

3. При появлении запроса введите значение секрета. Например, mySecretPassword.

   Отображаются выходные данные, аналогичные следующим:

   Creating a key in mykeyvault called 'myKey' ... done.
   Retrieving your key from mykeyvault.
   Your key version is '8532359bced24e4bb2525f2d2050738a'.
   Deleting your key from jl-kv ... done
   Purging your key from <your-unique-keyvault-name> ... done.   
   

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

Из этого краткого руководства вы узнали, как создать хранилище ключей, сохранить в нем ключ и извлечь его.

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

• Обзор Azure Key Vault
• Общие сведения о ключах
• См. Руководство по доступу к Key Vault из приложения службы приложений
• См. Руководство по доступу к Key Vault из виртуальной машины
• Руководство разработчика Azure Key Vault
• Статья Обзор системы безопасности Key Vault