Klientská knihovna Azure Key Vault Secrets pro Python – verze 4.7.0

  • Článek

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

  • Správa tajných kódů (tato knihovna) – 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 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 certifikátů (azure-keyvault-certificates) – vytváření, správa a nasazování veřejných a privátních certifikátů SSL/TLS
  • 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 na .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íčků

Nainstalujte azure-keyvault-secrets a azure-identity pomocí pip:

pip install azure-keyvault-secrets azure-identity

Azure-identity se používá k 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 SecretClient, 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ího vývojového a produkčního 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 k azure-identity .

Vytvoření klienta

Po konfiguraci prostředí pro DefaultAzureCredential tak, aby používalo vhodnou metodu ověřování, můžete následujícím způsobem vytvořit tajného klienta (hodnotu VAULT_URL nahraďte adresou URL vašeho trezoru):

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

POZNÁMKA: V případě asynchronního klienta místo toho proveďte SecretClient importazure.keyvault.secrets.aio.

Klíčové koncepty

Tajný kód

Tajný kód se skládá z hodnoty tajného klíče a přidružených metadat a informací správy. Tato knihovna zpracovává tajné hodnoty jako řetězce, ale Azure Key Vault je jako takové neukládá. Další informace o tajných kódech a o tom, jak je Key Vault ukládá a spravuje, najdete v dokumentaci k Key Vault.

SecretClient může nastavit hodnoty tajných kódů v trezoru, aktualizovat metadata tajných kódů a odstranit tajné kódy, jak 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:

Nastavení tajného kódu

set_secret vytvoří nové tajné kódy a změní hodnoty existujících tajných kódů. Pokud neexistuje žádný tajný kód se zadaným názvem, set_secret vytvoří nový tajný klíč s tímto názvem a danou hodnotou. Pokud se daný název používá, set_secret vytvoří novou verzi tohoto tajného klíče s danou hodnotou.

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)

Načtení tajného kódu

get_secret načte tajný kód dříve uložený v 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)

Aktualizace metadat tajného kódu

update_secret_properties aktualizuje metadata tajného kódu. Nelze změnit hodnotu tajného kódu; k nastavení hodnoty tajného kódu použijte set_secret .

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)

Odstranění tajného klíče

begin_delete_secret žádosti Key Vault odstranění tajného kódu a vrácení polleru, 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 tajný kód co nejdříve vyprázdnit (trvale odstranit). Pokud je obnovitelné odstranění zakázané, begin_delete_secret je samo o sobě trvalé.

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)

Výpis tajných kódů

list_properties_of_secrets zobrazí seznam vlastností všech tajných kódů v trezoru klienta. Tento seznam neobsahuje hodnoty tajného kódu.

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)

Asynchronní rozhraní API

Tato knihovna obsahuje kompletní sadu asynchronních rozhraní API. Abyste je mohli používat, musíte nejdřív 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ěly zavřít, když už je nepotřebujete. Tyto objekty jsou správci asynchronního kontextu a definují asynchronní close metody. Příklad:

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

Asynchronní vytvoření tajného kódu

set_secret vytvoří tajný kód v Key Vault se zadanými volitelnými argumenty.

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)

Asynchronní výpis tajných kódů

list_properties_of_secrets zobrazí seznam vlastností všech tajných kódů v trezoru 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)

Řešení potíží

azure-keyvault-secrets 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, SecretClient vyvolá chybu 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)

protokolování

Tato knihovna používá k 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 nezopravovaných hlaviček, je možné povolit na klientovi s 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
)

Podobně logging_enable může povolit podrobné protokolování pro jednu operaci, i když není povolené pro klienta:

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

Další kroky

V úložišti GitHub sady Azure SDK pro Python je k dispozici několik ukázek. Příklad kódu pro další scénáře Key Vault: | Soubor | Popis | |-------------|-------------| | hello_world.py (asynchronní verze) | create/get/update/delete secrets | | list_operations.py (asynchronní verze) | základní operace se seznamem tajných kódů | | backup_restore_operations.py (asynchronní verze) | zálohování a obnovení tajných kódů | | recover_purge_operations.py (asynchronní verze) | obnovení a vymazání tajných kódů |

Další dokumentace

Podrobnější 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