Python용 Azure ID 클라이언트 라이브러리의 자격 증명 체인
Azure ID 클라이언트 라이브러리는 Azure Core 라이브러리의 TokenCredential 프로토콜을 구현하는 공용 클래스인 자격 증명을 제공합니다. 자격 증명은 Microsoft Entra ID에서 액세스 토큰을 획득하기 위한 고유한 인증 흐름을 나타냅니다. 이러한 자격 증명을 함께 연결하여 정렬된 일련의 인증 메커니즘을 구성할 수 있습니다.
연결된 자격 증명의 작동 방식
런타임 시 자격 증명 체인은 시퀀스의 첫 번째 자격 증명을 사용하여 인증을 시도합니다. 해당 자격 증명이 액세스 토큰을 획득하지 못하면 액세스 토큰을 성공적으로 가져올 때까지 시퀀스의 다음 자격 증명이 시도됩니다. 다음 시퀀스 다이어그램은 이 동작을 설명합니다:
자격 증명 체인을 사용하는 이유
연결된 자격 증명은 다음과 같은 이점을 제공할 수 있습니다.
환경 인식: 앱이 실행 중인 환경에 따라 가장 적합한 자격 증명을 자동으로 선택합니다. 이 코드가 없으면 다음과 같은 코드를 작성해야 합니다.
# Set up credential based on environment (Azure or local development) if os.getenv("WEBSITE_HOSTNAME"): credential = ManagedIdentityCredential(client_id=user_assigned_client_id) else: credential = AzureCliCredential()원활한 전환: 앱은 인증 코드를 변경하지 않고 로컬 개발에서 스테이징 또는 프로덕션 환경으로 이동할 수 있습니다.
향상된 복원력: 이전에 액세스 토큰을 획득하지 못한 경우 다음 자격 증명으로 이동하는 대체 메커니즘을 포함합니다.
연결된 자격 증명을 선택하는 방법
자격 증명 체인에는 다음과 같은 두 가지 서로 다른 철학이 있습니다.
- 체인 "해제하기": 미리 구성된 체인으로 시작하고 필요하지 않은 것을 제외합니다. 이 접근 방식에 대해서는 DefaultAzureCredential 개요 섹션을 참조하세요.
- 체인 "구축": 빈 체인으로 시작하고 필요한 것만 포함합니다. 이 접근 방식에 대해서는 DefaultAzureCredential 개요 섹션을 참조하세요.
DefaultAzureCredential 개요
DefaultAzureCredential 은 미리 구성된 자격 증명 체인입니다. 가장 일반적인 인증 흐름 및 개발자 도구와 함께 많은 환경을 지원하도록 설계되었습니다. 그래픽 형식의 기본 체인은 다음과 같습니다.
DefaultAzureCredential이 자격 증명을 시도하는 순서는 다음과 같습니다.
| 순서 | 자격 증명 | 설명 | 기본값으로 사용합니까? |
|---|---|---|---|
| 1 | 환경 | 환경 변수 컬렉션을 읽어 애플리케이션 서비스 주체(애플리케이션 사용자)가 앱에 대해 구성되어 있는지 확인합니다. 그렇다면 DefaultAzureCredential은 이러한 값을 사용하여 Azure에 앱을 인증합니다. 이 방법은 서버 환경에서 가장 많이 사용되지만, 로컬로 개발할 때도 사용할 수 있습니다. |
예 |
| 2 | 워크로드 ID | 앱이 워크로드 ID를 사용하도록 설정된 Azure 호스트에 배포된 경우 해당 계정을 인증합니다. | 예 |
| 3 | 관리 ID | 앱이 관리되는 ID를 사용하도록 설정된 Azure 호스트에 배포된 경우, 해당 관리되는 ID를 사용하여 Azure에 앱을 인증합니다. | 예 |
| 4 | 공유 토큰 캐시 | 개발자가 Visual Studio에 로그인하여 Azure에 인증한 경우 동일한 계정을 사용하여 Azure에 앱을 인증합니다. (Windows에만 해당) | 예 |
| 5 | Azure CLI | 개발자가 Azure CLI의 az login 명령을 사용하여 Azure에 인증한 경우 동일한 계정을 사용하여 Azure에 앱을 인증합니다. |
예 |
| 6 | Azure PowerShell | 개발자가 Azure PowerShell의 Connect-AzAccount cmdlet을 사용하여 Azure에 인증한 경우 동일한 계정을 사용하여 Azure에 앱을 인증합니다. |
예 |
| 7 | Azure Developer CLI | 개발자가 Azure 개발자 CLI의 azd auth login 명령을 사용하여 Azure에 인증한 경우 해당 계정으로 인증합니다. |
예 |
| 8 | 대화형 브라우저 | 활성화된 경우 현재 시스템의 기본 브라우저를 통해 개발자를 대화형으로 인증합니다. | 아니요 |
가장 간단한 형태인 DefaultAzureCredential의 매개변수 없는 버전은 다음과 같이 사용할 수 있습니다:
from azure.identity import DefaultAzureCredential
from azure.storage.blob import BlobServiceClient
# Acquire a credential object
credential = DefaultAzureCredential()
blob_service_client = BlobServiceClient(
account_url="https://<my_account_name>.blob.core.windows.net",
credential=credential
)
DefaultAzureCredential을 사용자 지정하는 방법
자격 증명DefaultAzureCredential을 제거하려면 해당 exclude접두사 키워드 매개 변수를 사용합니다. 예시:
credential = DefaultAzureCredential(
exclude_environment_credential=True,
exclude_workload_identity_credential=True,
managed_identity_client_id=user_assigned_client_id
)
이전 코드 샘플에서 EnvironmentCredential과 WorkloadIdentityCredential는 자격 증명 체인에서 제거됩니다. 결과적으로 첫 번째로 시도되는 자격 증명은 ManagedIdentityCredential입니다. 수정된 체인은 다음과 같습니다.
참고 항목
InteractiveBrowserCredential 는 기본적으로 제외되므로 앞의 다이어그램에 표시되지 않습니다. 포함InteractiveBrowserCredential하려면 생성자를 호출할 때 키워드 매개 변수를 DefaultAzureCredential False 설정합니다exclude_interactive_browser_credential.
접두사 키워드 매개 변수가 더 많이 exclude설정 True 되면(자격 증명 제외가 구성됨) 사용 DefaultAzureCredential 의 장점이 줄어듭니다. 이러한 경우 ChainedTokenCredential 더 나은 선택이며 더 적은 코드가 필요합니다. 이를 설명하기 위해 다음 두 코드 샘플은 동일한 방식으로 작동합니다.
credential = DefaultAzureCredential(
exclude_environment_credential=True,
exclude_workload_identity_credential=True,
exclude_shared_token_cache_credential=True,
exclude_azure_powershell_credential=True,
exclude_azure_developer_cli_credential=True,
managed_identity_client_id=user_assigned_client_id
)
ChainedTokenCredential 개요
ChainedTokenCredential은 앱의 필요에 맞게 자격 증명을 추가하는 빈 체인입니다. 예시:
credential = ChainedTokenCredential(
ManagedIdentityCredential(client_id=user_assigned_client_id),
AzureCliCredential()
)
앞의 코드 샘플은 두 개의 자격 증명으로 구성된 맞춤형 자격 증명 체인을 생성합니다. 사용자가 지정한 ManagedIdentityCredential의 관리형 ID 변형이 먼저 시도되고, 필요한 경우 AzureCliCredential가 시도됩니다. 그래픽 형식으로 체인은 다음과 같이 표시됩니다:
팁
성능을 개선하려면 ChainedTokenCredential에서 프로덕션 환경에 맞게 자격증명 순서를 최적화하세요. 로컬 개발 환경에서 사용하기 위한 자격 증명을 마지막으로 추가해야 합니다.
DefaultAzureCredential에 대한 사용 지침
DefaultAzureCredential 는 의심할 여지 없이 Azure ID 클라이언트 라이브러리를 시작하는 가장 쉬운 방법이지만 이러한 편의상 장단점이 있습니다. Azure에 앱을 배포한 후에는 앱의 인증 요구 사항을 이해해야 합니다. 따라서 DefaultAzureCredential에서 다음 솔루션 중 하나로 이동하는 것을 강력히 고려하세요:
- 와 같은
ManagedIdentityCredential특정 자격 증명 구현입니다. - 앱이 실행되는 Azure 환경에 최적화된 축소된
ChainedTokenCredential구현입니다.
이유는 다음과 같습니다.
- 디버깅 문제: 인증에 실패하면 잘못된 자격 증명을 디버깅하고 식별하는 것이 어려울 수 있습니다. 한 자격 증명에서 다음 자격 증명으로의 진행률과 각 자격 증명의 성공/실패 상태를 보려면 로깅을 사용하도록 설정해야 합니다. 자세한 내용은 연결된 자격증명 디버깅하기를 참조하세요.
- 성능 오버헤드: 여러 자격 증명을 순차적으로 시도하는 프로세스로 인해 성능 오버헤드가 발생할 수 있습니다. 예를 들어 로컬 개발 머신에서 실행하는 경우 관리 ID를 사용할 수 없습니다. 따라서
ManagedIdentityCredential은 해당exclude접두사 속성을 통해 명시적으로 비활성화하지 않는 한 로컬 개발 환경에서는 항상 실패합니다. - 예측할 수 없는 동작:
DefaultAzureCredential특정 환경 변수가 있는지 확인합니다. 누군가 호스트 컴퓨터의 시스템 수준에서 이러한 환경 변수를 추가하거나 수정할 수 있습니다. 이러한 변경 사항은 전역적으로 적용되므로 해당 컴퓨터에서 실행 중인 모든 앱에서 런타임 시DefaultAzureCredential의 동작이 변경됩니다.
연결된 자격 증명 디버그
예기치 않은 문제를 진단하거나 체인화된 자격 증명이 어떤 역할을 하는지 파악하려면 앱에서 로깅을 활성화하세요. 필요에 따라 로그를 Azure ID 클라이언트 라이브러리에서 내보낸 이벤트로만 필터링합니다. 예시:
import logging
from azure.identity import DefaultAzureCredential
# Set the logging level for the Azure Identity library
logger = logging.getLogger("azure.identity")
logger.setLevel(logging.DEBUG)
# Direct logging output to stdout. Without adding a handler,
# no logging output is visible.
handler = logging.StreamHandler(stream=sys.stdout)
logger.addHandler(handler)
# Optional: Output logging levels to the console.
print(
f"Logger enabled for ERROR={logger.isEnabledFor(logging.ERROR)}, "
f"WARNING={logger.isEnabledFor(logging.WARNING)}, "
f"INFO={logger.isEnabledFor(logging.INFO)}, "
f"DEBUG={logger.isEnabledFor(logging.DEBUG)}"
)
설명을 위해 매개 변수가 없는 형식 DefaultAzureCredential 이 Blob Storage 계정에 대한 요청을 인증하는 데 사용된다고 가정합니다. 앱은 로컬 개발 환경에서 실행되고 개발자는 Azure CLI를 사용하여 Azure에 인증됩니다. 로깅 수준이 .로깅 수준으로 설정되어 있다고 가정합니다 logging.DEBUG. 앱이 실행되면 출력에 다음과 같은 관련 항목이 표시됩니다.
Logger enabled for ERROR=True, WARNING=True, INFO=True, DEBUG=True
No environment configuration found.
ManagedIdentityCredential will use IMDS
EnvironmentCredential.get_token failed: EnvironmentCredential authentication unavailable. Environment variables are not fully configured.
Visit https://aka.ms/azsdk/python/identity/environmentcredential/troubleshoot to troubleshoot this issue.
ManagedIdentityCredential.get_token failed: ManagedIdentityCredential authentication unavailable, no response from the IMDS endpoint.
SharedTokenCacheCredential.get_token failed: SharedTokenCacheCredential authentication unavailable. No accounts were found in the cache.
AzureCliCredential.get_token succeeded
[Authenticated account] Client ID: 00001111-aaaa-2222-bbbb-3333cccc4444. Tenant ID: aaaabbbb-0000-cccc-1111-dddd2222eeee. User Principal Name: unavailableUpn. Object ID (user): aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb
DefaultAzureCredential acquired a token from AzureCliCredential
앞의 출력에서 이를 확인할 수 있습니다:
EnvironmentCredential,ManagedIdentityCredential,SharedTokenCacheCredential이 각각 Microsoft Entra 액세스 토큰을 획득하지 못했습니다(순서대로).- 호출이
AzureCliCredential.get_token성공하고 출력은 토큰을 획득했음DefaultAzureCredential을AzureCliCredential나타냅니다.AzureCliCredential성공 이후 자격 증명이 시도되지 않았습니다.
참고 항목
앞의 예제에서 로깅 수준은 .로깅 수준으로 설정됩니다 logging.DEBUG. 중요한 정보를 출력할 수 있으므로 이 로깅 수준을 사용할 때는 주의해야 합니다. 예를 들어 이 경우 Azure에서 개발자 사용자 계정의 클라이언트 ID, 테넌트 ID 및 개체 ID가 있습니다. 명확성을 위해 출력에서 모든 추적 정보가 제거되었습니다.