Biblioteka klienta azure Key Vault Administration dla języka Python — wersja 4.3.0

Uwaga: Biblioteka administracyjna działa tylko z zarządzanym modułem HSM — funkcje przeznaczone dla Key Vault zakończy się niepowodzeniem.

Usługa Azure Key Vault pomaga rozwiązać następujące problemy:

• Administrowanie magazynem (ta biblioteka) — kontrola dostępu oparta na rolach (RBAC) oraz opcje tworzenia kopii zapasowych i przywracania na poziomie magazynu
• Zarządzanie kluczami kryptograficznymi (azure-keyvault-keys) — tworzenie, przechowywanie i kontrolowanie dostępu do kluczy używanych do szyfrowania danych
• Zarządzanie wpisami tajnymi (azure-keyvault-secrets) — bezpieczne przechowywanie i kontrolowanie dostępu do tokenów, haseł, certyfikatów, kluczy interfejsu API i innych wpisów tajnych
• Zarządzanie certyfikatami (azure-keyvault-certificates) — tworzenie i wdrażanie publicznych i prywatnych certyfikatów SSL/TLS oraz zarządzanie nimi

Kod | źródłowy Pakiet (PyPI) | Pakiet (Conda) | Dokumentacja referencyjna interfejsu | API Dokumentacja | produktu Próbki

Zrzeczenie odpowiedzialności

Obsługa pakietów języka Python dla zestawu Azure SDK dla języka Python 2.7 zakończyła się 1 stycznia 2022 r. Aby uzyskać więcej informacji i pytań, zobacz https://github.com/Azure/azure-sdk-for-python/issues/20691.Python 3.7 lub nowszy jest wymagany do korzystania z tego pakietu. Aby uzyskać więcej informacji, zapoznaj się z zasadami obsługi wersji zestawu Azure SDK dla języka Python.

Wprowadzenie

Instalowanie pakietów

Zainstaluj usługę azure-keyvault-administration i azure-identity za pomocą narzędzia pip:

pip install azure-keyvault-administration azure-identity

Usługa azure-identity jest używana do uwierzytelniania usługi Azure Active Directory, jak pokazano poniżej.

Wymagania wstępne

• Subskrypcja platformy Azure
• Środowisko Python w wersji 3.7 lub nowszej
• Istniejący Key Vault zarządzany moduł HSM. Jeśli musisz go utworzyć, możesz to zrobić przy użyciu interfejsu wiersza polecenia platformy Azure, wykonując kroki opisane w tym dokumencie.

Uwierzytelnianie klienta

Aby wchodzić w interakcje z usługą Azure Key Vault, potrzebne będzie wystąpienie klasy KeyVaultAccessControlClient lub KeyVaultBackupClient, a także adres URL magazynu (który może być widoczny jako "Nazwa DNS" w witrynie Azure Portal) i obiekt poświadczeń. W tym dokumencie przedstawiono użycie elementu DefaultAzureCredential, który jest odpowiedni dla większości scenariuszy, w tym lokalnych środowisk programistycznych i produkcyjnych. Zalecamy używanie tożsamości zarządzanej do uwierzytelniania w środowiskach produkcyjnych.

Zobacz dokumentację azure-identity , aby uzyskać więcej informacji na temat innych metod uwierzytelniania i odpowiadających im typów poświadczeń.

Tworzenie obiektu KeyVaultAccessControlClient

Po skonfigurowaniu środowiska domyślnegoAzureCredential do używania odpowiedniej metody uwierzytelniania można wykonać następujące czynności, aby utworzyć klienta kontroli dostępu (zastępując wartość vault_url adresem URL zarządzanego modułu 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
)

UWAGA: W przypadku klienta asynchronicznego zaimportuj azure.keyvault.administration.aioelement "s KeyVaultAccessControlClient ".

Tworzenie elementu KeyVaultBackupClient

Po skonfigurowaniu środowiska domyślnegoAzureCredential do użycia odpowiedniej metody uwierzytelniania można wykonać następujące czynności, aby utworzyć klienta kopii zapasowej (zastępując wartość vault_url adresem URL zarządzanego modułu 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
)

UWAGA: W przypadku klienta asynchronicznego zaimportuj azure.keyvault.administration.aioelement "s KeyVaultBackupClient ".

Tworzenie elementu KeyVaultSettingsClient

Po skonfigurowaniu środowiska domyślnegoAzureCredential do użycia odpowiedniej metody uwierzytelniania można wykonać następujące czynności, aby utworzyć klienta ustawień (zastępując wartość vault_url adresem URL zarządzanego modułu 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
)

UWAGA: W przypadku klienta asynchronicznego zaimportuj azure.keyvault.administration.aioelement "s KeyVaultSettingsClient ".

Kluczowe pojęcia

Definicja roli

Definicja roli definiuje operacje, które można wykonać, takie jak odczyt, zapis i usuwanie. Może również definiować operacje wykluczone z dozwolonych operacji.

Definicja roli jest określana jako część przypisania roli.

Przypisanie roli

Przypisanie roli jest skojarzeniem definicji roli z jednostką usługi. Można je tworzyć, wyświetlać, pobierać pojedynczo i usuwać.

KeyVaultAccessControlClient

A KeyVaultAccessControlClient zarządza definicjami ról i przypisaniami ról.

KeyVaultBackupClient

A KeyVaultBackupClient wykonuje pełne kopie zapasowe kluczy, pełne przywracanie kluczy i selektywne przywracanie kluczy.

KeyVaultSettingsClient

Element KeyVaultSettingsClient zarządza ustawieniami zarządzanego konta modułu HSM.

Przykłady

Ta sekcja zawiera fragmenty kodu obejmujące typowe zadania:

• Kontrola dostępu
  • Wyświetlanie listy wszystkich definicji ról
  • Ustawianie, pobieranie i usuwanie definicji roli
  • Wyświetlanie listy wszystkich przypisań ról
  • Tworzenie, pobieranie i usuwanie przypisania roli
• Tworzenie kopii zapasowej i przywracanie
  • Wykonywanie pełnej kopii zapasowej klucza
  • Wykonywanie pełnego przywracania klucza

Wyświetlanie listy wszystkich definicji ról

Wyświetl listę definicji ról dostępnych do przypisania.

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)

Ustawianie, pobieranie i usuwanie definicji roli

set_role_definition można użyć do utworzenia niestandardowej definicji roli lub zaktualizowania istniejącej definicji o określonej nazwie.

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)

Wyświetlanie listy wszystkich przypisań ról

Przed utworzeniem nowego przypisania roli w następnym fragmencie kodu wyświetl listę wszystkich bieżących przypisań ról:

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)

Tworzenie, pobieranie i usuwanie przypisania roli

Przypisywanie roli do jednostki usługi. Będzie to wymagało identyfikatora definicji roli i identyfikatora obiektu jednostki usługi. Możesz użyć identyfikatora z pobranej listy definicji ról dla poprzedniego i przypisania principal_id z listy pobranej w powyższym fragmencie kodu .

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)

Wykonywanie pełnej kopii zapasowej klucza

Tworzenie kopii zapasowej całej kolekcji kluczy. Magazyn zapasowy dla pełnych kopii zapasowych kluczy jest kontenerem magazynu obiektów blob przy użyciu uwierzytelniania za pomocą sygnatury dostępu współdzielonego.

Aby uzyskać więcej informacji na temat tworzenia tokenu SAS przy użyciu narzędzia BlobServiceClient, zobacz przykład tutaj. Alternatywnie można wygenerować token SAS w Eksplorator usługi Storage

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)

Wykonywanie pełnego przywracania klucza

Przywróć całą kolekcję kluczy z kopii zapasowej. Źródłem danych pełnego przywracania klucza jest obiekt blob magazynu dostępny przy użyciu uwierzytelniania za pomocą sygnatury dostępu współdzielonego. Będziesz również potrzebować elementu azure_storage_blob_container_uri z powyższego fragmentu kodu.

Aby uzyskać więcej informacji na temat tworzenia tokenu SAS przy użyciu narzędzia BlobServiceClient, zobacz przykład tutaj. Alternatywnie można wygenerować token SAS w Eksplorator usługi Storage

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()

Rozwiązywanie problemów

azure-keyvault-administration Zobacz przewodnik rozwiązywania problemów, aby uzyskać szczegółowe informacje na temat diagnozowania różnych scenariuszy awarii.

Ogólne

Key Vault klienci zgłaszają wyjątki zdefiniowane w środowisku azure-core. Jeśli na przykład próbujesz uzyskać przypisanie roli, które nie istnieje, element KeyVaultAccessControlClient zgłasza błąd 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)

Klienci z biblioteki administracyjnej mogą służyć tylko do wykonywania operacji na zarządzanym module HSM, więc próba wykonania tej czynności w Key Vault zgłosi błąd.

Następne kroki

Kilka przykładów jest dostępnych w repozytorium GitHub zestawu Azure SDK dla języka Python. Te przykłady zawierają przykładowy kod dla dodatkowych scenariuszy Key Vault: | Plik | Opis | |-------------|-------------| | access_control_operations.py | tworzenie/aktualizowanie/usuwanie definicji ról i przypisań ról | | access_control_operations_async.py | tworzenie/aktualizowanie/usuwanie definicji ról i przypisań ról za pomocą klienta asynchronicznego | | backup_restore_operations.py | pełna kopia zapasowa i przywracanie | | backup_restore_operations_async.py | pełna kopia zapasowa i przywracanie za pomocą klienta asynchronicznego | | settings_operations.py | wyświetlanie listy i aktualizowanie ustawień Key Vault | | settings_operations_async.py | wyświetlanie listy i aktualizowanie ustawień Key Vault za pomocą klienta asynchronicznego |

Dodatkowa dokumentacja

Aby uzyskać bardziej obszerną dokumentację dotyczącą usługi Azure Key Vault, zobacz dokumentację referencyjną interfejsu API.

Aby uzyskać bardziej obszerną dokumentację dotyczącą zarządzanego modułu HSM, zobacz dokumentację usługi.

Współtworzenie

W tym projekcie zachęcamy do współtworzenia i zgłaszania sugestii. Współtworzenie w większości przypadków wymaga zgody na umowę licencyjną dotyczącą współautorów (CLA, Contributor License Agreement), zgodnie z którą współautor ma prawo udzielić i faktycznie udziela nam praw do używania wytworzonej przez siebie zawartości. Aby uzyskać szczegółowe informacje, odwiedź stronę https://cla.microsoft.com.

Po przesłaniu żądania ściągnięcia robot CLA automatycznie określi, czy musisz przekazać umowę CLA, i doda odpowiednie informacje do tego żądania (na przykład etykietę czy komentarz). Po prostu postępuj zgodnie z instrukcjami robota. Wystarczy zrobić to raz dla wszystkich repozytoriów, w przypadku których jest używana nasza umowa CLA.

W tym projekcie przyjęto Kodeks postępowania oprogramowania Open Source firmy Microsoft. Aby uzyskać więcej informacji, zobacz artykuł Code of Conduct FAQ (Często zadawane pytania dotyczące kodeksu postępowania). Jeśli będziesz mieć jeszcze jakieś pytania lub komentarze, wyślij wiadomość e-mail na adres opencode@microsoft.com.