Pustaka klien Azure Key Vault Secrets untuk Python - versi 4.7.0

  • Artikel

Azure Key Vault membantu menyelesaikan masalah berikut:

  • Manajemen rahasia (pustaka ini) - menyimpan dan mengontrol akses ke token, kata sandi, sertifikat, kunci API, dan rahasia lainnya dengan aman
  • Manajemen kunci kriptografi (azure-keyvault-keys) - membuat, menyimpan, dan mengontrol akses ke kunci yang digunakan untuk mengenkripsi data Anda
  • Manajemen sertifikat (azure-keyvault-certificates) - membuat, mengelola, dan menyebarkan sertifikat SSL/TLS publik dan privat
  • Administrasi vault (azure-keyvault-administration) - kontrol akses berbasis peran (RBAC), dan opsi pencadangan dan pemulihan tingkat vault

Kode sumber | Paket (PyPI) | Paket (Conda) | Dokumentasi | referensi API Dokumentasi | produk Sampel

Pengelakan

Dukungan paket Azure SDK Python untuk Python 2.7 telah berakhir 01 Januari 2022. Untuk informasi dan pertanyaan lebih lanjut, silakan merujuk ke https://github.com/Azure/azure-sdk-for-python/issues/20691. Python 3.7 atau yang lebih baru diharuskan untuk menggunakan paket ini. Untuk detail selengkapnya, silakan lihat kebijakan dukungan versi Azure SDK for Python.

Memulai

Memasang paket

Instal azure-keyvault-secrets dan azure-identity dengan pip:

pip install azure-keyvault-secrets azure-identity

azure-identity digunakan untuk autentikasi Azure Active Directory seperti yang ditunjukkan di bawah ini.

Prasyarat

  • Langganan Azure
  • Python 3.7 atau yang lebih baru
  • Azure Key Vault yang sudah ada. Jika Anda perlu membuatnya, Anda bisa melakukannya menggunakan Azure CLI dengan mengikuti langkah-langkah dalam dokumen ini.

Mengautentikasi klien

Untuk berinteraksi dengan layanan Azure Key Vault, Anda memerlukan instans SecretClient, serta url vault dan objek kredensial. Dokumen ini menunjukkan penggunaan DefaultAzureCredential, yang sesuai untuk sebagian besar skenario, termasuk lingkungan pengembangan dan produksi lokal. Sebaiknya gunakan identitas terkelola untuk autentikasi di lingkungan produksi.

Lihat dokumentasi azure-identity untuk informasi selengkapnya tentang metode autentikasi lain dan jenis kredensial yang sesuai.

Membuat klien

Setelah mengonfigurasi lingkungan Anda untuk DefaultAzureCredential untuk menggunakan metode autentikasi yang sesuai, Anda dapat melakukan hal berikut untuk membuat klien rahasia (mengganti nilai VAULT_URL dengan URL vault Anda):

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

CATATAN: Untuk klien asinkron, impor azure.keyvault.secrets.aiosebagai gantinya SecretClient .

Konsep utama

Rahasia

Rahasia terdiri dari nilai rahasia dan metadata serta informasi manajemen terkait. Pustaka ini menangani nilai rahasia sebagai string, tetapi Azure Key Vault tidak menyimpannya. Untuk informasi selengkapnya tentang rahasia dan cara Key Vault menyimpan dan mengelolanya, lihat dokumentasi Key Vault.

SecretClient dapat mengatur nilai rahasia di vault, memperbarui metadata rahasia, dan menghapus rahasia, seperti yang ditunjukkan pada contoh di bawah ini.

Contoh

Bagian ini berisi cuplikan kode yang mencakup tugas umum:

Menetapkan rahasia

set_secret membuat rahasia baru dan mengubah nilai rahasia yang ada. Jika tidak ada rahasia dengan nama yang diberikan, set_secret buat rahasia baru dengan nama tersebut dan nilai yang diberikan. Jika nama yang diberikan sedang digunakan, set_secret membuat versi baru rahasia tersebut, dengan nilai yang diberikan.

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)

Menampilkan rahasia

get_secret mengambil rahasia yang sebelumnya disimpan di 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)

Memperbarui metadata rahasia

update_secret_properties memperbarui metadata rahasia. Ini tidak dapat mengubah nilai rahasia; gunakan set_secret untuk mengatur nilai rahasia.

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)

Menghapus rahasia

begin_delete_secret permintaan Key Vault menghapus rahasia, mengembalikan poller yang memungkinkan Anda menunggu penghapusan selesai. Menunggu sangat membantu ketika vault mengaktifkan penghapusan sementara , dan Anda ingin menghapus menyeluruh (menghapus secara permanen) rahasia sesegera mungkin. Ketika penghapusan sementara dinonaktifkan, begin_delete_secret itu sendiri bersifat permanen.

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)

Daftar rahasia

list_properties_of_secrets mencantumkan properti semua rahasia di vault klien. Daftar ini tidak menyertakan nilai rahasia.

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)

API Asinkron

Pustaka ini mencakup sekumpulan API asinkron lengkap. Untuk menggunakannya, Anda harus menginstal transportasi asinkron terlebih dahulu, seperti aiohttp. Lihat dokumentasi azure-core untuk informasi selengkapnya.

Klien dan kredensial asinkron harus ditutup ketika tidak lagi diperlukan. Objek ini adalah manajer konteks asinkron dan menentukan metode asinkron close . Contohnya:

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

Membuat rahasia secara asinkron

set_secret membuat rahasia di Key Vault dengan argumen opsional yang ditentukan.

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)

Daftar rahasia secara asinkron

list_properties_of_secrets mencantumkan properti semua rahasia di vault klien.

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)

Pemecahan Masalah

azure-keyvault-secrets Lihat panduan pemecahan masalah untuk detail tentang cara mendiagnosis berbagai skenario kegagalan.

Umum

Key Vault klien meningkatkan pengecualian yang ditentukan dalam azure-core. Misalnya, jika Anda mencoba mendapatkan kunci yang tidak ada di vault, SecretClient akan menaikkan 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)

Pembuatan Log

Pustaka ini menggunakan pustaka pengelogan standar untuk pengelogan. Informasi dasar tentang sesi HTTP (URL, header, dll.) dicatat di tingkat INFO.

Pengelogan tingkat DEBUG terperinci, termasuk isi permintaan/respons dan header yang tidak diredaktifkan, dapat diaktifkan pada klien dengan logging_enable argumen :

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
)

Demikian pula, logging_enable dapat mengaktifkan pengelogan mendetail untuk satu operasi, meskipun tidak diaktifkan untuk klien:

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

Langkah berikutnya

Beberapa sampel tersedia di repositori GitHub Azure SDK for Python. Ini memberikan contoh kode untuk skenario Key Vault tambahan: | File | Deskripsi | |-------------|-------------| | hello_world.py (versi asinkron) | membuat/mendapatkan/memperbarui/menghapus rahasia | | list_operations.py (versi asinkron) | operasi daftar dasar untuk rahasia | | backup_restore_operations.py (versi asinkron) | mencadangkan dan memulihkan rahasia | | recover_purge_operations.py (versi asinkron) | memulihkan dan menghapus menyeluruh rahasia |

Dokumentasi Tambahan

Untuk dokumentasi yang lebih luas tentang Azure Key Vault, lihat dokumentasi referensi API.

Berkontribusi

Proyek ini menyambut baik kontribusi dan saran. Sebagian besar kontribusi mengharuskan Anda menyetujui Perjanjian Lisensi Kontributor (CLA) yang menyatakan bahwa Anda memiliki hak untuk, dan benar-benar melakukannya, memberi kami hak untuk menggunakan kontribusi Anda. Untuk detailnya, kunjungi https://cla.microsoft.com.

Ketika Anda mengirimkan permintaan tarik, CLA-bot akan secara otomatis menentukan apakah Anda perlu memberikan CLA dan menghias PR dengan tepat (misalnya, label, komentar). Cukup ikuti instruksi yang diberikan oleh bot. Anda hanya perlu melakukan ini sekali di semua repos menggunakan CLA kami.

Proyek ini telah mengadopsi Kode Etik Sumber Terbuka Microsoft. Untuk informasi selengkapnya, lihat FAQ Kode Etik atau hubungi opencode@microsoft.com untuk mengajukan pertanyaan atau komentar tambahan.

Tayangan