Klientská knihovna azure Key Vault Administration pro Python – verze 4.3.0

Poznámka: Knihovna pro správu funguje jenom se spravovaným modulem HSM – funkce cílené na Key Vault selžou.

Azure Key Vault pomáhá vyřešit následující problémy:

• Správa trezoru (tato knihovna) – řízení přístupu na základě role (RBAC) a možnosti zálohování a obnovení na úrovni trezoru
• Správa kryptografických klíčů (azure-keyvault-keys) – vytváření, ukládání a řízení přístupu ke klíčům používaným k šifrování dat
• Správa tajných kódů (azure-keyvault-secrets) – bezpečné ukládání a řízení přístupu k tokenům, heslům, certifikátům, klíčům rozhraní API a dalším tajným klíčům
• Správa certifikátů (azure-keyvault-certificates) – vytváření, správa a nasazování veřejných a privátních certifikátů SSL/TLS

Zdrojový kód | Balíček (PyPI) | Balíček (Conda) | Referenční dokumentace k | rozhraní API Dokumentace k | produktu Vzorky

Právní omezení

Podpora balíčků Azure SDK Python pro Python 2.7 skončila 1. ledna 2022. Další informace a dotazy najdete v tématu https://github.com/Azure/azure-sdk-for-python/issues/20691.Použití tohoto balíčku vyžaduje Python 3.7 nebo novější. Další podrobnosti najdete v tématu Věnovaném zásadám podpory verzí sady Azure SDK pro Python.

Začínáme

Instalace balíčků

Nainstalujte azure-keyvault-administration a azure-identity pomocí pipu:

pip install azure-keyvault-administration azure-identity

azure-identity se používá pro ověřování Azure Active Directory, jak je znázorněno níže.

Požadavky

• Předplatné Azure
• Python 3.7 nebo novější
• Existující Key Vault spravovaný HSM. Pokud ho potřebujete vytvořit, můžete to udělat pomocí Azure CLI podle kroků v tomto dokumentu.

Ověření klienta

Abyste mohli pracovat se službou Azure Key Vault, budete potřebovat instanci KeyVaultAccessControlClient nebo KeyVaultBackupClient a také adresu URL trezoru (která se na webu Azure Portal může zobrazit jako název DNS) a objekt přihlašovacích údajů. Tento dokument ukazuje použití DefaultAzureCredential, které je vhodné pro většinu scénářů, včetně místních vývojových a produkčních prostředí. Pro ověřování v produkčních prostředích doporučujeme používat spravovanou identitu .

Další informace o dalších metodách ověřování a jejich odpovídajících typech přihlašovacích údajů najdete v dokumentaci azure-identity .

Vytvoření KeyVaultAccessControlClient

Po konfiguraci prostředí pro DefaultAzureCredential pro použití vhodné metody ověřování můžete následujícím způsobem vytvořit klienta řízení přístupu (hodnotu nahraďte vault_url adresou URL spravovaného 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
)

POZNÁMKA: V případě asynchronního klienta místo toho importujte azure.keyvault.administration.aio.KeyVaultAccessControlClient

Vytvoření KeyVaultBackupClient

Po konfiguraci prostředí pro DefaultAzureCredential pro použití vhodné metody ověřování můžete následujícím způsobem vytvořit zálohovacího klienta (hodnotu nahraďte vault_url adresou URL spravovaného 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
)

POZNÁMKA: V případě asynchronního klienta místo toho importujte azure.keyvault.administration.aio.KeyVaultBackupClient

Vytvoření KeyVaultSettingsClient

Po konfiguraci prostředí pro DefaultAzureCredential pro použití vhodné metody ověřování můžete následujícím způsobem vytvořit klienta nastavení (hodnotu nahraďte vault_url adresou URL spravovaného 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
)

POZNÁMKA: V případě asynchronního klienta místo toho importujte azure.keyvault.administration.aio.KeyVaultSettingsClient

Klíčové koncepty

Definice role

Definice role definuje operace, které je možné provádět, jako je čtení, zápis a odstranění. Může také definovat operace, které jsou vyloučeny z povolených operací.

Definice role se zadává jako součást přiřazení role.

Přiřazení role

Přiřazení role je přidružení definice role k instančnímu objektu. Je možné je vytvářet, vypisovat, načítat jednotlivě a odstraňovat.

KeyVaultAccessControlClient

A KeyVaultAccessControlClient spravuje definice rolí a přiřazení rolí.

KeyVaultBackupClient

Nástroj KeyVaultBackupClient provádí úplné zálohování klíčů, obnovení úplného klíče a selektivní obnovení klíče.

KeyVaultSettingsClient

A KeyVaultSettingsClient spravuje nastavení spravovaného účtu HSM.

Příklady

Tato část obsahuje fragmenty kódu, které pokrývají běžné úlohy:

• Řízení přístupu
  • Výpis všech definic rolí
  • Nastavení, získání a odstranění definice role
  • Výpis všech přiřazení rolí
  • Vytvoření, získání a odstranění přiřazení role
• Zálohování a obnovení
  • Provedení úplného zálohování klíčů
  • Provedení úplného obnovení klíče

Výpis všech definic rolí

Vypíše definice rolí, které jsou k dispozici pro přiřazení.

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)

Nastavení, získání a odstranění definice role

set_role_definition lze použít buď k vytvoření vlastní definice role, nebo k aktualizaci existující definice se zadaným názvem.

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)

Výpis všech přiřazení rolí

Před vytvořením nového přiřazení role v dalším fragmentu kódu vypište seznam všech aktuálních přiřazení rolí:

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)

Vytvoření, získání a odstranění přiřazení role

Přiřazení role instančnímu objektu To bude vyžadovat ID definice role a ID instančního objektu. Můžete použít ID z načteného seznamu definic rolí pro první a přiřazení principal_id ze seznamu načteného ve výše uvedeném fragmentu kódu pro druhou.

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)

Provedení úplného zálohování klíčů

Zálohujte celou kolekci klíčů. Záložním úložištěm pro úplné zálohy klíčů je kontejner úložiště objektů blob využívající ověřování pomocí sdíleného přístupového podpisu.

Další podrobnosti o vytvoření tokenu SAS pomocí BlobServiceClientnástroje najdete v ukázce zde. Alternativně je možné vygenerovat token SAS v Průzkumník služby 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)

Provedení úplného obnovení klíče

Obnovte celou kolekci klíčů ze zálohy. Zdrojem dat pro úplné obnovení klíče je objekt blob úložiště, ke který se přistupuje pomocí ověřování sdíleného přístupového podpisu. Budete také potřebovat fragment kódu z výše uvedeného fragmentuazure_storage_blob_container_uri kódu.

Další podrobnosti o vytvoření tokenu SAS pomocí BlobServiceClientnástroje najdete v ukázce zde. Alternativně je možné vygenerovat token SAS v Průzkumník služby 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()

Řešení potíží

azure-keyvault-administration Podrobnosti o tom, jak diagnostikovat různé scénáře selhání, najdete v průvodci odstraňováním potíží.

Obecné

Key Vault klienti vyvolávají výjimky definované v azure-core. Pokud se například pokusíte získat přiřazení role, které neexistuje, KeyVaultAccessControlClient vyvolá Chybu 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)

Klienty z knihovny pro správu je možné použít pouze k provádění operací ve spravovaném modulu HSM, takže pokud se o to pokusíte na Key Vault, dojde k chybě.

Další kroky

V úložišti Azure SDK pro Python Na GitHubu je k dispozici několik ukázek. Tyto ukázky poskytují příklad kódu pro další scénáře Key Vault: | Soubor | Popis | |-------------|-------------| | access_control_operations.py | vytvoření, aktualizace nebo odstranění definic rolí a přiřazení rolí | | access_control_operations_async.py | Vytvoření, aktualizace nebo odstranění definic rolí a přiřazení rolí pomocí asynchronního klienta | | backup_restore_operations.py | úplné zálohování a obnovení | | backup_restore_operations_async.py | úplné zálohování a obnovení pomocí asynchronního klienta | | settings_operations.py | nastavení seznamu a aktualizace Key Vault | | settings_operations_async.py | výpis a aktualizace nastavení Key Vault pomocí asynchronního klienta |

Další dokumentace

Rozsáhlejší dokumentaci k Azure Key Vault najdete v referenční dokumentaci k rozhraní API.

Rozsáhlejší dokumentaci ke spravovanému HSM najdete v dokumentaci ke službě.

Přispívání

Tento projekt vítá příspěvky a návrhy. Většina příspěvků vyžaduje souhlas s licenční smlouvou s přispěvatelem (CLA), která stanoví, že máte právo udělit nám práva k používání vašeho příspěvku a skutečně tak činíte. Podrobnosti najdete tady: https://cla.microsoft.com

Při odesílání žádosti o přijetí změn robot CLA automaticky určí, jestli je potřeba poskytnout smlouvu CLA, a příslušným způsobem žádost o přijetí změn upraví (např. přidáním jmenovky nebo komentáře). Stačí postupovat podle pokynů robota. Pro všechna úložiště používající naši smlouvu CLA to stačí udělat jenom jednou.

Tento projekt přijal pravidla chování pro Microsoft Open Source. Další informace najdete v nejčastějších dotazech k pravidlům chování. V případě jakýchkoli dotazů nebo připomínek kontaktujte opencode@microsoft.com.