Klientská knihovna certifikátů Azure Key Vault pro Python – verze 4.7.0

  • Článek

Azure Key Vault pomáhá vyřešit následující problémy:

  • Správa certifikátů (tato knihovna) – vytváření, správa a nasazování veřejných a privátních certifikátů SSL/TLS
  • Správa kryptografických klíčů (azure-keyvault-keys) – vytváření, ukládání a řízení přístupu ke klíčům používaným k šifrování dat
  • Správa tajných kódů (azure-keyvault-secrets) – bezpečné ukládání a řízení přístupu k tokenům, heslům, certifikátům, klíčům rozhraní API a dalším tajným klíčům
  • Správa trezoru (azure-keyvault-administration) – řízení přístupu na základě role (RBAC) a možnosti zálohování a obnovení na úrovni trezoru

Zdrojový kód | Balíček (PyPI) | Balíček (Conda) | Referenční dokumentace k | rozhraní API Dokumentace k | produktu Vzorky

Právní omezení

Podpora balíčků Azure SDK Python pro Python 2.7 skončila 1. ledna 2022. Další informace a dotazy najdete v tématu https://github.com/Azure/azure-sdk-for-python/issues/20691. K použití tohoto balíčku se vyžaduje Python 3.7 nebo novější. Další podrobnosti najdete v tématu Věnovaném zásadám podpory verzí sady Azure SDK pro Python.

Začínáme

Instalace balíčku

Nainstalujte azure-keyvault-certificates a azure-identity pomocí pipu:

pip install azure-keyvault-certificates azure-identity

azure-identity se používá pro ověřování Azure Active Directory, jak je znázorněno níže.

Požadavky

Ověření klienta

K interakci se službou Azure Key Vault budete potřebovat instanci CertificateClient, adresu URL trezoru a objekt přihlašovacích údajů. Tento dokument ukazuje použití DefaultAzureCredential, které je vhodné pro většinu scénářů, včetně místních vývojových a produkčních prostředí. Pro ověřování v produkčních prostředích doporučujeme používat spravovanou identitu .

Další informace o dalších metodách ověřování a jejich odpovídajících typech přihlašovacích údajů najdete v dokumentaci azure-identity .

Vytvoření klienta

Po konfiguraci prostředí pro DefaultAzureCredential pro použití vhodné metody ověřování můžete následujícím způsobem vytvořit klienta certifikátu (hodnotu nahraďte VAULT_URL adresou URL trezoru):

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

POZNÁMKA: V případě asynchronního klienta místo toho importujte azure.keyvault.certificates.aio.CertificateClient

Klíčové koncepty

CertificateClient

Pomocí CertificateClient můžete získat certifikáty z trezoru, vytvářet nové certifikáty a nové verze existujících certifikátů, aktualizovat metadata certifikátů a odstraňovat certifikáty. Můžete také spravovat vystavitele certifikátů, kontakty a zásady správy certifikátů. To je znázorněno v následujících příkladech .

Příklady

Tato část obsahuje fragmenty kódu, které pokrývají běžné úlohy:

Vytvoření certifikátu

begin_create_certificate vytvoří certifikát, který se uloží do Key Vault Azure. Pokud již existuje certifikát se stejným názvem, vytvoří se nová verze certifikátu. Před vytvořením certifikátu můžete pro certifikát vytvořit zásadu správy nebo se použije naše výchozí zásada. Tato metoda vrátí dlouho běžící operaci 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())

Pokud chcete zkontrolovat stav vytvoření certifikátu, můžete zavolat status() na poller nebo get_certificate_operation s názvem certifikátu.

Načtení certifikátu

get_certificate načte nejnovější verzi certifikátu dříve uloženého v 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 načte konkrétní verzi certifikátu.

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)

Aktualizace vlastností existujícího certifikátu

update_certificate_properties aktualizuje certifikát dříve uložený v 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)

Odstranění certifikátu

begin_delete_certificate žádosti Key Vault odstranit certifikát a vrátit poller, který vám umožní počkat na dokončení odstranění. Čekání je užitečné, když je v trezoru povolené obnovitelné odstranění a chcete certifikát co nejdříve vymazat (trvale odstranit). Pokud je obnovitelné odstranění zakázané, begin_delete_certificate je samo trvalé.

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)

Výpis vlastností certifikátů

list_properties_of_certificates seznam vlastností všech certifikátů v zadaném 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)

Asynchronní operace

Tato knihovna obsahuje kompletní sadu asynchronních rozhraní API. Abyste je mohli používat, musíte nejprve nainstalovat asynchronní přenos, například aiohttp. Další informace najdete v dokumentaci k azure-core .

Asynchronní klienti a přihlašovací údaje by se měli zavřít, když už nejsou potřeba. Tyto objekty jsou asynchronní kontextové manažery a definují asynchronní close metody. Příklad:

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

Asynchronní vytvoření certifikátu

create_certificate vytvoří certifikát, který se uloží do Key Vault Azure. Pokud již existuje certifikát se stejným názvem, vytvoří se nová verze certifikátu. Před vytvořením certifikátu můžete pro certifikát vytvořit zásadu správy nebo se použije naše výchozí zásada. Čekání create_certificate vrátí vytvořený certifikát, pokud je vytvoření úspěšné, a CertificateOperation , pokud není.

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)

Asynchronní výpis vlastností certifikátů

list_properties_of_certificates seznam všech vlastností certifikátů v trezoru 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)

Řešení potíží

azure-keyvault-certificates Podrobnosti o tom, jak diagnostikovat různé scénáře selhání, najdete v průvodci odstraňováním potíží.

Obecné

Key Vault klienti vyvolávají výjimky definované v azure-core. Pokud se například pokusíte získat klíč, který v trezoru neexistuje, CertificateClient vyvolá chybu 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)

protokolování

Tato knihovna používá pro protokolování standardní knihovnu protokolování . Základní informace o relacích HTTP (adresy URL, hlavičky atd.) se protokolují na úrovni INFO.

Podrobné protokolování úrovně LADĚNÍ, včetně těl požadavků/odpovědí a nereagovaných hlaviček, je možné povolit na klientovi s 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
)

Protokolování trasování sítě je také možné povolit pro libovolnou jednu operaci:

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

Další kroky

V úložišti Azure SDK pro Python Na GitHubu je k dispozici několik ukázek. Tyto ukázky poskytují příklad kódu pro další scénáře Key Vault: | Soubor | Popis | |-------------|-------------| | hello_world.py (asynchronní verze) | vytvoření, získání, aktualizace nebo odstranění certifikátů | | backup_restore_operations.py (asynchronní verze) | zálohování a obnovení certifikátů | | import_certificate.py (asynchronní verze) | import certifikátů ve formátu PKCS#12 (PFX) a PEM do Key Vault | | list_operations.py (asynchronní verze) | list certificate | | recover_purge_operations.py (asynchronní verze) | obnovení a vymazání certifikátů | | issuers.py (asynchronní verze) | správa vystavitelů certifikátů | | contacts.py (asynchronní verze) | správa kontaktů certifikátů | | parse_certificate.py (asynchronní verze) | extrakce privátního klíče certifikátu |

Další dokumentace

Rozsáhlejší dokumentaci k Azure Key Vault najdete v referenční dokumentaci k rozhraní API.

Přispívání

Tento projekt vítá příspěvky a návrhy. Většina příspěvků vyžaduje souhlas s licenční smlouvou s přispěvatelem (CLA), která stanoví, že máte právo udělit nám práva k používání vašeho příspěvku a skutečně tak činíte. Podrobnosti najdete tady: https://cla.microsoft.com

Při odesílání žádosti o přijetí změn robot CLA automaticky určí, jestli je potřeba poskytnout smlouvu CLA, a příslušným způsobem žádost o přijetí změn upraví (např. přidáním jmenovky nebo komentáře). Stačí postupovat podle pokynů robota. Pro všechna úložiště používající naši smlouvu CLA to stačí udělat jenom jednou.

Tento projekt přijal pravidla chování pro Microsoft Open Source. Další informace najdete v nejčastějších dotazech k pravidlům chování. V případě jakýchkoli dotazů nebo připomínek kontaktujte opencode@microsoft.com.

Imprese