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

  • Artykuł

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

  • Zarządzanie certyfikatami (ta biblioteka) — tworzenie i wdrażanie publicznych i prywatnych certyfikatów SSL/TLS oraz zarządzanie nimi
  • Zarządzanie kluczami kryptograficznymi (azure-keyvault-keys) — tworzenie, przechowywanie i kontrolowanie dostępu do kluczy używanych do szyfrowania danych
  • Zarządzanie wpisami tajnymi (azure-keyvault-secrets) — bezpieczne przechowywanie i kontrolowanie dostępu do tokenów, haseł, certyfikatów, kluczy interfejsu API i innych wpisów tajnych
  • 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 pakietu

Zainstaluj polecenie azure-keyvault-certificates i azure-identity za pomocą narzędzia pip:

pip install azure-keyvault-certificates 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 CertificateClient, 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żesz wykonać następujące czynności, aby utworzyć klienta certyfikatu (zastępując wartość VAULT_URL adresem URL magazynu):

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

UWAGA: W przypadku klienta asynchronicznego zaimportuj azure.keyvault.certificates.aioelement "s CertificateClient ".

Kluczowe pojęcia

CertificateClient

Za pomocą klasy CertificateClient można pobierać certyfikaty z magazynu, tworzyć nowe certyfikaty i nowe wersje istniejących certyfikatów, aktualizować metadane certyfikatów i usuwać certyfikaty. Można również zarządzać wystawcami certyfikatów, kontaktami i zasadami zarządzania certyfikatami. Przedstawiono to w poniższych przykładach .

Przykłady

Ta sekcja zawiera fragmenty kodu obejmujące typowe zadania:

Tworzenie certyfikatu

begin_create_certificate tworzy certyfikat do przechowywania w usłudze Azure Key Vault. Jeśli certyfikat o tej samej nazwie już istnieje, zostanie utworzona nowa wersja certyfikatu. Przed utworzeniem certyfikatu można utworzyć zasady zarządzania certyfikatem lub zostaną użyte nasze domyślne zasady. Ta metoda zwraca długotrwałą operację poller.

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())

Jeśli chcesz sprawdzić stan tworzenia certyfikatu, możesz wywołać status() polecenie na serwerze poller lub get_certificate_operation przy użyciu nazwy certyfikatu.

Pobieranie certyfikatu

get_certificate pobiera najnowszą wersję certyfikatu wcześniej przechowywanego w 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 pobiera określoną wersję certyfikatu.

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)

Aktualizowanie właściwości istniejącego certyfikatu

update_certificate_properties aktualizuje certyfikat przechowywany wcześniej w 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)

Usuwanie certyfikatu

begin_delete_certificate żądania Key Vault usunąć certyfikat, 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ąć) certyfikat. Gdy usuwanie nietrwałe jest wyłączone, begin_delete_certificate samo działanie jest trwałe.

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)

Wyświetlanie listy właściwości certyfikatów

list_properties_of_certificates wyświetla listę właściwości wszystkich certyfikatów w określonej 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)

Operacje asynchroniczne

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

Asynchronicznie utwórz certyfikat

create_certificate tworzy certyfikat do przechowywania w usłudze Azure Key Vault. Jeśli certyfikat o tej samej nazwie już istnieje, zostanie utworzona nowa wersja certyfikatu. Przed utworzeniem certyfikatu można utworzyć zasady zarządzania certyfikatem lub zostaną użyte nasze domyślne zasady. Oczekiwanie create_certificate na zwrócenie utworzonego certyfikatu w przypadku pomyślnego utworzenia i certyfikatuOperation , jeśli tak nie jest.

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)

Asynchronicznie lista właściwości certyfikatów

list_properties_of_certificates wyświetla listę wszystkich właściwości certyfikatów w magazynie klienta:

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)

Rozwiązywanie problemów

azure-keyvault-certificates 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 CertificateClient zgłasza błąd ResourceNotFoundError:

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)

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

Rejestrowanie śledzenia sieci można również włączyć dla dowolnej pojedynczej operacji:

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

Następne kroki

Kilka przykładów jest dostępnych w repozytorium GitHub zestawu Azure SDK dla języka Python. Te przykłady zawierają przykładowy kod dla dodatkowych scenariuszy Key Vault: | Plik | Opis | |-------------|-------------| | hello_world.py (wersja asynchroniowa) | tworzenie/pobieranie/aktualizowanie/usuwanie certyfikatów | | backup_restore_operations.py (wersja asynchroniowa) | tworzenie kopii zapasowych i odzyskiwanie certyfikatów | | import_certificate.py (wersja asynchroniowa) | importowanie certyfikatów PKCS#12 (PFX) i PEM w formacie PEM do Key Vault | | list_operations.py (wersja asynchroniowa) | wyświetlanie listy certyfikatów | | recover_purge_operations.py (wersja asynchronizuj) | odzyskiwanie i przeczyszczanie certyfikatów | | issuers.py (wersja asynchroniowa) | zarządzanie wystawcami certyfikatów | | contacts.py (wersja asynchronizuj) | zarządzanie kontaktami certyfikatów | | parse_certificate.py (wersja asynchroniowa) | wyodrębnianie klucza prywatnego certyfikatu |

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