Azure Key Vault Secrets-clientbibliotheek voor Python - versie 4.7.0

  • Artikel

Met Azure Key Vault kunt u de volgende problemen oplossen:

  • Geheimenbeheer (deze bibliotheek): veilig de toegang tot tokens, wachtwoorden, certificaten, API-sleutels en andere geheimen opslaan en beheren
  • Cryptografisch sleutelbeheer (azure-keyvault-keys): de toegang tot de sleutels die worden gebruikt voor het versleutelen van uw gegevens maken, opslaan en beheren
  • Certificaatbeheer (azure-keyvault-certificates): openbare en persoonlijke SSL/TLS-certificaten maken, beheren en implementeren
  • Kluisbeheer (azure-keyvault-administration) - op rollen gebaseerd toegangsbeheer (RBAC) en opties voor back-up en herstel op kluisniveau

Broncode | Pakket (PyPI) | Pakket (Conda) | API-referentiedocumentatie | Productdocumentatie | Monsters

Disclaimer

Ondersteuning voor Azure SDK Python-pakketten voor Python 2.7 is beëindigd op 1 januari 2022. Raadpleeg https://github.com/Azure/azure-sdk-for-python/issues/20691voor meer informatie en vragen. Python 3.7 of hoger is vereist voor het gebruik van dit pakket. Raadpleeg het ondersteuningsbeleid voor Azure SDK voor Python-versies voor meer informatie.

Aan de slag

Pakketten installeren

Installeer azure-keyvault-secrets en azure-identity met pip:

pip install azure-keyvault-secrets azure-identity

azure-identity wordt gebruikt voor Azure Active Directory-verificatie, zoals hieronder wordt weergegeven.

Vereisten

De client verifiëren

Als u wilt communiceren met de Azure Key Vault-service, hebt u een exemplaar van een SecretClient nodig, evenals een kluis-URL en een referentieobject. Dit document laat zien hoe u een DefaultAzureCredential gebruikt. Dit is geschikt voor de meeste scenario's, waaronder lokale ontwikkelings- en productieomgevingen. U wordt aangeraden een beheerde identiteit te gebruiken voor verificatie in productieomgevingen.

Zie documentatie over azure-identity voor meer informatie over andere verificatiemethoden en de bijbehorende referentietypen.

Client maken

Nadat u uw omgeving hebt geconfigureerd voor de DefaultAzureCredential om een geschikte verificatiemethode te gebruiken, kunt u het volgende doen om een geheime client te maken (waarbij u de waarde van vervangt door de URL van VAULT_URL uw kluis):

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

OPMERKING: Voor een asynchrone client importeert u azure.keyvault.secrets.aioin plaats daarvan 's SecretClient .

Belangrijkste concepten

Geheim

Een geheim bestaat uit een geheime waarde en de bijbehorende metagegevens en beheerinformatie. Deze bibliotheek verwerkt geheime waarden als tekenreeksen, maar Azure Key Vault slaat ze niet als zodanig op. Zie de documentatie over Key Vault voor meer informatie over geheimen en hoe Key Vault deze opslaat en beheert.

SecretClient kan geheime waarden instellen in de kluis, metagegevens van geheimen bijwerken en geheimen verwijderen, zoals wordt weergegeven in de onderstaande voorbeelden .

Voorbeelden

Deze sectie bevat codefragmenten die betrekking hebben op algemene taken:

Een geheim instellen

set_secret maakt nieuwe geheimen en wijzigt de waarden van bestaande geheimen. Als er geen geheim met de opgegeven naam bestaat, set_secret maakt u een nieuw geheim met die naam en de opgegeven waarde. Als de opgegeven naam in gebruik is, set_secret maakt u een nieuwe versie van dat geheim, met de opgegeven waarde.

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)

Een geheim ophalen

get_secret haalt een geheim op dat eerder is opgeslagen in de 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)

Metagegevens van geheimen bijwerken

update_secret_properties werkt de metagegevens van een geheim bij. De waarde van het geheim kan niet worden gewijzigd; gebruik set_secret om de waarde van een geheim in te stellen.

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)

Een geheim verwijderen

begin_delete_secret aanvragen Key Vault verwijderen van een geheim en retourneert een poller waarmee u kunt wachten totdat de verwijdering is voltooid. Wachten is handig wanneer voor de kluis voorlopig verwijderen is ingeschakeld en u het geheim zo snel mogelijk wilt opschonen (definitief verwijderen). Wanneer voorlopig verwijderen is uitgeschakeld, begin_delete_secret is dit 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)

Geheimen vermelden

list_properties_of_secrets bevat de eigenschappen van alle geheimen in de kluis van de client. Deze lijst bevat geen waarden van het geheim.

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)

Async-API

Deze bibliotheek bevat een volledige set asynchrone API's. Als u deze wilt gebruiken, moet u eerst een asynchroon transport installeren, zoals aiohttp. Zie azure-core-documentatie voor meer informatie.

Asynchrone clients en referenties moeten worden gesloten wanneer ze niet meer nodig zijn. Deze objecten zijn asynchrone contextbeheerders en definiëren asynchrone close methoden. Bijvoorbeeld:

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:
    ...

Asynchroon een geheim maken

set_secret maakt een geheim in de Key Vault met de opgegeven optionele 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)

Geheimen asynchroon weergeven

list_properties_of_secrets bevat de eigenschappen van alle geheimen in de kluis van de client.

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)

Problemen oplossen

Zie de azure-keyvault-secretshandleiding voor probleemoplossing voor meer informatie over het diagnosticeren van verschillende foutscenario's.

Algemeen

Key Vault clients genereren uitzonderingen die zijn gedefinieerd in azure-core. Als u bijvoorbeeld probeert een sleutel op te halen die niet in de kluis bestaat, wordt ResourceNotFoundError door SecretClient gegenereerd:

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)

Logboekregistratie

Deze bibliotheek gebruikt de standaardbibliotheek voor logboekregistratie voor logboekregistratie. Basisinformatie over HTTP-sessies (URL's, headers, enzovoort) wordt geregistreerd op INFO-niveau.

Gedetailleerde logboekregistratie op foutopsporingsniveau, inclusief aanvraag-/antwoordteksten en niet-geredigeerde headers, kan worden ingeschakeld op een client met het logging_enable argument:

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
)

Op dezelfde manier kan logging_enable logboekregistratie voor één bewerking inschakelen, zelfs wanneer dit niet is ingeschakeld voor de client:

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

Volgende stappen

Er zijn verschillende voorbeelden beschikbaar in de GitHub-opslagplaats azure SDK voor Python. Deze bieden voorbeeldcode voor aanvullende Key Vault scenario's: | Bestand | Beschrijving | |-------------|-------------| | hello_world.py (asynchrone versie) | geheimen maken/ophalen/bijwerken/verwijderen | | list_operations.py (asynchrone versie) | basislijstbewerkingen voor geheimen | | backup_restore_operations.py (asynchrone versie) | back-ups maken en geheimen herstellen | | recover_purge_operations.py (asynchrone versie) | geheimen herstellen en opschonen |

Aanvullende documentatie

Zie de API-referentiedocumentatie voor uitgebreidere documentatie over Azure Key Vault.

Bijdragen

Wij verwelkomen bijdragen en suggesties voor dit project. Voor de meeste bijdragen moet u instemmen met een licentieovereenkomst voor bijdragers (CLA: Contributor License Agreement) waarin u verklaart dat u gerechtigd bent ons het recht te geven uw bijdrage te gebruiken, en dat u dit ook doet. Ga naar https://cla.microsoft.com voor meer informatie.

Wanneer u een pull-aanvraag indient, wordt met een CLA-bot automatisch bepaald of u een CLA moet verschaffen en wordt de pull-aanvraag dienovereenkomstig opgemaakt (bijvoorbeeld met een label of commentaar). Volg gewoon de instructies van de bot. U hoeft dit maar eenmaal te doen voor alle repo's waar gebruik wordt gemaakt van onze CLA.

Op dit project is de Microsoft Open Source Code of Conduct (Microsoft Open Source-gedragscode) van toepassing. Raadpleeg de Veelgestelde vragen over de gedragscode voor meer informatie of neem contact op met opencode@microsoft.com als u meer vragen of opmerkingen hebt.

Weergaven