Python용 Azure Key Vault 관리 클라이언트 라이브러리 - 버전 4.3.0

참고: 관리 라이브러리는 관리형 HSM에서만 작동합니다. Key Vault 대상으로 하는 함수는 실패합니다.

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

• 자격 증명 모음 관리(이 라이브러리) - RBAC(역할 기반 액세스 제어) 및 자격 증명 모음 수준 백업 및 복원 옵션
• 암호화 키 관리(azure-keyvault-keys) - 데이터를 암호화하는 데 사용되는 키에 대한 액세스 만들기, 저장 및 제어
• 비밀 관리(azure-keyvault-secrets) - 토큰, 암호, 인증서, API 키 및 기타 비밀에 대한 액세스를 안전하게 저장하고 제어합니다.
• 인증서 관리(azure-keyvault-certificates) - 퍼블릭 및 프라이빗 SSL/TLS 인증서 만들기, 관리 및 배포

소스 코드 | 패키지(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-administration 및 azure-identity를 설치합니다.

pip install azure-keyvault-administration azure-identity

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

필수 구성 요소

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

클라이언트 인증

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

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

KeyVaultAccessControlClient 만들기

DefaultAzureCredential이 적절한 인증 방법을 사용하도록 환경을 구성한 후 다음을 수행하여 액세스 제어 클라이언트를 만들 수 있습니다(의 vault_url 값을 관리형 HSM의 URL로 대체).

from azure.identity import DefaultAzureCredential
from azure.keyvault.administration import KeyVaultAccessControlClient

credential = DefaultAzureCredential()

client = KeyVaultAccessControlClient(
    vault_url="https://my-managed-hsm-name.managedhsm.azure.net/",
    credential=credential
)

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

KeyVaultBackupClient 만들기

DefaultAzureCredential이 적절한 인증 방법을 사용하도록 환경을 구성한 후 다음을 수행하여 백업 클라이언트를 만들 수 있습니다(의 vault_url 값을 관리형 HSM의 URL로 대체).

from azure.identity import DefaultAzureCredential
from azure.keyvault.administration import KeyVaultBackupClient

credential = DefaultAzureCredential()

client = KeyVaultBackupClient(
    vault_url="https://my-managed-hsm-name.managedhsm.azure.net/",
    credential=credential
)

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

KeyVaultSettingsClient 만들기

DefaultAzureCredential이 적절한 인증 방법을 사용하도록 환경을 구성한 후 다음을 수행하여 설정 클라이언트를 만들 수 있습니다(의 vault_url 값을 관리형 HSM의 URL로 대체).

from azure.identity import DefaultAzureCredential
from azure.keyvault.administration import KeyVaultSettingsClient

credential = DefaultAzureCredential()

client = KeyVaultSettingsClient(
    vault_url="https://my-managed-hsm-name.managedhsm.azure.net/",
    credential=credential
)

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

주요 개념

역할 정의

역할 정의는 읽기, 쓰기 및 삭제와 같이 수행할 수 있는 작업을 정의합니다. 허용되는 작업에서 제외되는 작업을 정의할 수도 있습니다.

역할 정의는 역할 할당의 일부로 지정됩니다.

역할 할당

역할 할당은 역할 정의와 서비스 주체의 연결입니다. 개별적으로 만들고, 나열하고, 가져오고, 삭제할 수 있습니다.

KeyVaultAccessControlClient

는 KeyVaultAccessControlClient 역할 정의 및 역할 할당을 관리합니다.

KeyVaultBackupClient

는 KeyVaultBackupClient 전체 키 백업, 전체 키 복원 및 선택적 키 복원을 수행합니다.

KeyVaultSettingsClient

는 KeyVaultSettingsClient 관리형 HSM 계정 설정을 관리합니다.

예제

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

• Access Control
  • 모든 역할 정의 나열
  • 역할 정의 설정, 가져오기 및 삭제
  • 모든 역할 할당 나열
  • 역할 할당 만들기, 가져오기 및 삭제
• 백업 및 복원
  • 전체 키 백업 수행
  • 전체 키 복원 수행

모든 역할 정의 나열

할당에 사용할 수 있는 역할 정의를 나열합니다.

from azure.identity import DefaultAzureCredential
from azure.keyvault.administration import KeyVaultAccessControlClient, KeyVaultRoleScope

credential = DefaultAzureCredential()

client = KeyVaultAccessControlClient(
    vault_url="https://my-managed-hsm-name.managedhsm.azure.net/",
    credential=credential
)

# this will list all role definitions available for assignment
role_definitions = client.list_role_definitions(KeyVaultRoleScope.GLOBAL)

for definition in role_definitions:
    print(definition.id)
    print(definition.role_name)
    print(definition.description)

역할 정의 설정, 가져오기 및 삭제

set_role_definition 사용자 지정 역할 정의를 만들거나 지정된 이름으로 기존 정의를 업데이트하는 데 사용할 수 있습니다.

import uuid
from azure.identity import DefaultAzureCredential
from azure.keyvault.administration import (
    KeyVaultAccessControlClient,
    KeyVaultDataAction,
    KeyVaultPermission,
    KeyVaultRoleScope
)

credential = DefaultAzureCredential()

client = KeyVaultAccessControlClient(
    vault_url="https://my-managed-hsm-name.managedhsm.azure.net/",
    credential=credential
)

# create a custom role definition
permissions = [KeyVaultPermission(allowed_data_actions=[KeyVaultDataAction.READ_HSM_KEY])]
created_definition = client.set_role_definition(KeyVaultRoleScope.GLOBAL, permissions=permissions)

# update the custom role definition
permissions = [
    KeyVaultPermission(allowed_data_actions=[], denied_data_actions=[KeyVaultDataAction.READ_HSM_KEY])
]
updated_definition = client.set_role_definition(
    KeyVaultRoleScope.GLOBAL, permissions=permissions, role_name=created_definition.name
)

# get the custom role definition
definition = client.get_role_definition(KeyVaultRoleScope.GLOBAL, role_name=definition_name)

# delete the custom role definition
deleted_definition = client.delete_role_definition(KeyVaultRoleScope.GLOBAL, role_name=definition_name)

모든 역할 할당 나열

다음 코드 조각에서 새 역할 할당을 만들기 전에 현재 역할 할당을 모두 나열합니다.

from azure.identity import DefaultAzureCredential
from azure.keyvault.administration import KeyVaultAccessControlClient, KeyVaultRoleScope

credential = DefaultAzureCredential()

client = KeyVaultAccessControlClient(
    vault_url="https://my-managed-hsm-name.managedhsm.azure.net/",
    credential=credential
)

# this will list all role assignments
role_assignments = client.list_role_assignments(KeyVaultRoleScope.GLOBAL)

for assignment in role_assignments:
    print(assignment.name)
    print(assignment.principal_id)
    print(assignment.role_definition_id)

역할 할당 만들기, 가져오기 및 삭제

서비스 주체에 역할을 할당합니다. 이렇게 하려면 역할 정의 ID 및 서비스 주체 개체 ID가 필요합니다. 검색된 전자에 대한 역할 정의 목록의 ID와 후자의 위 코드 조각에서 검색된 목록에서 할당 principal_id 을 사용할 수 있습니다.

from azure.identity import DefaultAzureCredential
from azure.keyvault.administration import KeyVaultAccessControlClient, KeyVaultRoleScope

credential = DefaultAzureCredential()

client = KeyVaultAccessControlClient(
    vault_url="https://my-managed-hsm-name.managedhsm.azure.net/",
    credential=credential
)

# Replace <role-definition-id> with the id of a definition from the fetched list from an earlier example
role_definition_id = "<role-definition-id>"
# Replace <service-principal-object-id> with the principal_id of an assignment returned from the previous example
principal_id = "<service-principal-object-id>"

# first, let's create the role assignment
role_assignment = client.create_role_assignment(KeyVaultRoleScope.GLOBAL, role_definition_id, principal_id)
print(role_assignment.name)
print(role_assignment.principal_id)
print(role_assignment.role_definition_id)

# now, we get it
role_assignment = client.get_role_assignment(KeyVaultRoleScope.GLOBAL, role_assignment.name)
print(role_assignment.name)
print(role_assignment.principal_id)
print(role_assignment.role_definition_id)

# finally, we delete this role assignment
role_assignment = client.delete_role_assignment(KeyVaultRoleScope.GLOBAL, role_assignment.name)
print(role_assignment.name)
print(role_assignment.principal_id)
print(role_assignment.role_definition_id)

전체 키 백업 수행

키의 전체 컬렉션을 백업합니다. 전체 키 백업을 위한 백업 저장소는 공유 액세스 서명 인증을 사용하는 Blob Storage 컨테이너입니다.

를 사용하여 BlobServiceClientSAS 토큰을 만드는 방법에 대한 자세한 내용은 여기 샘플을 참조 하세요. 또는 Storage Explorer SAS 토큰을 생성할 수 있습니다.

from azure.identity import DefaultAzureCredential
from azure.keyvault.administration import KeyVaultBackupClient

credential = DefaultAzureCredential()
client = KeyVaultBackupClient(vault_url="https://my-managed-hsm-name.managedhsm.azure.net/", credential=credential)

# blob storage container URL, for example https://<account name>.blob.core.windows.net/backup
blob_storage_url = "<your-blob-storage-url>"
sas_token = "<your-sas-token>"  # replace with a sas token to your storage account

# Backup is a long-running operation. The client returns a poller object whose result() method
# blocks until the backup is complete, then returns an object representing the backup operation.
backup_poller = client.begin_backup(blob_storage_url, sas_token)
backup_operation = backup_poller.result()

# this is the Azure Storage Blob URL of the backup
print(backup_operation.folder_url)

전체 키 복원 수행

백업에서 키의 전체 컬렉션을 복원합니다. 전체 키 복원을 위한 데이터 원본은 공유 액세스 서명 인증을 사용하여 액세스하는 스토리지 Blob입니다. 위 코드 조각의 도 필요합니다azure_storage_blob_container_uri.

를 사용하여 BlobServiceClientSAS 토큰을 만드는 방법에 대한 자세한 내용은 여기 샘플을 참조 하세요. 또는 Storage Explorer SAS 토큰을 생성할 수 있습니다.

from azure.identity import DefaultAzureCredential
from azure.keyvault.administration import KeyVaultBackupClient

credential = DefaultAzureCredential()
client = KeyVaultBackupClient(vault_url="https://my-managed-hsm-name.managedhsm.azure.net/", credential=credential)

sas_token = "<your-sas-token>"  # replace with a sas token to your storage account

# URL to a storage blob, for example https://<account name>.blob.core.windows.net/backup/mhsm-account-2020090117323313
blob_url = "<your-blob-url>"

# Restore is a long-running operation. The client returns a poller object whose wait() method
# blocks until the restore is complete.
restore_poller = client.begin_restore(blob_url, sas_token)
restore_poller.wait()

문제 해결

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

일반

Key Vault 클라이언트는 azure-core에 정의된 예외를 발생합니다. 예를 들어 존재하지 않는 역할 할당을 받으려고 하면 KeyVaultAccessControlClient가 ResourceNotFoundError를 발생합니다.

from azure.identity import DefaultAzureCredential
from azure.keyvault.administration import KeyVaultAccessControlClient
from azure.core.exceptions import ResourceNotFoundError

credential = DefaultAzureCredential()
client = KeyVaultAccessControlClient(vault_url="https://my-managed-hsm-name.managedhsm.azure.net/", credential=credential)

try:
    client.get_role_assignment("/", "which-does-not-exist")
except ResourceNotFoundError as e:
    print(e.message)

관리 라이브러리의 클라이언트는 관리되는 HSM에서 작업을 수행하는 데만 사용할 수 있으므로 Key Vault 수행하려고 하면 오류가 발생합니다.

다음 단계

Python용 Azure SDK GitHub 리포지토리에서 몇 가지 샘플을 사용할 수 있습니다. 이러한 샘플은 추가 Key Vault 시나리오에 대한 예제 코드를 제공합니다. | 파일 | 설명 | |-------------|-------------| | access_control_operations.py | 역할 정의 및 역할 할당 만들기/업데이트/삭제 | | access_control_operations_async.py | 비동기 클라이언트를 사용하여 역할 정의 및 역할 할당 만들기/업데이트/삭제 | | backup_restore_operations.py | 전체 백업 및 복원 | | backup_restore_operations_async.py | 비동기 클라이언트를 사용하여 전체 백업 및 복원 | | settings_operations.py | Key Vault 설정 나열 및 업데이트 | | settings_operations_async.py | 비동기 클라이언트를 사용하여 Key Vault 설정 나열 및 업데이트 |

추가 설명서

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

관리형 HSM에 대한 자세한 설명서는 서비스 설명서를 참조하세요.

참여

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

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

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