共用方式為


適用于 Python 的 Azure 金鑰保存庫 金鑰用戶端程式庫 - 4.8.0 版

Azure Key Vault 可協助您解決下列問題:

  • 密碼編譯金鑰管理 (此程式庫) - 建立、儲存和控制用來加密資料的金鑰存取
  • 秘密管理 (azure-keyvault-secrets) - 安全地儲存和控制權杖、密碼、憑證、API 金鑰和其他秘密的存取
  • 憑證管理 (azure-keyvault-certificates) - 建立、管理及部署公用和私人 SSL/TLS 憑證
  • 保存庫管理 (azure-keyvault-administration) - 角色型存取控制 (RBAC) ,以及保存庫層級的備份和還原選項

| 原始程式碼套件 (PyPI) | 套件 (Conda) | API 參考檔 | 產品檔 | 樣品

免責聲明

Python 2.7 的 Azure SDK Python 套件支援已于 2022 年 1 月 1 日結束。 如需詳細資訊和問題,請參閱 https://github.com/Azure/azure-sdk-for-python/issues/20691

需要 Python 3.7 或更新版本才能使用此套件。 如需詳細資訊,請參閱 適用于 Python 的 Azure SDK 版本支援原則

開始使用

安裝套件

使用pip安裝azure-keyvault-keysazure-identity

pip install azure-keyvault-keys azure-identity

azure-identity 用於 Azure Active Directory 驗證,如下所示。

必要條件

驗證用戶端

若要與 Azure 金鑰保存庫服務互動,您需要KeyClient的實例,以及保存庫 URL和認證物件。 本檔示範如何使用 DefaultAzureCredential,這適用于大部分案例,包括本機開發和生產環境。 建議您在生產環境中使用 受控識別 進行驗證。

如需其他驗證方法及其對應認證類型的詳細資訊,請參閱 azure 身分識別 檔。

建立用戶端

將環境設定為 DefaultAzureCredential 以使用適當的驗證方法之後,您可以執行下列動作來建立金鑰用戶端, (將 的值 VAULT_URL 取代為保存庫的 URL) :

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

注意: 針對非同步用戶端,請改為匯 azure.keyvault.keys.aioKeyClient 入 。

重要概念

索引鍵

Azure 金鑰保存庫可以建立及儲存 RSA 和橢圓曲線金鑰。 兩者都可以選擇性地受到硬體安全性模組的保護, (HSM) 。 Azure 金鑰保存庫也可以使用它們來執行密碼編譯作業。 如需金鑰和支援的作業和演算法的詳細資訊,請參閱金鑰保存庫檔

KeyClient 可以在保存庫中建立金鑰、從保存庫取得現有的金鑰、更新金鑰中繼資料和刪除金鑰,如下列 範例 所示。

範例

本節包含涵蓋一般工作的程式碼片段:

建立金鑰

create_rsa_keycreate_ec_key 分別在保存庫中建立 RSA 和橢圓曲線金鑰。 如果具有相同名稱的索引鍵已經存在,就會建立該金鑰的新版本。

from azure.identity import DefaultAzureCredential
from azure.keyvault.keys import KeyClient

credential = DefaultAzureCredential()

key_client = KeyClient(vault_url="https://my-key-vault.vault.azure.net/", credential=credential)

# Create an RSA key
rsa_key = key_client.create_rsa_key("rsa-key-name", size=2048)
print(rsa_key.name)
print(rsa_key.key_type)

# Create an elliptic curve key
ec_key = key_client.create_ec_key("ec-key-name", curve="P-256")
print(ec_key.name)
print(ec_key.key_type)

擷取金鑰

get_key 擷取先前儲存在保存庫中的金鑰。

from azure.identity import DefaultAzureCredential
from azure.keyvault.keys import KeyClient

credential = DefaultAzureCredential()

key_client = KeyClient(vault_url="https://my-key-vault.vault.azure.net/", credential=credential)
key = key_client.get_key("key-name")
print(key.name)

更新現有的金鑰

update_key_properties更新先前儲存在金鑰保存庫中的金鑰屬性。

from azure.identity import DefaultAzureCredential
from azure.keyvault.keys import KeyClient

credential = DefaultAzureCredential()

key_client = KeyClient(vault_url="https://my-key-vault.vault.azure.net/", credential=credential)

# we will now disable the key for further use
updated_key = key_client.update_key_properties("key-name", enabled=False)

print(updated_key.name)
print(updated_key.properties.enabled)

刪除金鑰

begin_delete_key要求金鑰保存庫刪除金鑰,傳回輪詢器,讓您等候刪除完成。 當保存庫已啟用 虛刪除 時,等候會很有説明,而且您想要儘快清除 (永久刪除) 金鑰。 停用 虛刪除 時, begin_delete_key 本身是永久的。

from azure.identity import DefaultAzureCredential
from azure.keyvault.keys import KeyClient

credential = DefaultAzureCredential()

key_client = KeyClient(vault_url="https://my-key-vault.vault.azure.net/", credential=credential)
deleted_key = key_client.begin_delete_key("key-name").result()

print(deleted_key.name)
print(deleted_key.deleted_date)

設定自動金鑰輪替

update_key_rotation_policy 可讓您藉由指定輪替原則來設定金鑰的自動金鑰輪替。 此外, rotate_key 可讓您藉由建立新版的指定金鑰來隨選輪替金鑰。

from azure.identity import DefaultAzureCredential
from azure.keyvault.keys import KeyClient, KeyRotationLifetimeAction, KeyRotationPolicyAction

credential = DefaultAzureCredential()
key_client = KeyClient(vault_url="https://my-key-vault.vault.azure.net/", credential=credential)

# Set the key's automated rotation policy to rotate the key 30 days before the key expires
actions = [KeyRotationLifetimeAction(KeyRotationPolicyAction.ROTATE, time_before_expiry="P30D")]
# You may also specify the duration after which the newly rotated key will expire
# In this example, any new key versions will expire after 90 days
updated_policy = key_client.update_key_rotation_policy("key-name", expires_in="P90D", lifetime_actions=actions)

# You can get the current rotation policy for a key with get_key_rotation_policy
current_policy = key_client.get_key_rotation_policy("key-name")

# Finally, you can rotate a key on-demand by creating a new version of the key
rotated_key = key_client.rotate_key("key-name")

列出金鑰

list_properties_of_keys 列出用戶端保存庫中所有金鑰的屬性。

from azure.identity import DefaultAzureCredential
from azure.keyvault.keys import KeyClient

credential = DefaultAzureCredential()

key_client = KeyClient(vault_url="https://my-key-vault.vault.azure.net/", credential=credential)
keys = key_client.list_properties_of_keys()

for key in keys:
    # the list doesn't include values or versions of the keys
    print(key.name)

密碼編譯作業

CryptographyClient 可讓密碼編譯作業 (加密/解密、包裝/解除包裝、簽署/驗證) 使用特定金鑰。

from azure.identity import DefaultAzureCredential
from azure.keyvault.keys import KeyClient
from azure.keyvault.keys.crypto import CryptographyClient, EncryptionAlgorithm

credential = DefaultAzureCredential()
key_client = KeyClient(vault_url="https://my-key-vault.vault.azure.net/", credential=credential)

key = key_client.get_key("key-name")
crypto_client = CryptographyClient(key, credential=credential)
plaintext = b"plaintext"

result = crypto_client.encrypt(EncryptionAlgorithm.rsa_oaep, plaintext)
decrypted = crypto_client.decrypt(result.algorithm, result.ciphertext)

如需密碼編譯 API 的詳細資訊,請參閱 套件檔

非同步 API

此程式庫包含一組完整的非同步 API。 若要使用它們,您必須先安裝非同步傳輸,例如 aioHTTP。 如需詳細資訊 ,請參閱 azure 核心檔

不再需要非同步用戶端和認證時,應該關閉它們。 這些物件是非同步內容管理員,並定義非同步 close 方法。 例如:

from azure.identity.aio import DefaultAzureCredential
from azure.keyvault.keys.aio import KeyClient

credential = DefaultAzureCredential()

# call close when the client and credential are no longer needed
client = KeyClient(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 = KeyClient(vault_url="https://my-key-vault.vault.azure.net/", credential=credential)
async with client:
  async with credential:
    ...

以非同步方式建立金鑰

create_rsa_keycreate_ec_key 分別在保存庫中建立 RSA 和橢圓曲線金鑰。 如果具有相同名稱的金鑰已經存在,則會建立新版本的金鑰。

from azure.identity.aio import DefaultAzureCredential
from azure.keyvault.keys.aio import KeyClient

credential = DefaultAzureCredential()
key_client = KeyClient(vault_url="https://my-key-vault.vault.azure.net/", credential=credential)

# Create an RSA key
rsa_key = await key_client.create_rsa_key("rsa-key-name", size=2048)
print(rsa_key.name)
print(rsa_key.key_type)

# Create an elliptic curve key
ec_key = await key_client.create_ec_key("ec-key-name", curve="P-256")
print(ec_key.name)
print(ec_key.key_type)

以非同步方式列出金鑰

list_properties_of_keys 列出用戶端保存庫中所有金鑰的屬性。

from azure.identity.aio import DefaultAzureCredential
from azure.keyvault.keys.aio import KeyClient

credential = DefaultAzureCredential()
key_client = KeyClient(vault_url="https://my-key-vault.vault.azure.net/", credential=credential)
keys = key_client.list_properties_of_keys()

async for key in keys:
    print(key.name)

疑難排解

azure-keyvault-keys如需如何診斷各種失敗案例的詳細資訊,請參閱疑難排解指南

一般

金鑰保存庫用戶端會引發azure 核心中定義的例外狀況。 例如,如果您嘗試取得保存庫中不存在的金鑰, KeyClient 會引發 ResourceNotFoundError

from azure.identity import DefaultAzureCredential
from azure.keyvault.keys import KeyClient
from azure.core.exceptions import ResourceNotFoundError

credential = DefaultAzureCredential()
key_client = KeyClient(vault_url="https://my-key-vault.vault.azure.net/", credential=credential)

try:
    key_client.get_key("which-does-not-exist")
except ResourceNotFoundError as e:
    print(e.message)

記錄

此程式庫會使用標準 記錄 程式庫進行記錄。 HTTP 會話的基本資訊 (URL、標頭等) 會記錄在 INFO 層級。

您可以在具有 引數的用戶端 logging_enable 上啟用詳細的 DEBUG 層級記錄,包括要求/回應主體和未處理的標頭:

from azure.identity import DefaultAzureCredential
from azure.keyvault.keys import KeyClient
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 = KeyClient(vault_url="https://my-key-vault.vault.azure.net/", credential=credential, logging_enable=True)

同樣地,logging_enable 可對單一作業啟用詳細記錄,即使未對用戶端啟用也可行:

client.get_key("my-key", logging_enable=True)

後續步驟

Azure SDK for Python GitHub 存放庫中提供數個範例。 這些提供其他金鑰保存庫案例的範例程式碼: |檔案 |描述 | |-------------|-------------| |hello_world.py (非同步版本) |create/get/update/delete keys |list_operations.py (非同步版本) |金鑰的基本欄表作業 | |backup_restore_operations.py (非同步版本) |備份和復原金鑰 | |recover_purge_operations.py (非同步版本) |復原和清除金鑰 | |send_request.py |send_request使用用戶端方法 |

其他文件

如需 Azure 金鑰保存庫的詳細資訊檔,請參閱API 參考檔

參與

此專案歡迎參與和提供建議。 大部分的參與都要求您同意「參與者授權合約 (CLA)」,宣告您有權且確實授與我們使用投稿的權利。 如需詳細資料,請前往 https://cla.microsoft.com

當您提交提取要求時,CLA Bot 會自動判斷您是否需要提供 CLA,並適當地裝飾 PR (例如標籤、註解)。 請遵循 bot 提供的指示。 您只需要使用我們的 CLA 在所有存放庫上執行此動作一次。

此專案採用了 Microsoft 開放原始碼管理辦法。 如需詳細資訊,請參閱管理辦法常見問題集,如有其他問題或意見,請連絡 opencode@microsoft.com。

曝光數