Клиентская библиотека администрирования Key Vault Azure для Python версии 4.3.0

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

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

Установите azure-keyvault-administration и azure-identity с помощью pip:

pip install azure-keyvault-administration azure-identity

Azure-identity используется для проверки подлинности Azure Active Directory, как показано ниже.

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

• Подписка Azure
• Python версии 3.7 или выше
• Существующий Key Vault управляемого модуля HSM. Если вам нужно создать ее, это можно сделать с помощью Azure CLI, выполнив действия, описанные в этом документе.

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

Чтобы взаимодействовать со службой azure Key Vault, вам потребуется экземпляр KeyVaultAccessControlClient или KeyVaultBackupClient, а также URL-адрес хранилища (который может отображаться как DNS-имя на портале Azure) и объект учетных данных. В этом документе демонстрируется использование DefaultAzureCredential, который подходит для большинства сценариев, включая локальные среды разработки и рабочие среды. Мы рекомендуем использовать управляемое удостоверение для проверки подлинности в рабочих средах.

Дополнительные сведения о других методах проверки подлинности и соответствующих типах учетных данных см. в документации по azure-identity .

Создание KeyVaultAccessControlClient

После настройки среды для DefaultAzureCredential для использования подходящего метода проверки подлинности можно создать клиент управления доступом (заменив значение url-адресом управляемого vault_url устройства HSM):

from azure.identity import DefaultAzureCredential
from azure.keyvault.administration import KeyVaultAccessControlClient

credential = DefaultAzureCredential()

client = KeyVaultAccessControlClient(
    vault_url="https://my-managed-hsm-name.managedhsm.azure.net/",
    credential=credential
)

ПРИМЕЧАНИЕ: Вместо этого импортируйте azure.keyvault.administration.aioKeyVaultAccessControlClient для асинхронного клиента.

Создание KeyVaultBackupClient

После настройки среды для DefaultAzureCredential для использования подходящего метода проверки подлинности можно создать клиент резервного копирования (заменив значение vault_url URL-адресом управляемого устройства HSM):

from azure.identity import DefaultAzureCredential
from azure.keyvault.administration import KeyVaultBackupClient

credential = DefaultAzureCredential()

client = KeyVaultBackupClient(
    vault_url="https://my-managed-hsm-name.managedhsm.azure.net/",
    credential=credential
)

ПРИМЕЧАНИЕ: Вместо этого импортируйте azure.keyvault.administration.aioKeyVaultBackupClient для асинхронного клиента.

Создание KeyVaultSettingsClient

После настройки среды для DefaultAzureCredential для использования подходящего метода проверки подлинности можно создать клиент параметров (заменив значение URL-адресом управляемого vault_url устройства HSM):

from azure.identity import DefaultAzureCredential
from azure.keyvault.administration import KeyVaultSettingsClient

credential = DefaultAzureCredential()

client = KeyVaultSettingsClient(
    vault_url="https://my-managed-hsm-name.managedhsm.azure.net/",
    credential=credential
)

ПРИМЕЧАНИЕ: Вместо этого импортируйте azure.keyvault.administration.aioKeyVaultSettingsClient для асинхронного клиента.

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

Определение роли

Определение роли определяет операции, которые можно выполнять, такие как чтение, запись и удаление. Он также может определять операции, которые исключаются из разрешенных операций.

Определение роли указывается как часть назначения роли.

Назначение ролей

Назначение роли — это связь определения роли с субъектом-службой. Их можно создавать, перечислять, получать по отдельности и удалять.

KeyVaultAccessControlClient

Управляет KeyVaultAccessControlClient определениями ролей и назначениями ролей.

KeyVaultBackupClient

Выполняет KeyVaultBackupClient полное резервное копирование ключей, полное восстановление ключей и выборочное восстановление ключей.

KeyVaultSettingsClient

Управляет KeyVaultSettingsClient параметрами учетной записи управляемого устройства HSM.

Примеры

В этом разделе содержатся фрагменты кода, охватывающие распространенные задачи:

• Управление доступом
  • Получение списка всех определений роли
  • Установка, получение и удаление определения роли
  • Вывод списка всех назначений ролей
  • Создание, получение и удаление назначения ролей
• Резервное копирование и восстановление
  • Создание полной резервной копии ключа
  • Выполнение полного восстановления ключа

Получение списка всех определений роли

Список определений ролей, доступных для назначения.

from azure.identity import DefaultAzureCredential
from azure.keyvault.administration import KeyVaultAccessControlClient, KeyVaultRoleScope

credential = DefaultAzureCredential()

client = KeyVaultAccessControlClient(
    vault_url="https://my-managed-hsm-name.managedhsm.azure.net/",
    credential=credential
)

# this will list all role definitions available for assignment
role_definitions = client.list_role_definitions(KeyVaultRoleScope.GLOBAL)

for definition in role_definitions:
    print(definition.id)
    print(definition.role_name)
    print(definition.description)

Установка, получение и удаление определения роли

set_role_definition можно использовать для создания пользовательского определения роли или обновления существующего определения с указанным именем.

import uuid
from azure.identity import DefaultAzureCredential
from azure.keyvault.administration import (
    KeyVaultAccessControlClient,
    KeyVaultDataAction,
    KeyVaultPermission,
    KeyVaultRoleScope
)

credential = DefaultAzureCredential()

client = KeyVaultAccessControlClient(
    vault_url="https://my-managed-hsm-name.managedhsm.azure.net/",
    credential=credential
)

# create a custom role definition
permissions = [KeyVaultPermission(allowed_data_actions=[KeyVaultDataAction.READ_HSM_KEY])]
created_definition = client.set_role_definition(KeyVaultRoleScope.GLOBAL, permissions=permissions)

# update the custom role definition
permissions = [
    KeyVaultPermission(allowed_data_actions=[], denied_data_actions=[KeyVaultDataAction.READ_HSM_KEY])
]
updated_definition = client.set_role_definition(
    KeyVaultRoleScope.GLOBAL, permissions=permissions, role_name=created_definition.name
)

# get the custom role definition
definition = client.get_role_definition(KeyVaultRoleScope.GLOBAL, role_name=definition_name)

# delete the custom role definition
deleted_definition = client.delete_role_definition(KeyVaultRoleScope.GLOBAL, role_name=definition_name)

Вывод списка всех назначений ролей

Перед созданием нового назначения роли в следующем фрагменте выведите список всех текущих назначений ролей:

from azure.identity import DefaultAzureCredential
from azure.keyvault.administration import KeyVaultAccessControlClient, KeyVaultRoleScope

credential = DefaultAzureCredential()

client = KeyVaultAccessControlClient(
    vault_url="https://my-managed-hsm-name.managedhsm.azure.net/",
    credential=credential
)

# this will list all role assignments
role_assignments = client.list_role_assignments(KeyVaultRoleScope.GLOBAL)

for assignment in role_assignments:
    print(assignment.name)
    print(assignment.principal_id)
    print(assignment.role_definition_id)

Создание, получение и удаление назначения ролей

Назначьте роль субъекту-службе. Для этого потребуется идентификатор определения роли и идентификатор объекта субъекта-службы. Вы можете использовать идентификатор из полученного списка определений ролей для первого и назначения principal_id из списка, полученного в приведенном выше фрагменте для второго.

from azure.identity import DefaultAzureCredential
from azure.keyvault.administration import KeyVaultAccessControlClient, KeyVaultRoleScope

credential = DefaultAzureCredential()

client = KeyVaultAccessControlClient(
    vault_url="https://my-managed-hsm-name.managedhsm.azure.net/",
    credential=credential
)

# Replace <role-definition-id> with the id of a definition from the fetched list from an earlier example
role_definition_id = "<role-definition-id>"
# Replace <service-principal-object-id> with the principal_id of an assignment returned from the previous example
principal_id = "<service-principal-object-id>"

# first, let's create the role assignment
role_assignment = client.create_role_assignment(KeyVaultRoleScope.GLOBAL, role_definition_id, principal_id)
print(role_assignment.name)
print(role_assignment.principal_id)
print(role_assignment.role_definition_id)

# now, we get it
role_assignment = client.get_role_assignment(KeyVaultRoleScope.GLOBAL, role_assignment.name)
print(role_assignment.name)
print(role_assignment.principal_id)
print(role_assignment.role_definition_id)

# finally, we delete this role assignment
role_assignment = client.delete_role_assignment(KeyVaultRoleScope.GLOBAL, role_assignment.name)
print(role_assignment.name)
print(role_assignment.principal_id)
print(role_assignment.role_definition_id)

Создание полной резервной копии ключа

Создайте резервную копию всей коллекции ключей. Резервным хранилищем для полных резервных копий ключей является контейнер хранилища BLOB-объектов, использующий проверку подлинности подписанного URL-адреса.

Дополнительные сведения о создании маркера SAS с помощью BlobServiceClientсм. в этом примере. Кроме того, можно создать маркер SAS в Обозреватель службы хранилища

from azure.identity import DefaultAzureCredential
from azure.keyvault.administration import KeyVaultBackupClient

credential = DefaultAzureCredential()
client = KeyVaultBackupClient(vault_url="https://my-managed-hsm-name.managedhsm.azure.net/", credential=credential)

# blob storage container URL, for example https://<account name>.blob.core.windows.net/backup
blob_storage_url = "<your-blob-storage-url>"
sas_token = "<your-sas-token>"  # replace with a sas token to your storage account

# Backup is a long-running operation. The client returns a poller object whose result() method
# blocks until the backup is complete, then returns an object representing the backup operation.
backup_poller = client.begin_backup(blob_storage_url, sas_token)
backup_operation = backup_poller.result()

# this is the Azure Storage Blob URL of the backup
print(backup_operation.folder_url)

Выполнение полного восстановления ключа

Восстановите всю коллекцию ключей из резервной копии. Источником данных для полного восстановления ключа является большой двоичный объект хранилища, доступ к которым осуществляется с помощью проверки подлинности подписанного URL-адреса. Вам также потребуется из azure_storage_blob_container_uriприведенного выше фрагмента.

Дополнительные сведения о создании маркера SAS с помощью BlobServiceClientсм. в этом примере. Кроме того, можно создать маркер SAS в Обозреватель службы хранилища

from azure.identity import DefaultAzureCredential
from azure.keyvault.administration import KeyVaultBackupClient

credential = DefaultAzureCredential()
client = KeyVaultBackupClient(vault_url="https://my-managed-hsm-name.managedhsm.azure.net/", credential=credential)

sas_token = "<your-sas-token>"  # replace with a sas token to your storage account

# URL to a storage blob, for example https://<account name>.blob.core.windows.net/backup/mhsm-account-2020090117323313
blob_url = "<your-blob-url>"

# Restore is a long-running operation. The client returns a poller object whose wait() method
# blocks until the restore is complete.
restore_poller = client.begin_restore(blob_url, sas_token)
restore_poller.wait()

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

azure-keyvault-administration Дополнительные сведения о том, как диагностировать различные сценарии сбоев, см. в руководстве по устранению неполадок.

Общее

Key Vault клиенты вызывают исключения, определенные в azure-core. Например, при попытке получить назначение роли, которое не существует, KeyVaultAccessControlClient вызовет ResourceNotFoundError:

from azure.identity import DefaultAzureCredential
from azure.keyvault.administration import KeyVaultAccessControlClient
from azure.core.exceptions import ResourceNotFoundError

credential = DefaultAzureCredential()
client = KeyVaultAccessControlClient(vault_url="https://my-managed-hsm-name.managedhsm.azure.net/", credential=credential)

try:
    client.get_role_assignment("/", "which-does-not-exist")
except ResourceNotFoundError as e:
    print(e.message)

Клиенты из библиотеки администрирования можно использовать только для выполнения операций с управляемым устройством HSM, поэтому попытка сделать это на Key Vault приведет к ошибке.

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

Несколько примеров доступны в репозитории GitHub пакета Azure SDK для Python. В этих примерах приведен пример кода для дополнительных сценариев Key Vault: | Файл | Описание | |-------------|-------------| | access_control_operations.py | Создание, обновление и удаление определений ролей и назначений ролей | | access_control_operations_async.py | Создание, обновление и удаление определений ролей и назначений ролей с помощью асинхронного клиента | | backup_restore_operations.py | полное резервное копирование и восстановление | | backup_restore_operations_async.py | полное резервное копирование и восстановление с помощью асинхронного клиента | | settings_operations.py | перечисление и обновление параметров Key Vault | settings_operations_async.py | перечисление и обновление параметров Key Vault с помощью асинхронного клиента |

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

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

Более подробную документацию по управляемому устройству HSM см. в документации по службе.

Участие

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

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

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