Клиентская библиотека сертификатов Azure Key Vault для Python версии 4.7.0
Azure Key Vault помогает в решении следующих проблем:
- Управление сертификатами (эта библиотека) — создание, администрирование и развертывание общедоступных и частных сертификатов SSL/TLS
- Управление криптографическими ключами (azure-keyvault-keys) — создание, хранение и управление доступом к ключам, используемым для шифрования данных.
- Управление секретами (azure-keyvault-secrets) — безопасное хранение и контроль доступа к маркерам, паролям, сертификатам, ключам API и другим секретам.
- Администрирование хранилища (azure-keyvault-administration) — управление доступом на основе ролей (RBAC), а также параметры резервного копирования и восстановления на уровне хранилища.
Исходный код | Пакет (PyPI) | Пакет (Conda) | Справочная документация по | API Документация по продукту | Образцы
Заявление об отказе
Поддержка пакетов Python пакета Azure SDK для Python 2.7 завершилась 1 января 2022 г. Дополнительные сведения и вопросы см. в https://github.com/Azure/azure-sdk-for-python/issues/20691разделе . Для использования этого пакета требуется Python 3.7 или более поздней версии. Дополнительные сведения см. в статье Политика поддержки версий Пакета AZURE SDK для Python.
Начало работы
Установка пакета
Установите azure-keyvault-certificates и azure-identity с помощью pip:
pip install azure-keyvault-certificates azure-identity
Azure-identity используется для проверки подлинности Azure Active Directory, как показано ниже.
Предварительные требования
- Подписка Azure
- Python версии 3.7 или выше
- Существующий Key Vault Azure. Если вам нужно создать ее, это можно сделать с помощью Azure CLI, выполнив действия, описанные в этом документе.
Аутентификация клиента
Чтобы взаимодействовать со службой Key Vault Azure, вам потребуется экземпляр CertificateClient, а также URL-адрес хранилища и объект учетных данных. В этом документе демонстрируется использование DefaultAzureCredential, который подходит для большинства сценариев, включая локальные среды разработки и рабочие среды. Мы рекомендуем использовать управляемое удостоверение для проверки подлинности в рабочих средах.
Дополнительные сведения о других методах проверки подлинности и соответствующих типах учетных данных см. в документации по azure-identity .
Создание клиента
После настройки среды для DefaultAzureCredential для использования подходящего метода проверки подлинности можно создать клиент сертификата (заменив значение VAULT_URL URL-адресом хранилища):
VAULT_URL = os.environ["VAULT_URL"]
credential = DefaultAzureCredential()
client = CertificateClient(vault_url=VAULT_URL, credential=credential)
ПРИМЕЧАНИЕ: Вместо этого импортируйте
azure.keyvault.certificates.aioCertificateClientдля асинхронного клиента.
Основные понятия
CertificateClient
С помощью CertificateClient можно получать сертификаты из хранилища, создавать новые сертификаты и новые версии существующих сертификатов, обновлять метаданные сертификатов и удалять сертификаты. Вы также можете управлять издателями сертификатов, контактами и политиками управления сертификатами. Это показано в приведенных ниже примерах .
Примеры
В этом разделе содержатся фрагменты кода, охватывающие распространенные задачи:
- Создание сертификата
- Получение сертификата
- Обновление свойств существующего сертификата
- Удаление сертификата
- Список свойств сертификатов
- Асинхронные операции
- Асинхронное создание сертификата
- Асинхронный список свойств сертификатов
Создание сертификата
begin_create_certificate создает сертификат для хранения в Key Vault Azure. Если сертификат с таким именем уже существует, создается новая версия сертификата. Перед созданием сертификата можно создать политику управления для сертификата или использовать политику по умолчанию. Этот метод возвращает долго выполняющийся опрашиватель операций.
from azure.identity import DefaultAzureCredential
from azure.keyvault.certificates import CertificateClient, CertificatePolicy
credential = DefaultAzureCredential()
certificate_client = CertificateClient(vault_url="https://my-key-vault.vault.azure.net/", credential=credential)
create_certificate_poller = certificate_client.begin_create_certificate(
certificate_name="cert-name", policy=CertificatePolicy.get_default()
)
print(create_certificate_poller.result())
Если вы хотите проверить состояние создания сертификата, можно вызвать status() средство опроса или get_certificate_operation с именем сертификата.
Получение сертификата
get_certificate извлекает последнюю версию сертификата, ранее хранящегося в Key Vault.
from azure.identity import DefaultAzureCredential
from azure.keyvault.certificates import CertificateClient
credential = DefaultAzureCredential()
certificate_client = CertificateClient(vault_url="https://my-key-vault.vault.azure.net/", credential=credential)
certificate = certificate_client.get_certificate("cert-name")
print(certificate.name)
print(certificate.properties.version)
print(certificate.policy.issuer_name)
get_certificate_version извлекает определенную версию сертификата.
from azure.identity import DefaultAzureCredential
from azure.keyvault.certificates import CertificateClient
credential = DefaultAzureCredential()
certificate_client = CertificateClient(vault_url="https://my-key-vault.vault.azure.net/", credential=credential)
certificate = certificate_client.get_certificate_version(certificate_name="cert-name", version="cert-version")
print(certificate.name)
print(certificate.properties.version)
Обновление свойств существующего сертификата
update_certificate_properties обновляет сертификат, ранее сохраненный в Key Vault.
from azure.identity import DefaultAzureCredential
from azure.keyvault.certificates import CertificateClient
credential = DefaultAzureCredential()
certificate_client = CertificateClient(vault_url="https://my-key-vault.vault.azure.net/", credential=credential)
# we will now disable the certificate for further use
updated_certificate= certificate_client.update_certificate_properties(
certificate_name="cert-name", enabled=False
)
print(updated_certificate.name)
print(updated_certificate.properties.enabled)
Удаление сертификата
begin_delete_certificate запросы Key Vault удаления сертификата, возвращая средство опроса, которое позволяет дождаться завершения удаления.
Ожидание полезно, если в хранилище включено обратимое удаление и вы хотите как можно скорее очистить (окончательно удалить) сертификат. Если обратимое удаление отключено, begin_delete_certificate само по себе является постоянным.
from azure.identity import DefaultAzureCredential
from azure.keyvault.certificates import CertificateClient
credential = DefaultAzureCredential()
certificate_client = CertificateClient(vault_url="https://my-key-vault.vault.azure.net/", credential=credential)
deleted_certificate_poller = certificate_client.begin_delete_certificate("cert-name")
deleted_certificate = deleted_certificate_poller.result()
print(deleted_certificate.name)
print(deleted_certificate.deleted_on)
Список свойств сертификатов
list_properties_of_certificates перечисляет свойства всех сертификатов в указанном Key Vault.
from azure.identity import DefaultAzureCredential
from azure.keyvault.certificates import CertificateClient
credential = DefaultAzureCredential()
certificate_client = CertificateClient(vault_url="https://my-key-vault.vault.azure.net/", credential=credential)
certificates = certificate_client.list_properties_of_certificates()
for certificate in certificates:
# this list doesn't include versions of the certificates
print(certificate.name)
Асинхронные операции
Эта библиотека включает полный набор асинхронных API. Чтобы использовать их, необходимо сначала установить асинхронный транспорт, например aiohttp. Дополнительные сведения см. в документации по azure-core .
Асинхронные клиенты и учетные данные должны быть закрыты, если они больше не нужны. Эти объекты являются диспетчерами асинхронного контекста и определяют асинхронные close методы. Пример:
from azure.identity.aio import DefaultAzureCredential
from azure.keyvault.certificates.aio import CertificateClient
credential = DefaultAzureCredential()
# call close when the client and credential are no longer needed
client = CertificateClient(vault_url="https://my-key-vault.vault.azure.net/", credential=credential)
...
await client.close()
await credential.close()
# alternatively, use them as async context managers (contextlib.AsyncExitStack can help)
client = CertificateClient(vault_url="https://my-key-vault.vault.azure.net/", credential=credential)
async with client:
async with credential:
...
Асинхронное создание сертификата
create_certificate создает сертификат для хранения в Key Vault Azure. Если сертификат с таким именем уже существует, создается новая версия сертификата. Перед созданием сертификата можно создать политику управления для сертификата или использовать политику по умолчанию. Ожидание create_certificate возвращает созданный сертификат, если создание выполнено успешно, и CertificateOperation , если это не так.
from azure.identity.aio import DefaultAzureCredential
from azure.keyvault.certificates.aio import CertificateClient
from azure.keyvault.certificates import CertificatePolicy
credential = DefaultAzureCredential()
certificate_client = CertificateClient(vault_url="https://my-key-vault.vault.azure.net/", credential=credential)
create_certificate_result = await certificate_client.create_certificate(
certificate_name="cert-name", policy=CertificatePolicy.get_default()
)
print(create_certificate_result)
Асинхронный список свойств сертификатов
list_properties_of_certificates перечисляет все свойства сертификатов в хранилище клиента:
from azure.identity.aio import DefaultAzureCredential
from azure.keyvault.certificates.aio import CertificateClient
credential = DefaultAzureCredential()
certificate_client = CertificateClient(vault_url="https://my-key-vault.vault.azure.net/", credential=credential)
certificates = certificate_client.list_properties_of_certificates()
async for certificate in certificates:
print(certificate.name)
Устранение неполадок
azure-keyvault-certificates Дополнительные сведения о том, как диагностировать различные сценарии сбоев, см. в руководстве по устранению неполадок.
Общее
Key Vault клиенты вызывают исключения, определенные в azure-core. Например, при попытке получить ключ, который не существует в хранилище, CertificateClient вызовет ResourceNotFoundError:
from azure.identity import DefaultAzureCredential
from azure.keyvault.certificates import CertificateClient
from azure.core.exceptions import ResourceNotFoundError
credential = DefaultAzureCredential()
certificate_client = CertificateClient(vault_url="https://my-key-vault.vault.azure.net/", credential=credential)
try:
certificate_client.get_certificate("which-does-not-exist")
except ResourceNotFoundError as e:
print(e.message)
Ведение журнала
Эта библиотека использует стандартную библиотеку ведения журнала для ведения журнала. Основные сведения о сеансах HTTP (URL-адреса, заголовки и т. д.) регистрируются на уровне INFO.
Подробное ведение журнала на уровне DEBUG, включая тексты запросов и ответов и неотредактированные заголовки, можно включить на клиенте с помощью аргумента logging_enable :
from azure.identity import DefaultAzureCredential
from azure.keyvault.certificates import CertificateClient
import sys
import logging
# Create a logger for the 'azure' SDK
logger = logging.getLogger('azure')
logger.setLevel(logging.DEBUG)
# Configure a console output
handler = logging.StreamHandler(stream=sys.stdout)
logger.addHandler(handler)
credential = DefaultAzureCredential()
# This client will log detailed information about its HTTP sessions, at DEBUG level
client = CertificateClient(
vault_url="https://my-key-vault.vault.azure.net/",
credential=credential,
logging_enable=True
)
Ведение журнала трассировки сети также можно включить для любой отдельной операции:
certificate = certificate_client.get_certificate(certificate_name="cert-name", logging_enable=True)
Дальнейшие действия
Несколько примеров доступны в репозитории GitHub пакета Azure SDK для Python. В этих примерах приведен пример кода для дополнительных сценариев Key Vault: | Файл | Описание | |-------------|-------------| | hello_world.py (асинхронная версия) | Создание, получение, обновление и удаление сертификатов | backup_restore_operations.py (асинхронная версия) | резервное копирование и восстановление сертификатов | | import_certificate.py (асинхронная версия) | импорт сертификатов PKCS#12 (PFX) и PEM в Key Vault | | list_operations.py (асинхронная версия) | список сертификатов | | recover_purge_operations.py (асинхронная версия) | Восстановление и очистка сертификатов | | issuers.py (асинхронная версия) | управление издателями сертификатов | | contacts.py (асинхронная версия) | Управление контактами сертификатов | | parse_certificate.py (асинхронная версия) | извлечение закрытого ключа сертификата |
Дополнительная документация
Более подробную документацию по azure Key Vault см. в справочной документации по API.
Участие
На этом проекте приветствуются публикации и предложения. Для участия в большинстве процессов по разработке документации необходимо принять лицензионное соглашение участника (CLA), в котором указывается, что вы предоставляете нам права на использование ваших публикаций. Для получения подробных сведений посетите веб-страницу https://cla.microsoft.com.
При отправке запроса на включение внесенных изменений CLA-бот автоматически определит необходимость предоставления соглашения CLA и соответствующего оформления запроса на включение внесенных изменений (например, добавление метки, комментария). Просто следуйте инструкциям бота. Будет достаточно выполнить их один раз для всех репозиториев, поддерживающих соглашение CLA.
В рамках этого проекта действуют правила поведения в отношении продуктов с открытым исходным кодом Майкрософт. Дополнительные сведения: Вопросы и ответы по правилам поведения. С любыми другими вопросами или комментариями обращайтесь по адресу opencode@microsoft.com.
Azure SDK for Python
Обратная связь
Ожидается в ближайшее время: в течение 2024 года мы постепенно откажемся от GitHub Issues как механизма обратной связи для контента и заменим его новой системой обратной связи. Дополнительные сведения см. в разделе https://aka.ms/ContentUserFeedback.
Отправить и просмотреть отзыв по