Краткое руководство: клиентская библиотека секретов 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 — создайте бесплатную учетную запись.
• .NET 6 SDK или более поздней версии
• Azure CLI или Azure PowerShell.
• Key Vault — вы можете создать его с помощью Azure, Azure CLI или Azure PowerShell.

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

Настройка

az role assignment create --role "Key Vault Secrets Officer" --assignee "<upn>" --scope "/subscriptions/<subscription-id>/resourceGroups/myResourceGroup/providers/Microsoft.KeyVault/vaults/<vault-name>"

New-AzRoleAssignment -SignInName "<upn>" -RoleDefinitionName "Key Vault Secrets Officer" -Scope "/subscriptions/<subscription-id>/resourceGroups/myResourceGroup/providers/Microsoft.KeyVault/vaults/<vault-name>"

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

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

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

dotnet add package Azure.Security.KeyVault.Secrets

Для этого краткого старта вам также необходимо установить клиентскую библиотеку удостоверений Azure.

dotnet add package Azure.Identity

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

Это приложение использует имя хранилища ключей в качестве переменной окружения с именем KEY_VAULT_NAME.

Виндоус

set KEY_VAULT_NAME=<vault-name>

Windows PowerShell

$Env:KEY_VAULT_NAME="<vault-name>"

macOS или Linux

export KEY_VAULT_NAME=<vault-name>

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

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

Примеры кода

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

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

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

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

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

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

В этом примере имя вашего хранилища ключей расширяется до URI хранилища ключей в формате https://<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, выполнив следующие действия:

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 <vault-name> called 'mySecret' with the value 'mySecretPassword' ... done.
Forgetting your secret.
Your secret is ''.
Retrieving your secret from <vault-name>.
Your secret is 'mySecretPassword'.
Deleting your secret from <vault-name> ... done.    
Purging your secret from <vault-name> ... done.

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

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

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