Udostępnij za pośrednictwem

Biblioteka klienta usługi Azure Key Vault Secrets dla języka Python — wersja 4.7.0

  • Artykuł

Usługa Azure Key Vault pomaga rozwiązać następujące problemy:

  • Zarządzanie wpisami tajnymi (ta biblioteka) — bezpieczne przechowywanie i kontrolowanie dostępu do tokenów, haseł, certyfikatów, kluczy interfejsu API i innych wpisów tajnych
  • Zarządzanie kluczami kryptograficznymi (azure-keyvault-keys) — tworzenie, przechowywanie i kontrolowanie dostępu do kluczy używanych do szyfrowania danych
  • Zarządzanie certyfikatami (azure-keyvault-certificates) — tworzenie i wdrażanie publicznych i prywatnych certyfikatów SSL/TLS oraz zarządzanie nimi
  • Administrowanie magazynem (azure-keyvault-administration) — kontrola dostępu oparta na rolach (RBAC) oraz opcje tworzenia kopii zapasowych i przywracania na poziomie magazynu

Kod | źródłowy Pakiet (PyPI) | Pakiet (Conda) | Dokumentacja referencyjna interfejsu | API Dokumentacja | produktu Próbki

Zrzeczenie odpowiedzialności

Obsługa pakietów języka Python dla zestawu Azure SDK dla języka Python 2.7 zakończyła się 1 stycznia 2022 r. Aby uzyskać więcej informacji i pytań, zapoznaj się z tematem https://github.com/Azure/azure-sdk-for-python/issues/20691. Do korzystania z tego pakietu jest wymagany język Python w wersji 3.7 lub nowszej. Aby uzyskać więcej informacji, zapoznaj się z zasadami obsługi wersji zestawu Azure SDK dla języka Python.

Wprowadzenie

Instalowanie pakietów

Zainstaluj polecenia azure-keyvault-secrets i azure-identity za pomocą narzędzia pip:

pip install azure-keyvault-secrets azure-identity

Usługa azure-identity jest używana do uwierzytelniania usługi Azure Active Directory, jak pokazano poniżej.

Wymagania wstępne

Uwierzytelnianie klienta

Aby wchodzić w interakcje z usługą Azure Key Vault, potrzebne będzie wystąpienie obiektu SecretClient, a także adres URL magazynu i obiekt poświadczeń. W tym dokumencie przedstawiono użycie elementu DefaultAzureCredential, który jest odpowiedni dla większości scenariuszy, w tym lokalnych środowisk programistycznych i produkcyjnych. Zalecamy używanie tożsamości zarządzanej do uwierzytelniania w środowiskach produkcyjnych.

Zobacz dokumentację azure-identity , aby uzyskać więcej informacji na temat innych metod uwierzytelniania i odpowiadających im typów poświadczeń.

Tworzenie klienta

Po skonfigurowaniu środowiska domyślnegoAzureCredential do użycia odpowiedniej metody uwierzytelniania można wykonać następujące czynności, aby utworzyć klienta wpisu tajnego (zastępując wartość VAULT_URL adresem URL magazynu):

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

UWAGA: W przypadku klienta asynchronicznego zaimportuj azure.keyvault.secrets.aioelement "s SecretClient ".

Kluczowe pojęcia

Wpis tajny

Wpis tajny składa się z wartości wpisu tajnego oraz skojarzonych z nim metadanych i informacji dotyczących zarządzania. Ta biblioteka obsługuje wartości wpisów tajnych jako ciągi, ale usługa Azure Key Vault nie przechowuje ich jako takich. Aby uzyskać więcej informacji o wpisach tajnych i Key Vault sposobie przechowywania ich i zarządzania nimi, zobacz dokumentację Key Vault.

Klasa SecretClient może ustawiać wartości wpisów tajnych w magazynie, aktualizować metadane wpisów tajnych i usuwać wpisy tajne, jak pokazano w poniższych przykładach .

Przykłady

Ta sekcja zawiera fragmenty kodu obejmujące typowe zadania:

Ustawianie wpisu tajnego

set_secret tworzy nowe wpisy tajne i zmienia wartości istniejących wpisów tajnych. Jeśli nie istnieje wpis tajny o podanej nazwie, set_secret tworzy nowy wpis tajny o tej nazwie i podanej wartości. Jeśli podana nazwa jest używana, set_secret tworzy nową wersję tego wpisu tajnego z daną wartością.

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)

Pobieranie wpisu tajnego

get_secret pobiera wpis tajny wcześniej przechowywany w 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)

Aktualizowanie metadanych wpisów tajnych

update_secret_properties aktualizuje metadane wpisu tajnego. Nie może zmienić wartości wpisu tajnego; użyj set_secret , aby ustawić wartość wpisu tajnego.

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)

Usuń klucz tajny

begin_delete_secret żądania Key Vault usunąć wpis tajny, zwracając poller, który pozwala poczekać na zakończenie usuwania. Oczekiwanie jest przydatne, gdy magazyn ma włączone usuwanie nietrwałe i chcesz jak najszybciej przeczyścić (trwale usunąć) wpis tajny. Gdy usuwanie nietrwałe jest wyłączone, begin_delete_secret samo działanie jest trwałe.

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)

Wyświetlanie listy wpisów tajnych

list_properties_of_secrets wyświetla listę właściwości wszystkich wpisów tajnych w magazynie klienta. Ta lista nie zawiera wartości wpisu tajnego.

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)

Asynchroniczny interfejs API

Ta biblioteka zawiera kompletny zestaw asynchronicznych interfejsów API. Aby ich używać, należy najpierw zainstalować transport asynchroniczny, taki jak aiohttp. Aby uzyskać więcej informacji, zobacz dokumentację platformy azure-core .

Klienci asynchroniczne i poświadczenia powinny być zamykane, gdy nie są już potrzebne. Te obiekty są menedżerami kontekstu asynchronicznego i definiują metody asynchroniczne close . Przykład:

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

Asynchronicznie utwórz wpis tajny

set_secret tworzy wpis tajny w Key Vault z określonymi opcjonalnymi argumentami.

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)

Asynchronicznie wyświetlaj listę wpisów tajnych

list_properties_of_secrets wyświetla listę właściwości wszystkich wpisów tajnych w magazynie klienta.

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)

Rozwiązywanie problemów

azure-keyvault-secrets Zobacz przewodnik rozwiązywania problemów, aby uzyskać szczegółowe informacje na temat diagnozowania różnych scenariuszy awarii.

Ogólne

Key Vault klienci zgłaszają wyjątki zdefiniowane w środowisku azure-core. Jeśli na przykład spróbujesz uzyskać klucz, który nie istnieje w magazynie, element SecretClient zgłasza błąd ResourceNotFoundError:

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)

Rejestrowanie

Ta biblioteka używa standardowej biblioteki rejestrowania do rejestrowania. Podstawowe informacje o sesjach HTTP (adresach URL, nagłówkach itp.) są rejestrowane na poziomie INFORMACJI.

Szczegółowe rejestrowanie na poziomie DEBUG, w tym treści żądań/odpowiedzi i nieredagowanych nagłówków, można włączyć na kliencie z argumentem logging_enable :

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 Podobnie można włączyć szczegółowe rejestrowanie dla pojedynczej operacji, nawet jeśli nie jest włączone dla klienta:

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

Następne kroki

Kilka przykładów jest dostępnych w repozytorium GitHub zestawu Azure SDK dla języka Python. Zawierają one przykładowy kod dodatkowych scenariuszy Key Vault: | Plik | Opis | |-------------|-------------| | hello_world.py (wersja asynchroniowa) | tworzenie/pobieranie/aktualizowanie/usuwanie wpisów tajnych | | list_operations.py (wersja asynchroniowa) | podstawowe operacje listy dla wpisów tajnych | | backup_restore_operations.py (wersja asynchroniowa) | tworzenie kopii zapasowych i przywracanie wpisów tajnych | | recover_purge_operations.py (wersja asynchroniowa) | odzyskiwanie i przeczyszczanie wpisów tajnych |

Dodatkowa dokumentacja

Aby uzyskać bardziej obszerną dokumentację dotyczącą usługi Azure Key Vault, zobacz dokumentację referencyjną interfejsu API.

Współtworzenie

W tym projekcie zachęcamy do współtworzenia i zgłaszania sugestii. Współtworzenie w większości przypadków wymaga zgody na umowę licencyjną dotyczącą współautorów (CLA, Contributor License Agreement), zgodnie z którą współautor ma prawo udzielić i faktycznie udziela nam praw do używania wytworzonej przez siebie zawartości. Aby uzyskać szczegółowe informacje, odwiedź stronę https://cla.microsoft.com.

Po przesłaniu żądania ściągnięcia robot CLA automatycznie określi, czy musisz przekazać umowę CLA, i doda odpowiednie informacje do tego żądania (na przykład etykietę czy komentarz). Po prostu postępuj zgodnie z instrukcjami robota. Wystarczy zrobić to raz dla wszystkich repozytoriów, w przypadku których jest używana nasza umowa CLA.

W tym projekcie przyjęto Kodeks postępowania oprogramowania Open Source firmy Microsoft. Aby uzyskać więcej informacji, zobacz artykuł Code of Conduct FAQ (Często zadawane pytania dotyczące kodeksu postępowania). Jeśli będziesz mieć jeszcze jakieś pytania lub komentarze, wyślij wiadomość e-mail na adres opencode@microsoft.com.

Wrażenia