Share via

Azure Key Vault Administration-klientbibliotek för Python – version 4.3.0

  • Artikel

Observera: Administrationsbiblioteket fungerar bara med Managed HSM – funktioner som riktar sig till en Key Vault misslyckas.

Azure Key Vault kan hjälpa dig att lösa följande problem:

  • Valvadministration (det här biblioteket) – rollbaserad åtkomstkontroll (RBAC) och alternativ för säkerhetskopiering och återställning på valvnivå
  • Hantering av kryptografiska nycklar (azure-keyvault-keys) – skapa, lagra och kontrollera åtkomsten till de nycklar som används för att kryptera dina data
  • Hantering av hemligheter (azure-keyvault-secrets) – lagra och kontrollera åtkomsten till token, lösenord, certifikat, API-nycklar och andra hemligheter på ett säkert sätt
  • Certifikathantering (azure-keyvault-certificates) – skapa, hantera och distribuera offentliga och privata SSL/TLS-certifikat

Källkod | Paket (PyPI) | Paket (Conda) | API-referensdokumentation | Produktdokumentation | Prover

Friskrivning

Stöd för Azure SDK Python-paket för Python 2.7 har upphört den 1 januari 2022. Mer information och frågor finns i https://github.com/Azure/azure-sdk-for-python/issues/20691.Python 3.7 eller senare som krävs för att använda det här paketet. Mer information finns i Supportprincip för Azure SDK för Python-version.

Komma igång

Installera paket

Installera azure-keyvault-administration och azure-identity med pip:

pip install azure-keyvault-administration azure-identity

azure-identity används för Azure Active Directory-autentisering enligt nedan.

Förutsättningar

Autentisera klienten

För att kunna interagera med Azure Key Vault-tjänsten behöver du en instans av antingen en KeyVaultAccessControlClient eller KeyVaultBackupClient, samt en valv-URL (som du kan se som "DNS-namn" i Azure-portalen) och ett autentiseringsobjekt. Det här dokumentet visar hur du använder en DefaultAzureCredential, som är lämplig för de flesta scenarier, inklusive lokala utvecklings- och produktionsmiljöer. Vi rekommenderar att du använder en hanterad identitet för autentisering i produktionsmiljöer.

Mer information om andra autentiseringsmetoder och motsvarande typer av autentiseringsuppgifter finns i dokumentationen om azure-identity .

Skapa en KeyVaultAccessControlClient

När du har konfigurerat din miljö för DefaultAzureCredential för att använda en lämplig autentiseringsmetod kan du göra följande för att skapa en åtkomstkontrollklient (ersätta värdet vault_url för med din hanterade HSM-URL):

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
)

OBSERVERA: För en asynkron klient importerar du azure.keyvault.administration.aioi stället s KeyVaultAccessControlClient .

Skapa en KeyVaultBackupClient

När du har konfigurerat din miljö för DefaultAzureCredential för att använda en lämplig autentiseringsmetod kan du göra följande för att skapa en säkerhetskopieringsklient (ersätta värdet vault_url för med din hanterade HSM-URL):

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
)

OBSERVERA: För en asynkron klient importerar du azure.keyvault.administration.aioi stället s KeyVaultBackupClient .

Skapa en KeyVaultSettingsClient

När du har konfigurerat din miljö för StandardAzureCredential för att använda en lämplig autentiseringsmetod kan du göra följande för att skapa en inställningsklient (ersätta värdet vault_url för med din hanterade HSM-URL):

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
)

OBSERVERA: För en asynkron klient importerar du azure.keyvault.administration.aioi stället s KeyVaultSettingsClient .

Viktiga begrepp

Rolldefinition

En rolldefinition definierar de åtgärder som kan utföras, till exempel läsa, skriva och ta bort. Den kan också definiera de åtgärder som undantas från tillåtna åtgärder.

En rolldefinition anges som en del av en rolltilldelning.

Rolltilldelning

En rolltilldelning är associationen mellan en rolldefinition och ett tjänsthuvudnamn. De kan skapas, visas, hämtas individuellt och tas bort.

KeyVaultAccessControlClient

En KeyVaultAccessControlClient hanterar rolldefinitioner och rolltilldelningar.

KeyVaultBackupClient

A KeyVaultBackupClient utför fullständiga nyckelsäkerhetskopior, fullständiga nyckelåterställningar och selektiva nyckelåterställningar.

KeyVaultSettingsClient

En KeyVaultSettingsClient hanterar hanterade HSM-kontoinställningar.

Exempel

Det här avsnittet innehåller kodfragment som omfattar vanliga uppgifter:

Visa en lista över alla rolldefinitioner

Lista de rolldefinitioner som är tillgängliga för tilldelning.

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)

Ange, hämta och ta bort en rolldefinition

set_role_definition kan användas för att antingen skapa en anpassad rolldefinition eller uppdatera en befintlig definition med det angivna namnet.

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)

Visa en lista över alla rolltilldelningar

Innan du skapar en ny rolltilldelning i nästa kodfragment listar du alla aktuella rolltilldelningar:

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)

Skapa, hämta och ta bort en rolltilldelning

Tilldela en roll till ett huvudnamn för tjänsten. Detta kräver ett rolldefinitions-ID och objekt-ID för tjänstens huvudnamn. Du kan använda ett ID från den hämtade listan med rolldefinitioner för den förstnämnda och en tilldelning från listan som hämtats principal_id i ovanstående kodfragment för den senare.

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)

Utföra en fullständig nyckelsäkerhetskopiering

Säkerhetskopiera hela samlingen med nycklar. Säkerhetskopieringsarkivet för fullständiga nyckelsäkerhetskopior är en bloblagringscontainer med autentisering med signatur för delad åtkomst.

Mer information om hur du skapar en SAS-token med hjälp av BlobServiceClientfinns i exemplet här. Du kan också generera en SAS-token i Storage Explorer

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)

Utföra en fullständig nyckelåterställning

Återställ hela samlingen med nycklar från en säkerhetskopia. Datakällan för en fullständig nyckelåterställning är en lagringsblob som används med autentisering med signatur för delad åtkomst. Du behöver azure_storage_blob_container_uri också kodfragmentet ovan.

Mer information om hur du skapar en SAS-token med hjälp av BlobServiceClientfinns i exemplet här. Du kan också generera en SAS-token i Storage Explorer

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

Felsökning

Mer information om hur du diagnostiserar olika felscenarier finns i azure-keyvault-administrationfelsökningsguiden .

Allmänt

Key Vault klienter skapar undantag som definierats i azure-core. Om du till exempel försöker få en rolltilldelning som inte finns genererar 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)

Klienter från administrationsbiblioteket kan bara användas för att utföra åtgärder på en hanterad HSM, så om du försöker göra det på en Key Vault uppstår ett fel.

Nästa steg

Flera exempel är tillgängliga i Azure SDK för Python GitHub-lagringsplatsen. De här exemplen innehåller exempelkod för ytterligare Key Vault scenarier: | Fil | Beskrivning | |-------------|-------------| | | access_control_operations.py | skapa/uppdatera/ta bort rolldefinitioner och rolltilldelningar | | access_control_operations_async.py | skapa/uppdatera/ta bort rolldefinitioner och rolltilldelningar med en asynkron klient | | backup_restore_operations.py | fullständig säkerhetskopiering och återställning | | | backup_restore_operations_async.py | fullständig säkerhetskopiering och återställning med en asynkron klient | | | settings_operations.py | lista och uppdatera Key Vault inställningar | | | settings_operations_async.py | lista och uppdatera Key Vault inställningar med en asynkron klient |

Ytterligare dokumentation

Mer omfattande dokumentation om Azure Key Vault finns i API-referensdokumentationen.

Mer omfattande dokumentation om Hanterad HSM finns i tjänstdokumentationen.

Bidra

Det här projektet välkomnar bidrag och förslag. Merparten av bidragen kräver att du godkänner ett licensavtal för bidrag, där du deklarerar att du har behörighet att bevilja oss rättigheten att använda ditt bidrag, och att du dessutom uttryckligen gör så. Mer information finns på https://cla.microsoft.com.

När du skickar en pull-förfrågan avgör en CLA-robot automatiskt om du måste tillhandahålla ett licensavtal för bidrag med lämplig PR (t.ex. etikett eller kommentar). Följ bara robotens anvisningar. Du behöver bara göra detta en gång för alla repor som använder vårt licensavtal för bidrag.

Det här projektet använder sig av Microsofts uppförandekod för öppen källkod. Du hittar mer information i Vanliga frågor om uppförandekod eller kontakta opencode@microsoft.com för ytterligare frågor eller kommentarer.

Visningar