Python용 Azure Key Vault 비밀 클라이언트 라이브러리 - 버전 4.7.0

Azure Key Vault는 다음 문제를 해결하는 데 도움이 됩니다.

• 비밀 관리(이 라이브러리) - 토큰, 암호, 인증서, API 키 및 기타 비밀에 대한 액세스를 안전하게 저장하고 제어합니다.
• 암호화 키 관리(azure-keyvault-keys) - 데이터를 암호화하는 데 사용되는 키에 대한 액세스 만들기, 저장 및 제어
• 인증서 관리(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-secrets 및 azure-identity를 설치합니다.

pip install azure-keyvault-secrets azure-identity

azure-identity 는 아래와 같이 Azure Active Directory 인증에 사용됩니다.

필수 구성 요소

• Azure 구독
• Python 3.7 이상
• 기존 Azure Key Vault. 만들어야 하는 경우 이 문서의 단계에 따라 Azure CLI를 사용하여 만들 수 있습니다.

클라이언트 인증

Azure Key Vault 서비스와 상호 작용하려면 SecretClient 인스턴스와 자격 증명 모음 URL 및 자격 증명 개체가 필요합니다. 이 문서에서는 로컬 개발 및 프로덕션 환경을 비롯한 대부분의 시나리오에 적합한 DefaultAzureCredential을 사용하는 방법을 보여 줍니다. 프로덕션 환경에서 인증에 관리 ID 를 사용하는 것이 좋습니다.

다른 인증 방법 및 해당 자격 증명 유형에 대한 자세한 내용은 azure-identity 설명서를 참조하세요.

클라이언트 만들기

DefaultAzureCredential이 적절한 인증 방법을 사용하도록 환경을 구성한 후 다음을 수행하여 비밀 클라이언트를 만들 수 있습니다(의 VAULT_URL 값을 자격 증명 모음의 URL로 대체).

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

참고: 비동기 클라이언트의 경우 를 대신 가져옵니다azure.keyvault.secrets.aioSecretClient.

주요 개념

비밀

비밀은 비밀 값과 관련된 메타데이터 및 관리 정보로 구성됩니다. 이 라이브러리는 비밀 값을 문자열로 처리하지만 Azure Key Vault 이러한 값을 저장하지 않습니다. 비밀 및 Key Vault 저장 및 관리하는 방법에 대한 자세한 내용은 Key Vault 설명서를 참조하세요.

SecretClient 는 아래 예제와 같이 자격 증명 모음에서 비밀 값을 설정하고, 비밀 메타데이터를 업데이트하고, 비밀을 삭제할 수 있습니다 .

예제

이 섹션에는 일반적인 작업을 다루는 코드 조각이 포함되어 있습니다.

• 비밀 설정
• 비밀 검색
• 비밀 메타데이터 업데이트
• 암호 삭제
• 비밀 나열
• 비동기 API
• 비동기적으로 비밀 만들기
• 비동기적으로 비밀 나열

비밀 설정

set_secret 새 비밀을 만들고 기존 비밀의 값을 변경합니다. 지정된 이름의 비밀이 set_secret 없으면 해당 이름과 지정된 값을 사용하여 새 비밀을 만듭니다. 지정된 이름을 사용하는 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)
secret = secret_client.set_secret("secret-name", "secret-value")

print(secret.name)
print(secret.value)
print(secret.properties.version)

비밀 검색

get_secret 이전에 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)

비밀 메타데이터 업데이트

update_secret_properties 비밀의 메타데이터를 업데이트합니다. 비밀의 값은 변경할 수 없습니다. 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)

비밀 삭제

begin_delete_secret 요청은 비밀을 삭제할 Key Vault 삭제가 완료되기를 기다릴 수 있는 폴러를 반환합니다. 자격 증명 모음이 일시 삭제 를 사용하도록 설정되어 있고 가능한 한 빨리 비밀을 제거(영구적으로 삭제)하려는 경우 대기하는 것이 유용합니다. 일시 삭제를 사용하지 않도록 설정하면 begin_delete_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)
deleted_secret = secret_client.begin_delete_secret("secret-name").result()

print(deleted_secret.name)
print(deleted_secret.deleted_date)

암호 나열

list_properties_of_secrets 클라이언트 자격 증명 모음에 있는 모든 비밀의 속성을 나열합니다. 이 목록에는 비밀의 값이 포함되지 않습니다.

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

이 라이브러리에는 전체 비동기 API 집합이 포함되어 있습니다. 이를 사용하려면 먼저 aiohttp와 같은 비동기 전송을 설치해야 합니다. 자세한 내용은 azure-core 설명서를 참조하세요.

비동기 클라이언트 및 자격 증명은 더 이상 필요하지 않은 경우 닫아야 합니다. 이러한 개체는 비동기 컨텍스트 관리자이며 비동 close 기 메서드를 정의합니다. 예를 들면 다음과 같습니다.

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

비동기적으로 비밀 만들기

set_secret 지정된 선택적 인수를 사용하여 Key Vault 비밀을 만듭니다.

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)

비동기적으로 비밀 나열

list_properties_of_secrets 클라이언트 자격 증명 모음에 있는 모든 비밀의 속성을 나열합니다.

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)

문제 해결

azure-keyvault-secrets 다양한 오류 시나리오를 진단하는 방법에 대한 자세한 내용은 문제 해결 가이드를 참조하세요.

일반

Key Vault 클라이언트는 azure-core에 정의된 예외를 발생합니다. 예를 들어 자격 증명 모음에 없는 키를 가져오는 경우 SecretClient 는 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)

로깅

이 라이브러리는 로깅에 표준 로깅 라이브러리를 사용합니다. HTTP 세션(URL, 헤더 등)에 대한 기본 정보는 INFO 수준에서 기록됩니다.

요청/응답 본문 및 수정되지 않은 헤더를 포함한 자세한 DEBUG 수준 로깅은 인수를 사용하여 클라이언트 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
)

마찬가지로 logging_enable은 클라이언트에 대해 상세 로깅을 사용하지 않는 경우에도 한 작업에만 사용하게 설정할 수 있습니다.

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

다음 단계

Python용 Azure SDK GitHub 리포지토리에서 몇 가지 샘플을 사용할 수 있습니다. 다음은 추가 Key Vault 시나리오에 대한 예제 코드를 제공합니다. | 파일 | 설명 | |-------------|-------------| | hello_world.py(비동기 버전) | 비밀 만들기/가져오기/업데이트/삭제 | | list_operations.py(비동기 버전) | 비밀에 대한 기본 목록 작업 | | backup_restore_operations.py(비동기 버전) | 비밀 백업 및 복원 | | recover_purge_operations.py(비동기 버전) | 비밀 복구 및 제거 |

추가 설명서

Azure Key Vault 대한 자세한 설명서는 API 참조 설명서를 참조하세요.

참여

이 프로젝트에 대한 기여와 제안을 환영합니다. 대부분의 경우 기여하려면 권한을 부여하며 실제로 기여를 사용할 권한을 당사에 부여한다고 선언하는 CLA(기여자 라이선스 계약)에 동의해야 합니다. 자세한 내용은 https://cla.microsoft.com 을 참조하세요.

끌어오기 요청을 제출하면 CLA-bot은 CLA를 제공하고 PR을 적절하게 데코레이팅해야 하는지 여부를 자동으로 결정합니다(예: 레이블, 설명). 봇에서 제공하는 지침을 따르기만 하면 됩니다. 이 작업은 CLA를 사용하여 모든 리포지토리에서 한 번만 수행하면 됩니다.

이 프로젝트는 Microsoft 오픈 소스 준수 사항을 채택했습니다. 자세한 내용은 준수 사항 FAQ를 참조하거나 opencode@microsoft.com에 추가 질문 또는 의견을 알려주세요.