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

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

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

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

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

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

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

dotnet add package Azure.Security.KeyVault.Certificates

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

• Подписка 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, необходимо создать экземпляр класса CertificateClient. Вам потребуется URL-адрес хранилища, который может отображаться как DNS-имя на портале, и учетные данные для создания экземпляра объекта клиента.

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

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

dotnet add package Azure.Identity

Создание CertificateClient

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

// Create a new certificate 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 CertificateClient(vaultUri: new Uri(vaultUrl), credential: new DefaultAzureCredential());

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

KeyVaultCertificate

— KeyVaultCertificate это фундаментальный ресурс в azure Key Vault. Вы будете использовать сертификаты для шифрования и проверки зашифрованных или подписанных данных.

CertificateClient

С помощью CertificateClient можно получать сертификаты из хранилища, создавать новые сертификаты и новые версии существующих сертификатов, обновлять метаданные сертификатов и удалять сертификаты. Вы также можете управлять издателями сертификатов, контактами и политиками управления сертификатами. Это показано в приведенных ниже примерах.

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

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

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

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

Примеры

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

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

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

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

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

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

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

StartCreateCertificateсоздает сертификат для хранения в Key Vault Azure. Если сертификат с таким именем уже существует, создается новая версия сертификата. При создании сертификата пользователь может указать политику, которая управляет временем существования сертификата. Если политика не указана, будет использоваться политика по умолчанию. Операция StartCreateCertificate возвращает .CertificateOperation В следующем примере создается самозаверяющий сертификат с политикой по умолчанию.

// Create a certificate. This starts a long running operation to create and sign the certificate.
CertificateOperation operation = client.StartCreateCertificate("MyCertificate", CertificatePolicy.Default);

// You can await the completion of the create certificate operation.
// You should run UpdateStatus in another thread or do other work like pumping messages between calls.
while (!operation.HasCompleted)
{
    Thread.Sleep(2000);

    operation.UpdateStatus();
}

KeyVaultCertificateWithPolicy certificate = operation.Value;

ПРИМЕЧАНИЕ. В зависимости от издателя сертификата и методов проверки создание и подписание сертификата может занять неопределенное время. Пользователи должны ждать операций с сертификатами только в том случае, если операция может быть достаточно завершена в область приложения, например с самозаверяющими сертификатами или издателями с хорошо известным временем отклика.

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

GetCertificateизвлекает последнюю версию сертификата, хранящегося в Key Vault Azure, а также его CertificatePolicy.

KeyVaultCertificateWithPolicy certificateWithPolicy = client.GetCertificate("MyCertificate");

GetCertificateVersion извлекает определенную версию сертификата в хранилище.

KeyVaultCertificate certificate = client.GetCertificateVersion(certificateWithPolicy.Name, certificateWithPolicy.Properties.Version);

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

UpdateCertificateобновляет сертификат, хранящийся в Key Vault Azure.

CertificateProperties certificateProperties = new CertificateProperties(certificate.Id);
certificateProperties.Tags["key1"] = "value1";

KeyVaultCertificate updated = client.UpdateCertificateProperties(certificateProperties);

Список сертификатов

GetCertificates перечисляет сертификаты в хранилище, возвращая свойства выбранного сертификата. Конфиденциальные поля сертификата не будут возвращены. Для этой операции требуется разрешение certificates/list.

Pageable<CertificateProperties> allCertificates = client.GetPropertiesOfCertificates();

foreach (CertificateProperties certificateProperties in allCertificates)
{
    Console.WriteLine(certificateProperties.Name);
}

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

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

DeleteCertificateOperation operation = client.StartDeleteCertificate("MyCertificate");

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

    operation.UpdateStatus();
}

DeletedCertificate certificate = operation.Value;
client.PurgeDeletedCertificate(certificate.Name);

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

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

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

// Create a certificate. This starts a long running operation to create and sign the certificate.
CertificateOperation operation = await client.StartCreateCertificateAsync("MyCertificate", CertificatePolicy.Default);

// You can await the completion of the create certificate operation.
KeyVaultCertificateWithPolicy certificate = await operation.WaitForCompletionAsync();

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

Вывод сертификата не зависит от ожидания GetPropertiesOfCertificatesAsync метода , но возвращает AsyncPageable<CertificateProperties> объект , который можно использовать с инструкцией await foreach :

AsyncPageable<CertificateProperties> allCertificates = client.GetPropertiesOfCertificatesAsync();

await foreach (CertificateProperties certificateProperties in allCertificates)
{
    Console.WriteLine(certificateProperties.Name);
}

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

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

DeleteCertificateOperation operation = await client.StartDeleteCertificateAsync("MyCertificate");

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

DeletedCertificate certificate = operation.Value;
await client.PurgeDeletedCertificateAsync(certificate.Name);

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

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

Общее

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

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

try
{
    KeyVaultCertificateWithPolicy certificateWithPolicy = client.GetCertificate("SomeCertificate");
}
catch (RequestFailedException ex)
{
    Console.WriteLine(ex.ToString());
}

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

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

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 — для работы с сертификатами azure Key Vault, в том числе:

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

• Sample2_GetCertificates.md — пример кода для работы с сертификатами azure 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 с любыми дополнительными вопросами или комментариями.