Biblioteka klienta certyfikatów usługi Azure Key Vault dla języka Python — wersja 4.7.0
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
- Subskrypcja platformy Azure
- Środowisko Python w wersji 3.7 lub nowszej
- Istniejąca Key Vault platformy Azure. Jeśli musisz go utworzyć, możesz to zrobić przy użyciu interfejsu wiersza polecenia platformy Azure, wykonując kroki opisane w tym dokumencie.
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.aio
element "sCertificateClient
".
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
- Pobieranie certyfikatu
- Aktualizowanie właściwości istniejącego certyfikatu
- Usuwanie certyfikatu
- Wyświetlanie listy właściwości certyfikatów
- Operacje asynchroniczne
- Asynchronicznie utwórz certyfikat
- Asynchronicznie lista właściwości certyfikatów
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.
Azure SDK for Python
Opinia
https://aka.ms/ContentUserFeedback.
Dostępne już wkrótce: W 2024 r. będziemy stopniowo wycofywać zgłoszenia z serwisu GitHub jako mechanizm przesyłania opinii na temat zawartości i zastępować go nowym systemem opinii. Aby uzyskać więcej informacji, sprawdź:Prześlij i wyświetl opinię dla