Klientbibliotek för Azure Key Vault-certifikat för Python – version 4.7.0

  • Artikel

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

  • Certifikathantering (det här biblioteket) – skapa, hantera och distribuera offentliga och privata SSL/TLS-certifikat
  • 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
  • Valvadministration (azure-keyvault-administration) – rollbaserad åtkomstkontroll (RBAC) och alternativ för säkerhetskopiering och återställning på valvnivå

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

Friskrivning

Stöd för Azure SDK Python-paket för Python 2.7 upphörde 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 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 paketet

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

pip install azure-keyvault-certificates azure-identity

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

Förutsättningar

Autentisera klienten

För att interagera med Azure Key Vault-tjänsten behöver du en instans av en CertificateClient, samt en valv-URL 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 deras motsvarande typer av autentiseringsuppgifter finns i dokumentationen om azure-identity .

Skapa en klient

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 certifikatklient (ersätta värdet VAULT_URL för med valvets URL):

VAULT_URL = os.environ["VAULT_URL"]
credential = DefaultAzureCredential()
client = CertificateClient(vault_url=VAULT_URL, credential=credential)

OBSERVERA: För en asynkron klient importerar du azure.keyvault.certificates.aiodem CertificateClient i stället.

Viktiga begrepp

CertificateClient

Med en CertificateClient kan du hämta certifikat från valvet, skapa nya certifikat och nya versioner av befintliga certifikat, uppdatera certifikatmetadata och ta bort certifikat. Du kan också hantera certifikatutfärdare, kontakter och hanteringsprinciper för certifikat. Detta illustreras i exemplen nedan.

Exempel

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

Skapa ett certifikat

begin_create_certificate skapar ett certifikat som ska lagras i Azure Key Vault. Om det redan finns ett certifikat med samma namn skapas en ny version av certifikatet. Innan du skapar ett certifikat kan du skapa en hanteringsprincip för certifikatet eller så används vår standardprincip. Den här metoden returnerar en tidskrävande åtgärdspolerare.

from azure.identity import DefaultAzureCredential
from azure.keyvault.certificates import CertificateClient, CertificatePolicy

credential = DefaultAzureCredential()

certificate_client = CertificateClient(vault_url="https://my-key-vault.vault.azure.net/", credential=credential)

create_certificate_poller = certificate_client.begin_create_certificate(
    certificate_name="cert-name", policy=CertificatePolicy.get_default()
)
print(create_certificate_poller.result())

Om du vill kontrollera statusen för att skapa certifikatet kan du anropa status() på pollern eller get_certificate_operation med namnet på certifikatet.

Hämta ett certifikat

get_certificate hämtar den senaste versionen av ett certifikat som tidigare lagrats i Key Vault.

from azure.identity import DefaultAzureCredential
from azure.keyvault.certificates import CertificateClient

credential = DefaultAzureCredential()

certificate_client = CertificateClient(vault_url="https://my-key-vault.vault.azure.net/", credential=credential)

certificate = certificate_client.get_certificate("cert-name")

print(certificate.name)
print(certificate.properties.version)
print(certificate.policy.issuer_name)

get_certificate_version hämtar en specifik version av ett certifikat.

from azure.identity import DefaultAzureCredential
from azure.keyvault.certificates import CertificateClient

credential = DefaultAzureCredential()

certificate_client = CertificateClient(vault_url="https://my-key-vault.vault.azure.net/", credential=credential)
certificate = certificate_client.get_certificate_version(certificate_name="cert-name", version="cert-version")

print(certificate.name)
print(certificate.properties.version)

Uppdatera egenskaper för ett befintligt certifikat

update_certificate_properties uppdaterar ett certifikat som tidigare lagrats i Key Vault.

from azure.identity import DefaultAzureCredential
from azure.keyvault.certificates import CertificateClient

credential = DefaultAzureCredential()

certificate_client = CertificateClient(vault_url="https://my-key-vault.vault.azure.net/", credential=credential)

# we will now disable the certificate for further use
updated_certificate= certificate_client.update_certificate_properties(
    certificate_name="cert-name", enabled=False
)

print(updated_certificate.name)
print(updated_certificate.properties.enabled)

Ta bort ett certifikat

begin_delete_certificate begär Key Vault ta bort ett certifikat och returnerar en poller som gör att du kan vänta tills borttagningen har slutförts. Att vänta är användbart när mjuk borttagning är aktiverat för valvet och du vill rensa certifikatet (permanent ta bort) så snart som möjligt. När mjuk borttagning är inaktiverat begin_delete_certificate är sig själv permanent.

from azure.identity import DefaultAzureCredential
from azure.keyvault.certificates import CertificateClient

credential = DefaultAzureCredential()

certificate_client = CertificateClient(vault_url="https://my-key-vault.vault.azure.net/", credential=credential)

deleted_certificate_poller = certificate_client.begin_delete_certificate("cert-name")

deleted_certificate = deleted_certificate_poller.result()
print(deleted_certificate.name)
print(deleted_certificate.deleted_on)

Lista egenskaper för certifikat

list_properties_of_certificates visar egenskaperna för alla certifikat i den angivna Key Vault.

from azure.identity import DefaultAzureCredential
from azure.keyvault.certificates import CertificateClient

credential = DefaultAzureCredential()

certificate_client = CertificateClient(vault_url="https://my-key-vault.vault.azure.net/", credential=credential)

certificates = certificate_client.list_properties_of_certificates()

for certificate in certificates:
    # this list doesn't include versions of the certificates
    print(certificate.name)

Asynkrona åtgärder

Det här biblioteket innehåller en fullständig uppsättning asynkrona API:er. Om du vill använda dem måste du först installera en asynkron transport, till exempel aiohttp. Mer information finns i azure-core-dokumentationen .

Asynkrona klienter och autentiseringsuppgifter bör stängas när de inte längre behövs. Dessa objekt är asynkrona kontexthanterare och definierar asynkrona close metoder. Exempel:

from azure.identity.aio import DefaultAzureCredential
from azure.keyvault.certificates.aio import CertificateClient

credential = DefaultAzureCredential()

# call close when the client and credential are no longer needed
client = CertificateClient(vault_url="https://my-key-vault.vault.azure.net/", credential=credential)
...
await client.close()
await credential.close()

# alternatively, use them as async context managers (contextlib.AsyncExitStack can help)
client = CertificateClient(vault_url="https://my-key-vault.vault.azure.net/", credential=credential)
async with client:
  async with credential:
    ...

Skapa ett certifikat asynkront

create_certificate skapar ett certifikat som ska lagras i Azure Key Vault. Om det redan finns ett certifikat med samma namn skapas en ny version av certifikatet. Innan du skapar ett certifikat kan du skapa en hanteringsprincip för certifikatet eller så används vår standardprincip. Väntar på create_certificate returnerar det skapade certifikatet om det lyckas och ett CertificateOperation om det inte är det.

from azure.identity.aio import DefaultAzureCredential
from azure.keyvault.certificates.aio import CertificateClient
from azure.keyvault.certificates import CertificatePolicy

credential = DefaultAzureCredential()

certificate_client = CertificateClient(vault_url="https://my-key-vault.vault.azure.net/", credential=credential)

create_certificate_result = await certificate_client.create_certificate(
    certificate_name="cert-name", policy=CertificatePolicy.get_default()
)
print(create_certificate_result)

Lista egenskaper för certifikat asynkront

list_properties_of_certificates visar alla egenskaper för certifikaten i klientens valv:

from azure.identity.aio import DefaultAzureCredential
from azure.keyvault.certificates.aio import CertificateClient

credential = DefaultAzureCredential()

certificate_client = CertificateClient(vault_url="https://my-key-vault.vault.azure.net/", credential=credential)

certificates = certificate_client.list_properties_of_certificates()
async for certificate in certificates:
    print(certificate.name)

Felsökning

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

Allmänt

Key Vault klienter skapar undantag som definierats i azure-core. Om du till exempel försöker hämta en nyckel som inte finns i valvet genererar CertificateClientResourceNotFoundError:

from azure.identity import DefaultAzureCredential
from azure.keyvault.certificates import CertificateClient
from azure.core.exceptions import ResourceNotFoundError

credential = DefaultAzureCredential()
certificate_client = CertificateClient(vault_url="https://my-key-vault.vault.azure.net/", credential=credential)

try:
    certificate_client.get_certificate("which-does-not-exist")
except ResourceNotFoundError as e:
    print(e.message)

Loggning

Det här biblioteket använder standardloggningsbiblioteket för loggning. Grundläggande information om HTTP-sessioner (URL:er, rubriker osv.) loggas på INFO-nivå.

Detaljerad loggning på FELSÖKNINGsnivå, inklusive begärande-/svarskroppar och oredigerade huvuden, kan aktiveras på en klient med logging_enable argumentet :

from azure.identity import DefaultAzureCredential
from azure.keyvault.certificates import CertificateClient
import sys
import logging

# Create a logger for the 'azure' SDK
logger = logging.getLogger('azure')
logger.setLevel(logging.DEBUG)

# Configure a console output
handler = logging.StreamHandler(stream=sys.stdout)
logger.addHandler(handler)

credential = DefaultAzureCredential()

# This client will log detailed information about its HTTP sessions, at DEBUG level
client = CertificateClient(
    vault_url="https://my-key-vault.vault.azure.net/",
    credential=credential,
    logging_enable=True
)

Loggning av nätverksspårning kan också aktiveras för en enskild åtgärd:

certificate = certificate_client.get_certificate(certificate_name="cert-name", logging_enable=True)

Nästa steg

Det finns flera exempel i Azure SDK för Python GitHub-lagringsplatsen. De här exemplen innehåller exempelkod för ytterligare Key Vault scenarier: | Fil | Beskrivning | |-------------|-------------| | | hello_world.py (asynkron version) | skapa/hämta/uppdatera/ta bort certifikat | | backup_restore_operations.py (asynkron version) | Säkerhetskopiera och återställa certifikat | | import_certificate.py (asynkron version) | importera PKCS#12 (PFX) och PEM-formaterade certifikat till Key Vault | | list_operations.py (asynkron version) | lista certifikat | | recover_purge_operations.py (asynkron version) | återställa och rensa certifikat | | issuers.py (asynkron version) | hantera certifikatutfärdare | | contacts.py (asynkron version) | hantera certifikatkontakter | | parse_certificate.py (asynkron version) | extrahera ett certifikats privata nyckel |

Ytterligare dokumentation

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

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