Azure Key Vault Administration-klientbibliotek för Python – version 4.3.0
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
- En Azure-prenumeration
- Python 3.7 eller senare
- En befintlig Key Vault Managed HSM. Om du behöver skapa en kan du göra det med hjälp av Azure CLI genom att följa stegen i det här dokumentet.
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.aio
i stället sKeyVaultAccessControlClient
.
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.aio
i stället sKeyVaultBackupClient
.
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.aio
i stället sKeyVaultSettingsClient
.
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:
- Åtkomstkontroll
- Säkerhetskopiering och återställning
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 BlobServiceClient
finns 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 BlobServiceClient
finns 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-administration
felsö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.
Azure SDK for Python
Feedback
https://aka.ms/ContentUserFeedback.
Kommer snart: Under hela 2024 kommer vi att fasa ut GitHub-problem som feedbackmekanism för innehåll och ersätta det med ett nytt feedbacksystem. Mer information finns i:Skicka och visa feedback för