Python용 Azure Key Vault 키 클라이언트 라이브러리 - 버전 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-keys 및 azure-identity를 설치합니다.
pip install azure-keyvault-keys azure-identity
azure-identity 는 아래와 같이 Azure Active Directory 인증에 사용됩니다.
필수 구성 요소
- Azure 구독
- Python 3.7 이상
- 기존 Azure Key Vault. 만들어야 하는 경우 이 문서의 단계에 따라 Azure CLI를 사용하여 만들 수 있습니다.
- 관리형 HSM을 사용하는 경우 기존 Key Vault 관리형 HSM입니다. 관리형 HSM을 만들어야 하는 경우 이 문서의 단계에 따라 Azure CLI를 사용하여 만들 수 있습니다.
클라이언트 인증
Azure Key Vault 서비스와 상호 작용하려면 KeyClient 인스턴스와 자격 증명 모음 URL 및 자격 증명 개체가 필요합니다. 이 문서에서는 로컬 개발 및 프로덕션 환경을 비롯한 대부분의 시나리오에 적합한 DefaultAzureCredential을 사용하는 방법을 보여 줍니다. 프로덕션 환경에서 인증에 관리 ID 를 사용하는 것이 좋습니다.
다른 인증 방법 및 해당 자격 증명 유형에 대한 자세한 내용은 azure-identity 설명서를 참조하세요.
클라이언트 만들기
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 Key Vault RSA 및 타원 곡선 키를 만들고 저장할 수 있습니다. 둘 다 필요에 따라 HSM(하드웨어 보안 모듈)으로 보호할 수 있습니다. Azure Key Vault 암호화 작업을 수행할 수도 있습니다. 키 및 지원되는 작업 및 알고리즘에 대한 자세한 내용은 Key Vault 설명서를 참조하세요.
KeyClient 는 아래 예제와 같이 자격 증명 모음에 키를 만들고, 자격 증명 모음에서 기존 키를 얻고, 키 메타데이터를 업데이트하고, 키를 삭제할 수 있습니다 .
예제
이 섹션에는 일반적인 작업을 다루는 코드 조각이 포함되어 있습니다.
키 만들기
create_rsa_key 및 create_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 이전에 Key Vault 저장된 키의 속성을 업데이트합니다.
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 삭제가 완료되기를 기다릴 수 있는 폴러를 반환하여 키를 삭제할 Key Vault 요청합니다. 자격 증명 모음이 일시 삭제 를 사용하도록 설정되어 있고 가능한 한 빨리 키를 제거(영구적으로 삭제)하려는 경우 대기하는 것이 유용합니다. 일시 삭제를 사용하지 않도록 설정하면 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-core 설명서를 참조하세요.
비동기 클라이언트 및 자격 증명은 더 이상 필요하지 않은 경우 닫아야 합니다. 이러한 개체는 비동기 컨텍스트 관리자이며 비동기 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_key 및 create_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 다양한 오류 시나리오를 진단하는 방법에 대한 자세한 내용은 문제 해결 가이드를 참조하세요.
일반
Key Vault 클라이언트는 azure-core에 정의된 예외를 발생합니다. 예를 들어 자격 증명 모음에 없는 키를 얻으려고 하면 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 수준에서 기록됩니다.
요청/응답 본문 및 수정되지 않은 헤더를 포함한 자세한 DEBUG 수준 로깅은 인수가 있는 클라이언트 logging_enable 에서 사용하도록 설정할 수 있습니다.
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)
다음 단계
Python용 Azure SDK GitHub 리포지토리에서 몇 가지 샘플을 사용할 수 있습니다.
다음은 추가 Key Vault 시나리오에 대한 예제 코드를 제공합니다. | 파일 | 설명 | |-------------|-------------| | hello_world.py(비동기 버전) | 키 만들기/가져오기/업데이트/삭제 | | list_operations.py(비동기 버전) | 키에 대한 기본 목록 작업 | | backup_restore_operations.py(비동기 버전) | 키 백업 및 복구 | | recover_purge_operations.py(비동기 버전) | 키 복구 및 제거 | | send_request.py | send_request 클라이언트 메서드 사용 |
추가 설명서
Azure Key Vault 대한 보다 광범위한 설명서는 API 참조 설명서를 참조하세요.
참여
이 프로젝트에 대한 기여와 제안을 환영합니다. 대부분의 경우 기여하려면 권한을 부여하며 실제로 기여를 사용할 권한을 당사에 부여한다고 선언하는 CLA(기여자 라이선스 계약)에 동의해야 합니다. 자세한 내용은 https://cla.microsoft.com 을 참조하세요.
끌어오기 요청을 제출하면 CLA-bot은 CLA를 제공하고 PR을 적절하게 데코레이팅해야 하는지 여부를 자동으로 결정합니다(예: 레이블, 설명). 봇에서 제공하는 지침을 따르기만 하면 됩니다. 이 작업은 CLA를 사용하여 모든 리포지토리에서 한 번만 수행하면 됩니다.
이 프로젝트는 Microsoft 오픈 소스 준수 사항을 채택했습니다. 자세한 내용은 준수 사항 FAQ를 참조하거나 opencode@microsoft.com에 추가 질문 또는 의견을 알려주세요.
Azure SDK for Python
피드백
출시 예정: 2024년 내내 콘텐츠에 대한 피드백 메커니즘으로 GitHub 문제를 단계적으로 폐지하고 이를 새로운 피드백 시스템으로 바꿀 예정입니다. 자세한 내용은 다음을 참조하세요. https://aka.ms/ContentUserFeedback
다음에 대한 사용자 의견 제출 및 보기