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

Azure Key Vault — это облачная служба, которая обеспечивает безопасное хранение секретов, таких как пароли и строки подключения к базе данных.

Клиентская библиотека секретов Key Vault Azure позволяет безопасно хранить маркеры, пароли, ключи API и другие секреты и управлять ими. Эта библиотека предлагает операции по созданию, извлечению, обновлению, удалению, очистке, резервному копированию, восстановлению и перечислению секретов и их версий.

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

Начало работы

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

Установите клиентую библиотеку секретов azure Key Vault для .NET с помощью NuGet:

dotnet add package Azure.Security.KeyVault.Secrets

Предварительные требования

• Подписка Azure.
• Существующая Key Vault Azure. Если вам нужно создать Key Vault Azure, можно использовать портал Azure или Azure CLI.
• Авторизация в существующей Key Vault Azure с помощью RBAC (рекомендуется) или управления доступом.

Если вы используете Azure CLI, замените <your-resource-group-name> и <your-key-vault-name> собственными уникальными именами:

az keyvault create --resource-group <your-resource-group-name> --name <your-key-vault-name>

Аутентификация клиента

Чтобы взаимодействовать со службой azure Key Vault, необходимо создать экземпляр класса SecretClient. Вам потребуется URL-адрес хранилища, который может отображаться как DNS-имя на портале, и учетные данные для создания экземпляра объекта клиента.

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

Чтобы использовать поставщик, показанный DefaultAzureCredential ниже, или другие поставщики учетных данных, предоставляемые вместе с пакетом AZURE SDK, необходимо сначала установить пакет Azure.Identity:

dotnet add package Azure.Identity

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

// Create a new secret client using the default credential from Azure.Identity using environment variables previously set,
// including AZURE_CLIENT_ID, AZURE_CLIENT_SECRET, and AZURE_TENANT_ID.
var client = new SecretClient(vaultUri: new Uri(vaultUrl), credential: new DefaultAzureCredential());

// Create a new secret using the secret client.
KeyVaultSecret secret = client.SetSecret("secret-name", "secret-value");

// Retrieve a secret using the secret client.
secret = client.GetSecret("secret-name");

Основные понятия

KeyVaultSecret

— KeyVaultSecret это фундаментальный ресурс в azure Key Vault. С точки зрения разработчика API-интерфейсы Azure Key Vault принимают и возвращают значения секретов в виде строк.

SecretClient

предоставляет SecretClient синхронные и асинхронные операции в пакете SDK, позволяя выбирать клиент в зависимости от варианта использования приложения. После инициализации SecretClientможно взаимодействовать с секретами в Azure Key Vault.

Потокобезопасность

Мы гарантируем, что все методы экземпляра клиента являются потокобезопасны и независимы друг от друга (руководство). Это гарантирует, что рекомендация по повторному использованию экземпляров клиента всегда будет безопасной, даже в разных потоках.

Дополнительные понятия

Параметры | клиента Доступ к ответу | Длительные операции | Обработка сбоев | Диагностики | Насмешливый | Время существования клиента

Примеры

Пакет Azure.Security.KeyVault.Secrets поддерживает синхронные и асинхронные API.

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

Примеры синхронизации

• Создание секрета
• Получение секрета
• Обновление существующего секрета
• Удаление секрета
• Удаление и очистка секрета
• Список секретов

Примеры асинхронных сценариев

• Асинхронное создание секрета
• Асинхронный список секретов
• Асинхронное удаление секрета

Создание секрета

SetSecretсоздает объект для KeyVaultSecret хранения в Key Vault Azure. Если секрет с таким именем уже существует, создается новая версия секрета.

KeyVaultSecret secret = client.SetSecret("secret-name", "secret-value");

Console.WriteLine(secret.Name);
Console.WriteLine(secret.Value);
Console.WriteLine(secret.Properties.Version);
Console.WriteLine(secret.Properties.Enabled);

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

GetSecretизвлекает секрет, ранее сохраненный в Key Vault Azure.

KeyVaultSecret secret = client.GetSecret("secret-name");

Console.WriteLine(secret.Name);
Console.WriteLine(secret.Value);

Обновление существующего секрета

UpdateSecretPropertiesобновляет секрет, ранее сохраненный в Key Vault Azure. Обновляются только атрибуты секрета. Чтобы обновить значение, вызовите SecretClient.SetSecret для секрета с тем же именем.

KeyVaultSecret secret = client.GetSecret("secret-name");

// Clients may specify the content type of a secret to assist in interpreting the secret data when its retrieved.
secret.Properties.ContentType = "text/plain";

// You can specify additional application-specific metadata in the form of tags.
secret.Properties.Tags["foo"] = "updated tag";

SecretProperties updatedSecretProperties = client.UpdateSecretProperties(secret.Properties);

Console.WriteLine(updatedSecretProperties.Name);
Console.WriteLine(updatedSecretProperties.Version);
Console.WriteLine(updatedSecretProperties.ContentType);

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

StartDeleteSecretзапускает длительную операцию удаления секрета, ранее хранящегося в Key Vault Azure. Секрет можно получить немедленно, не дожидаясь завершения операции. Если обратимое удаление не включено для Key Vault Azure, эта операция безвозвратно удаляет секрет.

DeleteSecretOperation operation = client.StartDeleteSecret("secret-name");

DeletedSecret secret = operation.Value;
Console.WriteLine(secret.Name);
Console.WriteLine(secret.Value);

Удаление и очистка секрета

Прежде чем пытаться очистить или восстановить секрет, необходимо дождаться завершения длительной операции. Это можно сделать, вызвав UpdateStatus в цикле, как показано ниже:

DeleteSecretOperation operation = client.StartDeleteSecret("secret-name");

// You only need to wait for completion if you want to purge or recover the secret.
// You should call `UpdateStatus` in another thread or after doing additional work like pumping messages.
while (!operation.HasCompleted)
{
    Thread.Sleep(2000);

    operation.UpdateStatus();
}

DeletedSecret secret = operation.Value;
client.PurgeDeletedSecret(secret.Name);

получение списка секретов;

В этом примере перечислены все секреты в указанном Key Vault Azure. Значение не возвращается при перечислении всех секретов. Для получения значения потребуется вызвать метод SecretClient.GetSecret .

Pageable<SecretProperties> allSecrets = client.GetPropertiesOfSecrets();

foreach (SecretProperties secretProperties in allSecrets)
{
    Console.WriteLine(secretProperties.Name);
}

Асинхронное создание секрета

Асинхронные API идентичны своим синхронным аналогам, но возвращают с типичным суффиксом TaskAsync для асинхронных методов и возвращают .

В этом примере создается секрет в Key Vault Azure с указанными необязательными аргументами.

KeyVaultSecret secret = await client.SetSecretAsync("secret-name", "secret-value");

Console.WriteLine(secret.Name);
Console.WriteLine(secret.Value);

Асинхронный список секретов

Перечисление секретов не зависит от ожидания GetPropertiesOfSecretsAsync метода , но возвращает AsyncPageable<SecretProperties> объект , который можно использовать с оператором await foreach :

AsyncPageable<SecretProperties> allSecrets = client.GetPropertiesOfSecretsAsync();

await foreach (SecretProperties secretProperties in allSecrets)
{
    Console.WriteLine(secretProperties.Name);
}

Асинхронное удаление секрета

При асинхронном удалении секрета перед его очисткой можно ожидать WaitForCompletionAsync выполнения метода в операции. По умолчанию этот цикл выполняется бесконечно, но его можно отменить, передав .CancellationToken

DeleteSecretOperation operation = await client.StartDeleteSecretAsync("secret-name");

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

DeletedSecret secret = operation.Value;
await client.PurgeDeletedSecretAsync(secret.Name);

Устранение неполадок

Дополнительные сведения о диагностике различных сценариев сбоев см. в нашем руководстве по устранению неполадок .

Общее

При взаимодействии с клиентской библиотекой секретов Azure Key Vault с помощью пакета SDK для .NET ошибки, возвращаемые службой, соответствуют тем же кодам состояния HTTP, возвращенным для запросов REST API.

Например, при попытке получить секрет, который не существует в Key Vault Azure, 404 возвращается ошибка, указывающая Not Foundна .

try
{
    KeyVaultSecret secret = client.GetSecret("some_secret");
}
catch (RequestFailedException ex)
{
    Console.WriteLine(ex.ToString());
}

Вы заметите, что в журнал записываются дополнительные сведения, например идентификатор клиентского запроса операции.

Message:
    Azure.RequestFailedException : Service request failed.
    Status: 404 (Not Found)
Content:
    {"error":{"code":"SecretNotFound","message":"Secret not found: some_secret"}}

Headers:
    Cache-Control: no-cache
    Pragma: no-cache
    Server: Microsoft-IIS/10.0
    x-ms-keyvault-region: westus
    x-ms-request-id: 625f870e-10ea-41e5-8380-282e5cf768f2
    x-ms-keyvault-service-version: 1.1.0.866
    x-ms-keyvault-network-info: addr=131.107.174.199;act_addr_fam=InterNetwork;
    X-AspNet-Version: 4.0.30319
    X-Powered-By: ASP.NET
    Strict-Transport-Security: max-age=31536000;includeSubDomains
    X-Content-Type-Options: nosniff
    Date: Tue, 18 Jun 2019 16:02:11 GMT
    Content-Length: 75
    Content-Type: application/json; charset=utf-8
    Expires: -1

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

В этом репозитории GitHub доступно несколько примеров клиентской библиотеки секретов Azure Key Vault. В этих примерах приведен пример кода для дополнительных сценариев, часто встречающихся при работе с Azure Key Vault:

• Sample1_HelloWorld.md — для работы с Key Vault Azure, в том числе:

  • Создание секрета
  • Получение существующего секрета
  • Обновление существующего секрета
  • Удаление секрета

• Sample2_BackupAndRestore.md — содержит фрагменты кода, работающие с секретами azure Key Vault, в том числе:

  • Резервное копирование и восстановление секрета

• Sample3_GetSecrets.md — пример кода для работы с секретами azure Key Vault, в том числе:

  • Создание секретов
  • Вывод списка всех секретов в Key Vault
  • Обновление секретов в Key Vault
  • Вывод списка версий указанного секрета
  • Удаление секретов из Key Vault
  • Вывод списка удаленных секретов в Key Vault

Дополнительная документация

• Более подробную документацию по azure Key Vault см. в справочной документации по API.
• Сведения о клиентской библиотеке ключей см. в разделе Клиентская библиотека ключей.
• Сведения о клиентской библиотеке сертификатов см. в разделе Клиентская библиотека сертификатов.

Участие

Дополнительные сведения о создании, тестировании и участии в этих библиотеках см. в CONTRIBUTING.md .

На этом проекте приветствуются публикации и предложения. Для участия в большинстве процессов по разработке документации необходимо принять лицензионное соглашение участника (CLA), в котором указывается, что вы предоставляете нам права на использование ваших публикаций. Для получения подробных сведений посетите веб-страницу https://cla.microsoft.com.

При отправке запроса на включение внесенных изменений CLA-бот автоматически определит необходимость предоставления соглашения CLA и соответствующего оформления запроса на включение внесенных изменений (например, добавление метки, комментария). Просто следуйте инструкциям бота. Будет достаточно выполнить их один раз для всех репозиториев, поддерживающих соглашение CLA.

В рамках этого проекта действуют правила поведения в отношении продуктов с открытым исходным кодом Майкрософт. Дополнительные сведения см. в разделе часто задаваемых вопросов о правилах поведения или обратитесь к opencode@microsoft.com с любыми дополнительными вопросами или комментариями.