Azure Key Vault Secrets-klientbibliotek för Python – version 4.7.0

  • Artikel

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

  • Hantering av hemligheter (det här biblioteket) – lagra och kontrollera åtkomsten till token, lösenord, certifikat, API-nycklar och andra hemligheter på ett säkert sätt
  • Hantering av kryptografiska nycklar (azure-keyvault-keys) – skapa, lagra och kontrollera åtkomsten till de nycklar som används för att kryptera dina data
  • Certifikathantering (azure-keyvault-certificates) – skapa, hantera och distribuera offentliga och privata SSL/TLS-certifikat
  • 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 paket

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

pip install azure-keyvault-secrets azure-identity

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

Förutsättningar

Autentisera klienten

För att interagera med Tjänsten Azure Key Vault behöver du en instans av en SecretClient, 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 hemlig klient (ersätta värdet VAULT_URL för med valvets URL):

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

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

Viktiga begrepp

Hemlighet

En hemlighet består av ett hemligt värde och dess associerade metadata och hanteringsinformation. Det här biblioteket hanterar hemliga värden som strängar, men Azure Key Vault lagrar dem inte som sådana. Mer information om hemligheter och hur Key Vault lagrar och hanterar dem finns i dokumentationen om Key Vault.

SecretClient kan ange hemliga värden i valvet, uppdatera hemliga metadata och ta bort hemligheter, enligt exemplen nedan.

Exempel

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

Ange en hemlighet

set_secret skapar nya hemligheter och ändrar värdena för befintliga hemligheter. Om det inte finns någon hemlighet med det angivna namnet skapas set_secret en ny hemlighet med det namnet och det angivna värdet. Om det angivna namnet används set_secret skapar en ny version av hemligheten med det angivna värdet.

from azure.identity import DefaultAzureCredential
from azure.keyvault.secrets import SecretClient

credential = DefaultAzureCredential()

secret_client = SecretClient(vault_url="https://my-key-vault.vault.azure.net/", credential=credential)
secret = secret_client.set_secret("secret-name", "secret-value")

print(secret.name)
print(secret.value)
print(secret.properties.version)

Hämta en hemlighet

get_secret hämtar en hemlighet som tidigare lagrats i Key Vault.

from azure.identity import DefaultAzureCredential
from azure.keyvault.secrets import SecretClient

credential = DefaultAzureCredential()

secret_client = SecretClient(vault_url="https://my-key-vault.vault.azure.net/", credential=credential)
secret = secret_client.get_secret("secret-name")

print(secret.name)
print(secret.value)

Uppdatera hemliga metadata

update_secret_properties uppdaterar en hemlighets metadata. Det går inte att ändra hemlighetens värde. använd set_secret för att ange en hemlighets värde.

from azure.identity import DefaultAzureCredential
from azure.keyvault.secrets import SecretClient

credential = DefaultAzureCredential()

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

# Clients may specify the content type of a secret to assist in interpreting the secret data when it's retrieved
content_type = "text/plain"

# We will also disable the secret for further use

updated_secret_properties = secret_client.update_secret_properties("secret-name", content_type=content_type, enabled=False)

print(updated_secret_properties.updated_on)
print(updated_secret_properties.content_type)
print(updated_secret_properties.enabled)

Ta bort en hemlighet

begin_delete_secret begäranden Key Vault ta bort en hemlighet 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 hemligheten (permanent ta bort) så snart som möjligt. När mjuk borttagning är inaktiverat begin_delete_secret är sig själv permanent.

from azure.identity import DefaultAzureCredential
from azure.keyvault.secrets import SecretClient

credential = DefaultAzureCredential()

secret_client = SecretClient(vault_url="https://my-key-vault.vault.azure.net/", credential=credential)
deleted_secret = secret_client.begin_delete_secret("secret-name").result()

print(deleted_secret.name)
print(deleted_secret.deleted_date)

Visa en lista över hemligheter

list_properties_of_secrets visar egenskaperna för alla hemligheter i klientens valv. Den här listan innehåller inte hemlighetens värden.

from azure.identity import DefaultAzureCredential
from azure.keyvault.secrets import SecretClient

credential = DefaultAzureCredential()

secret_client = SecretClient(vault_url="https://my-key-vault.vault.azure.net/", credential=credential)
secret_properties = secret_client.list_properties_of_secrets()

for secret_property in secret_properties:
    # the list doesn't include values or versions of the secrets
    print(secret_property.name)

Asynkront API

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.secrets.aio import SecretClient

credential = DefaultAzureCredential()

# call close when the client and credential are no longer needed
client = SecretClient(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 = SecretClient(vault_url="https://my-key-vault.vault.azure.net/", credential=credential)
async with client:
  async with credential:
    ...

Skapa en hemlighet asynkront

set_secret skapar en hemlighet i Key Vault med de angivna valfria argumenten.

from azure.identity.aio import DefaultAzureCredential
from azure.keyvault.secrets.aio import SecretClient

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

secret = await secret_client.set_secret("secret-name", "secret-value")

print(secret.name)
print(secret.value)
print(secret.properties.version)

Lista hemligheter asynkront

list_properties_of_secrets visar egenskaperna för alla hemligheter i klientens valv.

from azure.identity.aio import DefaultAzureCredential
from azure.keyvault.secrets.aio import SecretClient

credential = DefaultAzureCredential()
secret_client = SecretClient(vault_url="https://my-key-vault.vault.azure.net/", credential=credential)
secret_properties = secret_client.list_properties_of_secrets()

async for secret_property in secret_properties:
    # the list doesn't include values or versions of the secrets
    print(secret_property.name)

Felsökning

Mer information om hur du diagnostiserar olika felscenarier finns i azure-keyvault-secretsfelsö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 SecretClientResourceNotFoundError:

from azure.identity import DefaultAzureCredential
from azure.keyvault.secrets import SecretClient
from azure.core.exceptions import ResourceNotFoundError

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

try:
    secret_client.get_secret("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.secrets import SecretClient
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
secret_client = SecretClient(
    vault_url="https://my-key-vault.vault.azure.net/",
    credential=credential,
    logging_enable=True
)

logging_enable På samma sätt kan aktivera detaljerad loggning för en enda åtgärd, även om den inte är aktiverad för klienten:

secret_client.get_secret("my-secret", logging_enable=True)

Nästa steg

Det finns flera exempel i Azure SDK för Python GitHub-lagringsplatsen. Dessa ger exempelkod för ytterligare Key Vault scenarier: | Fil | Beskrivning | |-------------|-------------| | | hello_world.py (asynkron version) | skapa/hämta/uppdatera/ta bort hemligheter | | list_operations.py (asynkron version) | grundläggande liståtgärder för hemligheter | | backup_restore_operations.py (asynkron version) | Säkerhetskopiera och återställa hemligheter | | recover_purge_operations.py (asynkron version) | återställa och rensa hemligheter |

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