Краткое руководство. Клиентская библиотека сертификатов 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.Certificates

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

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

Запросы приложений к большинству служб 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 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");

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

Теперь удалите сертификат из хранилища ключей и очистите его с помощью методов StartDeleteCertificateAsync и PurgeDeletedCertificateAsync.

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

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

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

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

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