Python용 Azure Key Vault 인증서 클라이언트 라이브러리 - 버전 4.7.0

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

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

pip install azure-keyvault-certificates azure-identity

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

필수 구성 요소

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

클라이언트 인증

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

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

클라이언트 만들기

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

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

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

주요 개념

CertificateClient

CertificateClient를 사용하면 자격 증명 모음에서 인증서를 얻고, 새 인증서와 새 버전의 기존 인증서를 만들고, 인증서 메타데이터를 업데이트하고, 인증서를 삭제할 수 있습니다. 인증서 발급자, 연락처 및 인증서의 관리 정책을 관리할 수도 있습니다. 아래 예제에 나와 있습니다 .

예제

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

• 인증서 만들기
• 인증서 검색
• 기존 인증서의 속성 업데이트
• 인증서 삭제
• 인증서의 속성 나열
• 비동기 작업
• 비동기적으로 인증서 만들기
• 인증서의 속성을 비동기적으로 나열

인증서 만들기

begin_create_certificate Azure Key Vault 저장할 인증서를 만듭니다. 이름이 같은 인증서가 이미 있는 경우 새 버전의 인증서가 만들어집니다. 인증서를 만들기 전에 인증서에 대한 관리 정책을 만들거나 기본 정책을 사용합니다. 이 메서드는 장기 실행 작업 폴러를 반환합니다.

from azure.identity import DefaultAzureCredential
from azure.keyvault.certificates import CertificateClient, CertificatePolicy

credential = DefaultAzureCredential()

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

create_certificate_poller = certificate_client.begin_create_certificate(
    certificate_name="cert-name", policy=CertificatePolicy.get_default()
)
print(create_certificate_poller.result())

인증서 만들기의 상태를 확인하려면 폴러에서 를 호출 status() 하거나 인증서 이름으로 get_certificate_operation 수 있습니다.

인증서 검색

get_certificate 이전에 Key Vault 저장된 인증서의 최신 버전을 검색합니다.

from azure.identity import DefaultAzureCredential
from azure.keyvault.certificates import CertificateClient

credential = DefaultAzureCredential()

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

certificate = certificate_client.get_certificate("cert-name")

print(certificate.name)
print(certificate.properties.version)
print(certificate.policy.issuer_name)

get_certificate_version 특정 버전의 인증서를 검색합니다.

from azure.identity import DefaultAzureCredential
from azure.keyvault.certificates import CertificateClient

credential = DefaultAzureCredential()

certificate_client = CertificateClient(vault_url="https://my-key-vault.vault.azure.net/", credential=credential)
certificate = certificate_client.get_certificate_version(certificate_name="cert-name", version="cert-version")

print(certificate.name)
print(certificate.properties.version)

기존 인증서의 속성 업데이트

update_certificate_properties 이전에 Key Vault 저장된 인증서를 업데이트합니다.

from azure.identity import DefaultAzureCredential
from azure.keyvault.certificates import CertificateClient

credential = DefaultAzureCredential()

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

# we will now disable the certificate for further use
updated_certificate= certificate_client.update_certificate_properties(
    certificate_name="cert-name", enabled=False
)

print(updated_certificate.name)
print(updated_certificate.properties.enabled)

인증서 삭제

begin_delete_certificate 요청은 인증서를 삭제할 Key Vault 있으며 삭제가 완료되기를 기다릴 수 있는 폴러를 반환합니다. 자격 증명 모음이 일시 삭제 를 사용하도록 설정되어 있고 가능한 한 빨리 인증서를 제거(영구적으로 삭제)하려는 경우 대기하는 것이 유용합니다. 일시 삭제를 사용하지 않도록 설정하면 begin_delete_certificate 그 자체가 영구적입니다.

from azure.identity import DefaultAzureCredential
from azure.keyvault.certificates import CertificateClient

credential = DefaultAzureCredential()

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

deleted_certificate_poller = certificate_client.begin_delete_certificate("cert-name")

deleted_certificate = deleted_certificate_poller.result()
print(deleted_certificate.name)
print(deleted_certificate.deleted_on)

인증서의 속성 나열

list_properties_of_certificates 지정된 Key Vault 있는 모든 인증서의 속성을 나열합니다.

from azure.identity import DefaultAzureCredential
from azure.keyvault.certificates import CertificateClient

credential = DefaultAzureCredential()

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

certificates = certificate_client.list_properties_of_certificates()

for certificate in certificates:
    # this list doesn't include versions of the certificates
    print(certificate.name)

비동기 작업

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

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

from azure.identity.aio import DefaultAzureCredential
from azure.keyvault.certificates.aio import CertificateClient

credential = DefaultAzureCredential()

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

비동기적으로 인증서 만들기

create_certificate Azure Key Vault 저장할 인증서를 만듭니다. 이름이 같은 인증서가 이미 있는 경우 새 버전의 인증서가 만들어집니다. 인증서를 만들기 전에 인증서에 대한 관리 정책을 만들거나 기본 정책을 사용합니다. 생성에 create_certificate 성공하면 만든 인증서를 반환하고, 그렇지 않으면 CertificateOperation 을 반환합니다.

from azure.identity.aio import DefaultAzureCredential
from azure.keyvault.certificates.aio import CertificateClient
from azure.keyvault.certificates import CertificatePolicy

credential = DefaultAzureCredential()

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

create_certificate_result = await certificate_client.create_certificate(
    certificate_name="cert-name", policy=CertificatePolicy.get_default()
)
print(create_certificate_result)

인증서의 속성을 비동기적으로 나열

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

from azure.identity.aio import DefaultAzureCredential
from azure.keyvault.certificates.aio import CertificateClient

credential = DefaultAzureCredential()

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

certificates = certificate_client.list_properties_of_certificates()
async for certificate in certificates:
    print(certificate.name)

문제 해결

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

일반

Key Vault 클라이언트는 azure-core에 정의된 예외를 발생합니다. 예를 들어 자격 증명 모음에 없는 키를 가져오는 경우 CertificateClient 는 ResourceNotFoundError를 발생합니다.

from azure.identity import DefaultAzureCredential
from azure.keyvault.certificates import CertificateClient
from azure.core.exceptions import ResourceNotFoundError

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

try:
    certificate_client.get_certificate("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.certificates import CertificateClient
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 = CertificateClient(
    vault_url="https://my-key-vault.vault.azure.net/",
    credential=credential,
    logging_enable=True
)

단일 작업에 대해 네트워크 추적 로깅을 사용하도록 설정할 수도 있습니다.

certificate = certificate_client.get_certificate(certificate_name="cert-name", logging_enable=True)

다음 단계

Python용 Azure SDK GitHub 리포지토리에서 몇 가지 샘플을 사용할 수 있습니다. 이러한 샘플은 추가 Key Vault 시나리오에 대한 예제 코드를 제공합니다. | 파일 | 설명 | |-------------|-------------| | hello_world.py(비동기 버전) | 인증서 만들기/가져오기/업데이트/삭제 | | backup_restore_operations.py(비동기 버전) | 인증서 백업 및 복구 | | import_certificate.py(비동기 버전) | PKCS#12(PFX) 및 PEM 형식 인증서를 Key Vault 가져오기 | | list_operations.py(비동기 버전) | list certificates | | recover_purge_operations.py(비동기 버전) | 인증서 복구 및 제거 | | issuers.py(비동기 버전) | 인증서 발급자 관리 | | contacts.py(비동기 버전) | 인증서 연락처 관리 | | parse_certificate.py(비동기 버전) | 인증서의 프라이빗 키 추출 |

추가 설명서

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

참여

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

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

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