Python용 Azure ID 클라이언트 라이브러리 - 버전 1.14.1
Azure ID 라이브러리는 Azure SDK에서 Azure AD(Azure Active Directory) 토큰 인증 지원을 제공합니다. Azure AD 토큰 인증을 지원하는 Azure SDK 클라이언트를 생성하는 데 사용할 수 있는 구현 집합 TokenCredential 을 제공합니다.
소스 코드 | 패키지(PyPI) | 패키지(Conda) | API 참조 설명서 | Azure AD 설명서
시작
패키지 설치
pip를 사용하여 Azure ID를 설치합니다.
pip install azure-identity
필수 구성 요소
- Azure 구독
- Python 3.7 또는 최신 버전의 Python 3(이 라이브러리는 수명 종료 버전을 지원하지 않음)
로컬 개발 중 인증
코드를 로컬로 디버깅하고 실행할 때 개발자는 Azure 서비스에 대한 호출을 인증하기 위해 고유한 계정을 사용하는 것이 일반적입니다. Azure ID 라이브러리는 로컬 개발을 간소화하기 위해 개발자 도구를 통한 인증을 지원합니다.
Visual Studio Code 통해 인증
Visual Studio Code 사용하는 개발자는 Azure 계정 확장을 사용하여 편집기를 통해 인증할 수 있습니다. 또는 를 VisualStudioCodeCredential 사용하는 DefaultAzureCredential 앱은 로컬로 실행할 때 이 계정을 사용하여 앱에서 호출을 인증할 수 있습니다.
Visual Studio Code 인증하려면 Azure 계정 확장이 설치되어 있는지 확인합니다. 설치되면 명령 팔레트 를 열고 Azure: 로그인 명령을 실행합니다.
Azure 계정 확장 버전이 VisualStudioCodeCredential0.9.11보다 최신 버전에서 작동하지 않는 알려진 문제입니다. 이 문제에 대한 장기적인 수정이 진행 중입니다. 그 동안 Azure CLI를 통해 인증하는 것이 좋습니다.
Azure CLI를 통해 인증
DefaultAzureCredential 및 AzureCliCredential 는 사용자가 Azure CLI에 로그인한 것으로 인증할 수 있습니다. Azure CLI에 로그인하려면 를 실행합니다 az login. 기본 웹 브라우저가 있는 시스템에서 Azure CLI는 브라우저를 시작하여 사용자를 인증합니다.
기본 브라우저를 사용할 수 az login 없는 경우 는 디바이스 코드 인증 흐름을 사용합니다. 이 흐름은 를 실행 az login --use-device-code하여 수동으로 선택할 수도 있습니다.
Azure Developer CLI 통해 인증
IDE 외부에서 코딩하는 개발자는 Azure Developer CLI 사용하여 인증할 수도 있습니다. 그러면 DefaultAzureCredential 또는 AzureDeveloperCliCredential을 사용하는 애플리케이션이 이 계정을 사용하여 로컬에서 실행할 때 애플리케이션에서 호출을 인증할 수 있습니다.
Azure Developer CLI 인증하기 위해 사용자는 명령을 azd auth login실행할 수 있습니다. 기본 웹 브라우저가 있는 시스템에서 실행되는 사용자의 경우 Azure Developer CLI 브라우저를 시작하여 사용자를 인증합니다.
기본 웹 브라우저가 없는 시스템의 경우 azd auth login --use-device-code 명령은 디바이스 코드 인증 흐름을 사용합니다.
주요 개념
자격 증명
자격 증명은 서비스 클라이언트가 요청을 인증하는 데 필요한 데이터를 포함하고 있거나 획득할 수 있는 클래스입니다. Azure SDK의 서비스 클라이언트는 생성될 때 자격 증명 instance 수락하고 해당 자격 증명을 사용하여 요청을 인증합니다.
Azure ID 라이브러리는 Azure AD 사용한 OAuth 인증에 중점을 둡니다. Azure AD 액세스 토큰을 획득할 수 있는 다양한 자격 증명 클래스를 제공합니다. 이 라이브러리의 자격 목록은 아래의 자격 증명 클래스 자격 증명 클래스 섹션을 참조하세요.
DefaultAzureCredential
DefaultAzureCredential 는 일반적인 프로덕션 자격 증명과 개발 자격 증명을 결합하기 때문에 Azure에서 실행되는 대부분의 애플리케이션에 적합합니다. DefaultAzureCredential 는 다음 메커니즘을 통해 인증을 시도합니다. 이 순서대로 성공하면 중지됩니다.
참고:
DefaultAzureCredential적절한 기본 동작으로 일반적인 시나리오를 처리하여 라이브러리 시작을 간소화하기 위한 것입니다. 더 많은 제어를 원하거나 자신의 시나리오가 기본 설정에서 제공되지 않는 개발자는 다른 자격 증명 형식을 사용해야 합니다.
- 환경 -
DefaultAzureCredential통해 지정된 계정 정보를 읽고 이를 사용하여 인증합니다. - 워크로드 ID - 애플리케이션이 관리 ID를 사용하도록 설정된 Azure Kubernetes Service 배포된
DefaultAzureCredential경우 에서 인증합니다. - 관리 ID - 애플리케이션이 관리 ID를 사용하도록 설정된 Azure 호스트에 배포된
DefaultAzureCredential경우 에서 인증합니다. - Azure CLI - 사용자가 Azure CLI
az login명령을DefaultAzureCredential통해 로그인한 경우 는 해당 사용자로 인증됩니다. - Azure PowerShell - 사용자가 Azure PowerShell
Connect-AzAccount명령을DefaultAzureCredential통해 로그인한 경우 는 해당 사용자로 인증됩니다. - Azure Developer CLI - 개발자가 Azure Developer CLI
azd auth login명령을DefaultAzureCredential통해 인증한 경우 는 해당 계정으로 인증됩니다. - 대화형 브라우저 - 사용하도록 설정된 경우 는
DefaultAzureCredential기본 브라우저를 통해 사용자를 대화형으로 인증합니다. 이 자격 증명 형식은 기본적으로 사용하지 않도록 설정됩니다.
참고 정보 VisualStudioCodeCredential
알려진 문제로VisualStudioCodeCredential 인해 이 토큰 체인에서 DefaultAzureCredential 제거되었습니다. 이후 릴리스에서 문제가 해결되면 이 변경 내용이 되돌려집니다.
예제
다음 예제는 다음과 같습니다.
DefaultAzureCredential을 사용하여 인증
를 사용하도록 DefaultAzureCredential 환경을 구성하는 방법에 대한 자세한 내용은 클래스의 참조 설명서에서 확인할 수 있습니다.
이 예제에서는 를 사용하여 DefaultAzureCredentialazure-storage-blob 라이브러리에서 를 인증하는 BlobServiceClient 방법을 보여 줍니다.
from azure.identity import DefaultAzureCredential
from azure.storage.blob import BlobServiceClient
default_credential = DefaultAzureCredential()
client = BlobServiceClient(account_url, credential=default_credential)
를 사용하여 대화형 인증 사용 DefaultAzureCredential
대화형 인증은 기본적으로 사용하지 DefaultAzureCredential 않도록 설정되며 키워드(keyword) 인수를 사용하여 사용하도록 설정할 수 있습니다.
DefaultAzureCredential(exclude_interactive_browser_credential=False)
사용하도록 설정 DefaultAzureCredential 하면 다른 자격 증명을 사용할 수 없는 경우 시스템의 기본 웹 브라우저를 통해 대화형 인증으로 돌아갑니다.
에 대한 사용자 할당 관리 ID 지정 DefaultAzureCredential
많은 Azure 호스트에서 사용자가 할당한 관리 ID를 할당할 수 있습니다. 사용자 할당 ID를 인증하도록 구성 DefaultAzureCredential 하려면 키워드(keyword) 인수를 managed_identity_client_id 사용합니다.
DefaultAzureCredential(managed_identity_client_id=client_id)
또는 환경 변수 AZURE_CLIENT_ID 를 ID의 클라이언트 ID로 설정합니다.
ChainedTokenCredential을 사용하여 사용자 지정 인증 흐름 정의
DefaultAzureCredential 는 일반적으로 Azure용 애플리케이션 개발을 시작하는 가장 빠른 방법입니다. 고급 시나리오의 경우 ChainedTokenCredential 은 인증할 때 순차적으로 시도할 여러 자격 증명 인스턴스를 연결합니다. 연결된 각 자격 증명은 토큰을 제공하거나 오류로 인해 인증에 실패할 때까지 차례로 시도합니다.
다음 예제에서는 먼저 관리 ID를 사용하여 인증을 시도하는 자격 증명을 만드는 방법을 보여 줍니다. 관리 ID를 사용할 수 없는 경우 자격 증명은 Azure CLI를 통해 인증으로 대체됩니다. 이 예제에서는 azure-eventhub 클라이언트 라이브러리의 를 사용합니다EventHubProducerClient.
from azure.eventhub import EventHubProducerClient
from azure.identity import AzureCliCredential, ChainedTokenCredential, ManagedIdentityCredential
managed_identity = ManagedIdentityCredential()
azure_cli = AzureCliCredential()
credential_chain = ChainedTokenCredential(managed_identity, azure_cli)
client = EventHubProducerClient(namespace, eventhub_name, credential_chain)
비동기 자격 증명
이 라이브러리에는 비동기 API 집합이 포함되어 있습니다. azure.identity.aio에서 비동기 자격 증명을 사용하려면 먼저 aiohttp와 같은 비동기 전송을 설치해야 합니다. 자세한 내용은 azure-core 설명서를 참조하세요.
비동기 자격 증명은 더 이상 필요하지 않은 경우 닫아야 합니다. 각 비동기 자격 증명은 비동기 컨텍스트 관리자이며 비동 close 기 메서드를 정의합니다. 예:
from azure.identity.aio import DefaultAzureCredential
# call close when the credential is no longer needed
credential = DefaultAzureCredential()
...
await credential.close()
# alternatively, use the credential as an async context manager
credential = DefaultAzureCredential()
async with credential:
...
이 예제에서는 비동 SecretClient 기 자격 증명을 사용하여 azure-keyvault-secrets 에서 비동기 인증을 보여 줍니다.
from azure.identity.aio import DefaultAzureCredential
from azure.keyvault.secrets.aio import SecretClient
default_credential = DefaultAzureCredential()
client = SecretClient("https://my-vault.vault.azure.net", default_credential)
관리 ID 지원
관리 ID 인증은 다음 Azure 서비스에 대해 또는 ManagedIdentityCredential 를 통해 DefaultAzureCredential 직접 지원됩니다.
- Azure App Service 및 Azure Functions
- Azure Arc
- Azure Cloud Shell
- Azure Kubernetes Service
- Azure Service Fabric
- Azure Virtual Machines
- Azure Virtual machines 확장 집합
예제
사용자 할당 관리 ID를 사용하여 인증
from azure.identity import ManagedIdentityCredential
from azure.keyvault.secrets import SecretClient
credential = ManagedIdentityCredential(client_id=managed_identity_client_id)
client = SecretClient("https://my-vault.vault.azure.net", credential)
시스템 할당 관리 ID로 인증
from azure.identity import ManagedIdentityCredential
from azure.keyvault.secrets import SecretClient
credential = ManagedIdentityCredential()
client = SecretClient("https://my-vault.vault.azure.net", credential)
클라우드 구성
자격 증명은 기본적으로 Azure 퍼블릭 클라우드에 대한 Azure AD 엔드포인트에 인증합니다. Azure Government 또는 프라이빗 클라우드와 같은 다른 클라우드의 리소스에 액세스하려면 인수를 사용하여 자격 증명을 authority 구성합니다. AzureAuthorityHosts는 잘 알려진 클라우드에 대한 기관을 정의합니다.
from azure.identity import AzureAuthorityHosts
DefaultAzureCredential(authority=AzureAuthorityHosts.AZURE_GOVERNMENT)
클라우드에 대한 권한이 에 AzureAuthorityHosts나열되지 않은 경우 해당 URL을 명시적으로 지정할 수 있습니다.
DefaultAzureCredential(authority="https://login.partner.microsoftonline.cn")
인수를 지정하는 authority 대신 환경 변수를 AZURE_AUTHORITY_HOST 클라우드 권한의 URL로 설정할 수도 있습니다. 이 방법은 동일한 클라우드에 인증하도록 여러 자격 증명을 구성할 때 유용합니다.
AZURE_AUTHORITY_HOST=https://login.partner.microsoftonline.cn
모든 자격 증명에 이 구성이 필요한 것은 아닙니다. 와 같은 AzureCliCredential개발 도구를 통해 인증하는 자격 증명은 해당 도구의 구성을 사용합니다. 마찬가지로 는 VisualStudioCodeCredential 인수를 authority 허용하지만 기본적으로 VS Code의 "Azure: 클라우드" 설정과 일치하는 권한으로 설정됩니다.
자격 증명 클래스
Azure 호스팅 애플리케이션 인증
| 자격 증명 | 사용량 |
|---|---|
DefaultAzureCredential |
Azure에서 실행되는 애플리케이션 개발을 빠르게 시작하는 간소화된 인증 환경을 제공합니다. |
ChainedTokenCredential |
사용자가 여러 자격 증명을 구성하는 사용자 지정 인증 흐름을 정의할 수 있습니다. |
EnvironmentCredential |
환경 변수에 지정된 자격 증명 정보를 통해 서비스 주체 또는 사용자를 인증합니다. |
ManagedIdentityCredential |
Azure 리소스의 관리 ID를 인증합니다. |
WorkloadIdentityCredential |
Kubernetes에서 Azure AD 워크로드 ID를 지원합니다. |
서비스 주체 인증
| 자격 증명 | 사용량 | 참고 |
|---|---|---|
CertificateCredential |
인증서를 사용하여 서비스 주체를 인증합니다. | 서비스 주체 인증 |
ClientAssertionCredential |
서명된 클라이언트 어설션을 사용하여 서비스 주체를 인증합니다. | |
ClientSecretCredential |
비밀을 사용하여 서비스 주체를 인증합니다. | 서비스 주체 인증 |
사용자 인증
| 자격 증명 | 사용량 | 참고 |
|---|---|---|
AuthorizationCodeCredential |
이전에 가져온 권한 부여 코드를 사용하여 사용자를 인증합니다. | OAuth2 인증 코드 |
DeviceCodeCredential |
UI가 제한된 디바이스에서 사용자를 대화형으로 인증합니다. | 디바이스 코드 인증 |
InteractiveBrowserCredential |
기본 시스템 브라우저를 사용하여 사용자를 대화형으로 인증합니다. | OAuth2 인증 코드 |
OnBehalfOfCredential |
요청 체인을 통해 위임된 사용자 ID 및 권한을 전파합니다. | On-Behalf-Of 인증 |
UsernamePasswordCredential |
사용자 이름 및 암호를 사용하여 사용자를 인증합니다(다단계 인증을 지원하지 않음). | 사용자 이름 + 암호 인증 |
개발 도구를 통해 인증
| 자격 증명 | 사용량 | 참고 |
|---|---|---|
AzureCliCredential |
Azure CLI를 사용하여 개발 환경에서 인증합니다. | Azure CLI 인증 |
AzureDeveloperCliCredential |
Azure Developer CLI 사용하여 개발 환경에서 인증합니다. | Azure Developer CLI 참조 |
AzurePowerShellCredential |
Azure PowerShell 사용하여 개발 환경에서 인증합니다. | Azure PowerShell 인증 |
VisualStudioCodeCredential |
사용자가 Visual Studio Code Azure 계정 확장에 로그인한 것으로 인증합니다. | VS Code Azure 계정 확장 |
환경 변수
DefaultAzureCredential 및 EnvironmentCredential은 환경 변수를 사용하여 구성할 수 있습니다. 각 인증 유형에는 다음과 같은 특정 변수 값이 필요합니다.
비밀을 사용하는 서비스 주체
| 변수 이름 | 값 |
|---|---|
AZURE_CLIENT_ID |
Azure AD 애플리케이션 ID |
AZURE_TENANT_ID |
애플리케이션의 Azure AD 테넌트 ID |
AZURE_CLIENT_SECRET |
애플리케이션의 클라이언트 암호 중 하나 |
인증서를 사용하는 서비스 주체
| 변수 이름 | 값 |
|---|---|
AZURE_CLIENT_ID |
Azure AD 애플리케이션 ID |
AZURE_TENANT_ID |
애플리케이션의 Azure AD 테넌트 ID |
AZURE_CLIENT_CERTIFICATE_PATH |
프라이빗 키를 포함한 PEM 또는 PKCS12 인증서 파일 경로 |
AZURE_CLIENT_CERTIFICATE_PASSWORD |
인증서 파일의 암호(있는 경우) |
사용자 이름 및 암호
| 변수 이름 | 값 |
|---|---|
AZURE_CLIENT_ID |
Azure AD 애플리케이션 ID |
AZURE_USERNAME |
사용자 이름(일반적으로 메일 주소) |
AZURE_PASSWORD |
해당 사용자 암호 |
위의 순서대로 구성이 시도됩니다. 예를 들어 클라이언트 암호 및 인증서 값이 모두 있는 경우 클라이언트 암호가 사용됩니다.
토큰 캐싱
토큰 캐싱은 앱에서 다음을 수행할 수 있도록 하는 Azure ID 라이브러리에서 제공하는 기능입니다.
- 메모리(기본값) 또는 디스크(옵트인)에서 토큰을 캐시합니다.
- 복원력 및 성능을 개선합니다.
- 액세스 토큰을 가져오기 위해 Azure AD 요청 수를 줄입니다.
Azure ID 라이브러리는 메모리 내 및 영구 디스크 캐싱을 모두 제공합니다. 자세한 내용은 토큰 캐싱 설명서를 참조하세요.
문제 해결
다양한 오류 시나리오를 진단하는 방법에 대한 자세한 내용은 문제 해결 가이드 를 참조하세요.
오류 처리
자격 증명은 필요한 데이터 또는 상태가 부족하여 인증을 시도할 수 없을 때 발생 CredentialUnavailableError 합니다. 예를 들어 EnvironmentCredential 은 이 불완전할 때 이 예외를 발생합니다.
자격 증명이 인증에 실패하면 azure.core.exceptions.ClientAuthenticationError가 발생합니다. ClientAuthenticationError 에는 message 인증이 실패한 이유를 설명하는 특성이 있습니다. 또는 ChainedTokenCredential에 의해 DefaultAzureCredential 발생하는 경우 메시지는 체인의 각 자격 증명에서 오류 메시지를 수집합니다.
특정 Azure AD 오류 처리에 대한 자세한 내용은 Azure AD 오류 코드 설명서를 참조하세요.
로깅
이 라이브러리는 로깅에 표준 로깅 라이브러리를 사용합니다. 자격 증명은 INFO 수준에서 HTTP 세션(URL, 헤더 등)을 포함한 기본 정보를 기록합니다. 이러한 로그 항목에는 인증 비밀이 포함되지 않습니다.
요청/응답 본문 및 헤더 값을 포함한 자세한 DEBUG 수준 로깅은 기본적으로 사용하도록 설정되지 않습니다. 인수를 logging_enable 사용하여 사용하도록 설정할 수 있습니다. 예:
credential = DefaultAzureCredential(logging_enable=True)
주의: 자격 증명의 디버그 수준 로그에는 중요한 정보가 포함됩니다. 계정 보안이 손상되지 않도록 이러한 로그를 보호해야 합니다.
다음 단계
클라이언트 라이브러리 지원
Azure AD 인증을 지원하는 Azure SDK 릴리스 페이지에 나열된 클라이언트 및 관리 라이브러리는 이 라이브러리의 자격 증명을 수락합니다. 릴리스 페이지에서 연결된 설명서에서 이러한 라이브러리를 사용하는 방법에 대해 자세히 알아볼 수 있습니다.
알려진 문제
이 라이브러리는 Azure AD B2C를 지원하지 않습니다.
열려 있는 다른 문제는 라이브러리의 GitHub 리포지토리를 참조하세요.
피드백 제공
버그가 발생하거나 제안이 있는 경우 문제를 엽니다.
참여
이 프로젝트에 대한 기여와 제안을 환영합니다. 대부분의 경우 기여하려면 권한을 부여하며 실제로 기여를 사용할 권한을 당사에 부여한다고 선언하는 CLA(기여자 라이선스 계약)에 동의해야 합니다. 자세한 내용은 https://cla.microsoft.com 을 참조하세요.
끌어오기 요청을 제출하면 CLA-bot은 CLA를 제공하고 PR을 적절하게 데코레이팅해야 하는지 여부를 자동으로 결정합니다(예: 레이블, 설명). 봇에서 제공하는 지침을 따르기만 하면 됩니다. CLA를 사용하여 모든 리포지토리에서 한 번만 이 작업을 수행해야 합니다.
이 프로젝트는 Microsoft 오픈 소스 준수 사항을 채택했습니다. 자세한 내용은 준수 사항 FAQ를 참조하거나 opencode@microsoft.com에 추가 질문 또는 의견을 알려주세요.
