Delen via

Azure Key Vault Keys-clientbibliotheek voor Python - versie 4.8.0

  • Artikel

Met Azure Key Vault kunt u de volgende problemen oplossen:

  • Beheer van cryptografische sleutels (deze bibliotheek): de toegang tot de sleutels die worden gebruikt voor het versleutelen van uw gegevens maken, opslaan en beheren
  • Geheimenbeheer (azure-keyvault-secrets): veilig de toegang tot tokens, wachtwoorden, certificaten, API-sleutels en andere geheimen 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

Het pakket installeren

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

pip install azure-keyvault-keys 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 KeyClient nodig, evenals een kluis-URL en een referentieobject. In dit document wordt het gebruik van een DefaultAzureCredential gedemonstreert, wat geschikt is voor de meeste scenario's, waaronder lokale ontwikkel- 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 sleutelclient 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 = KeyClient(vault_url=VAULT_URL, credential=credential)

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

Belangrijkste concepten

Sleutels

Azure Key Vault kunt RSA- en elliptische curvesleutels maken en opslaan. Beide kunnen optioneel worden beveiligd met hardwarebeveiligingsmodules (HSM's). Azure Key Vault kan ook cryptografische bewerkingen uitvoeren. Zie de documentatie voor Key Vault voor meer informatie over sleutels en ondersteunde bewerkingen en algoritmen.

KeyClient kan sleutels maken in de kluis, bestaande sleutels ophalen uit de kluis, sleutelmetagegevens bijwerken en sleutels verwijderen, zoals wordt weergegeven in de onderstaande voorbeelden .

Voorbeelden

Deze sectie bevat codefragmenten voor algemene taken:

Een sleutel maken

create_rsa_key en create_ec_key respectievelijk RSA- en elliptische curvesleutels in de kluis maken. Als er al een sleutel met dezelfde naam bestaat, wordt er een nieuwe versie van die sleutel gemaakt.

from azure.identity import DefaultAzureCredential
from azure.keyvault.keys import KeyClient

credential = DefaultAzureCredential()

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

# Create an RSA key
rsa_key = key_client.create_rsa_key("rsa-key-name", size=2048)
print(rsa_key.name)
print(rsa_key.key_type)

# Create an elliptic curve key
ec_key = key_client.create_ec_key("ec-key-name", curve="P-256")
print(ec_key.name)
print(ec_key.key_type)

Een sleutel ophalen

get_key haalt een sleutel op die eerder is opgeslagen in de kluis.

from azure.identity import DefaultAzureCredential
from azure.keyvault.keys import KeyClient

credential = DefaultAzureCredential()

key_client = KeyClient(vault_url="https://my-key-vault.vault.azure.net/", credential=credential)
key = key_client.get_key("key-name")
print(key.name)

Een bestaande sleutel bijwerken

update_key_properties werkt de eigenschappen bij van een sleutel die eerder is opgeslagen in de Key Vault.

from azure.identity import DefaultAzureCredential
from azure.keyvault.keys import KeyClient

credential = DefaultAzureCredential()

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

# we will now disable the key for further use
updated_key = key_client.update_key_properties("key-name", enabled=False)

print(updated_key.name)
print(updated_key.properties.enabled)

Een sleutel verwijderen

begin_delete_key vraagt Key Vault een sleutel te verwijderen en retourneert een poller waarmee u kunt wachten tot de verwijdering is voltooid. Wachten is handig wanneer voorlopig verwijderen is ingeschakeld voor de kluis en u de sleutel zo snel mogelijk wilt leegmaken (definitief verwijderen). Wanneer voorlopig verwijderen is uitgeschakeld, begin_delete_key is de functie permanent.

from azure.identity import DefaultAzureCredential
from azure.keyvault.keys import KeyClient

credential = DefaultAzureCredential()

key_client = KeyClient(vault_url="https://my-key-vault.vault.azure.net/", credential=credential)
deleted_key = key_client.begin_delete_key("key-name").result()

print(deleted_key.name)
print(deleted_key.deleted_date)

Automatische sleutelrotatie configureren

met update_key_rotation_policy kunt u automatische sleutelrotatie voor een sleutel configureren door een rotatiebeleid op te geven. Bovendien kunt u met rotate_key een sleutel op aanvraag roteren door een nieuwe versie van de opgegeven sleutel te maken.

from azure.identity import DefaultAzureCredential
from azure.keyvault.keys import KeyClient, KeyRotationLifetimeAction, KeyRotationPolicyAction

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

# Set the key's automated rotation policy to rotate the key 30 days before the key expires
actions = [KeyRotationLifetimeAction(KeyRotationPolicyAction.ROTATE, time_before_expiry="P30D")]
# You may also specify the duration after which the newly rotated key will expire
# In this example, any new key versions will expire after 90 days
updated_policy = key_client.update_key_rotation_policy("key-name", expires_in="P90D", lifetime_actions=actions)

# You can get the current rotation policy for a key with get_key_rotation_policy
current_policy = key_client.get_key_rotation_policy("key-name")

# Finally, you can rotate a key on-demand by creating a new version of the key
rotated_key = key_client.rotate_key("key-name")

Sleutels vermelden

list_properties_of_keys bevat de eigenschappen van alle sleutels in de kluis van de client.

from azure.identity import DefaultAzureCredential
from azure.keyvault.keys import KeyClient

credential = DefaultAzureCredential()

key_client = KeyClient(vault_url="https://my-key-vault.vault.azure.net/", credential=credential)
keys = key_client.list_properties_of_keys()

for key in keys:
    # the list doesn't include values or versions of the keys
    print(key.name)

Cryptografische bewerkingen

CryptographyClient maakt cryptografische bewerkingen mogelijk (versleutelen/ontsleutelen, verpakken/uitpakken, ondertekenen/verifiëren) met behulp van een bepaalde sleutel.

from azure.identity import DefaultAzureCredential
from azure.keyvault.keys import KeyClient
from azure.keyvault.keys.crypto import CryptographyClient, EncryptionAlgorithm

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

key = key_client.get_key("key-name")
crypto_client = CryptographyClient(key, credential=credential)
plaintext = b"plaintext"

result = crypto_client.encrypt(EncryptionAlgorithm.rsa_oaep, plaintext)
decrypted = crypto_client.decrypt(result.algorithm, result.ciphertext)

Zie de pakketdocumentatie voor meer informatie over de cryptografie-API.

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.keys.aio import KeyClient

credential = DefaultAzureCredential()

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

Asynchroon een sleutel maken

create_rsa_key en create_ec_key respectievelijk RSA- en elliptische curvesleutels in de kluis maken. Als er al een sleutel met dezelfde naam bestaat, wordt er een nieuwe versie van de sleutel gemaakt.

from azure.identity.aio import DefaultAzureCredential
from azure.keyvault.keys.aio import KeyClient

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

# Create an RSA key
rsa_key = await key_client.create_rsa_key("rsa-key-name", size=2048)
print(rsa_key.name)
print(rsa_key.key_type)

# Create an elliptic curve key
ec_key = await key_client.create_ec_key("ec-key-name", curve="P-256")
print(ec_key.name)
print(ec_key.key_type)

Sleutels asynchroon weergeven

list_properties_of_keys bevat de eigenschappen van alle sleutels in de kluis van de client.

from azure.identity.aio import DefaultAzureCredential
from azure.keyvault.keys.aio import KeyClient

credential = DefaultAzureCredential()
key_client = KeyClient(vault_url="https://my-key-vault.vault.azure.net/", credential=credential)
keys = key_client.list_properties_of_keys()

async for key in keys:
    print(key.name)

Problemen oplossen

Zie de azure-keyvault-keysgids 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 een sleutel probeert op te halen die niet in de kluis bestaat, genereert KeyClientResourceNotFoundError:

from azure.identity import DefaultAzureCredential
from azure.keyvault.keys import KeyClient
from azure.core.exceptions import ResourceNotFoundError

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

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

Logboekregistratie

Deze bibliotheek maakt gebruik van 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-bewerkte headers, kan worden ingeschakeld op een client met het logging_enable argument:

from azure.identity import DefaultAzureCredential
from azure.keyvault.keys import KeyClient
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 = KeyClient(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:

client.get_key("my-key", 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) | sleutels maken/ophalen/bijwerken/verwijderen | | list_operations.py (asynchrone versie) | basislijstbewerkingen voor sleutels | | backup_restore_operations.py (asynchrone versie) | back-up maken en sleutels herstellen | | recover_purge_operations.py (asynchrone versie) | sleutels herstellen en opschonen | | send_request.py | de send_request clientmethode |

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