.NET용 Azure Identity 라이브러리
Microsoft Entra ID를 사용하여 Azure SDK 클라이언트를 인증하는 라이브러리입니다.
설치
dotnet add package Azure.Identity
# ASP.NET Core 통합을 위한 경우
dotnet add package Microsoft.Extensions.Azure
# 브로커 인증 및 Visual Studio Code 자격 증명 지원을 위한 경우
dotnet add package Azure.Identity.Broker
환경 변수
비밀을 사용한 서비스 주체
AZURE_CLIENT_ID=<application-client-id>
AZURE_TENANT_ID=<directory-tenant-id>
AZURE_CLIENT_SECRET=<client-secret-value>
인증서를 사용한 서비스 주체
AZURE_CLIENT_ID=<application-client-id>
AZURE_TENANT_ID=<directory-tenant-id>
AZURE_CLIENT_CERTIFICATE_PATH=<path-to-pfx-or-pem>
AZURE_CLIENT_CERTIFICATE_PASSWORD=<certificate-password> # 선택 사항
관리 ID
AZURE_CLIENT_ID=<user-assigned-managed-identity-client-id> # 사용자 할당의 경우만
DefaultAzureCredential
대부분의 시나리오에 권장되는 자격 증명입니다. 여러 인증 방법을 순서대로 시도합니다. 현재 자격 증명 체인 순서 및 기본값에 대한 자세한 내용은 DefaultAzureCredential 개요를 참조하세요.
기본 사용법
using Azure.Identity;
using Azure.Storage.Blobs;
var credential = new DefaultAzureCredential();
var blobClient = new BlobServiceClient(
new Uri("https://myaccount.blob.core.windows.net"),
credential);
ASP.NET Core 및 의존성 주입
using Azure.Identity;
using Microsoft.Extensions.Azure;
builder.Services.AddAzureClients(clientBuilder =>
{
clientBuilder.AddBlobServiceClient(
new Uri("https://myaccount.blob.core.windows.net"));
clientBuilder.AddSecretClient(
new Uri("https://myvault.vault.azure.net"));
// 기본적으로 DefaultAzureCredential을 사용합니다.
clientBuilder.UseCredential(new DefaultAzureCredential());
});
DefaultAzureCredential 사용자 지정
var credential = new DefaultAzureCredential(
new DefaultAzureCredentialOptions
{
ExcludeEnvironmentCredential = true,
ExcludeManagedIdentityCredential = false,
ExcludeVisualStudioCredential = false,
ExcludeAzureCliCredential = false,
ExcludeInteractiveBrowserCredential = false, // 대화형 사용
TenantId = "<tenant-id>",
ManagedIdentityClientId = "<user-assigned-mi-client-id>"
});
자격 증명 유형
ManagedIdentityCredential (프로덕션)
// 시스템 할당 관리 ID
var credential = new ManagedIdentityCredential(ManagedIdentityId.SystemAssigned);
// 클라이언트 ID로 사용자 할당
var credential = new ManagedIdentityCredential(
ManagedIdentityId.FromUserAssignedClientId("<client-id>"));
// 리소스 ID로 사용자 할당
var credential = new ManagedIdentityCredential(
ManagedIdentityId.FromUserAssignedResourceId("<resource-id>"));
// 개체 ID로 사용자 할당
var credential = new ManagedIdentityCredential(
ManagedIdentityId.FromUserAssignedObjectId("<object-id>"));
ClientSecretCredential
var credential = new ClientSecretCredential(
tenantId: "<tenant-id>",
clientId: "<client-id>",
clientSecret: "<client-secret>");
var client = new SecretClient(
new Uri("https://myvault.vault.azure.net"),
credential);
ClientCertificateCredential
var certificate = X509CertificateLoader.LoadCertificateFromFile("MyCertificate.pfx");
var credential = new ClientCertificateCredential(
tenantId: "<tenant-id>",
clientId: "<client-id>",
certificate);
ChainedTokenCredential (사용자 지정 체인)
var credential = new ChainedTokenCredential(
new ManagedIdentityCredential(),
new AzureCliCredential());
var client = new SecretClient(
new Uri("https://myvault.vault.azure.net"),
credential);
개발자 자격 증명
// Azure CLI
var credential = new AzureCliCredential();
// Azure PowerShell
var credential = new AzurePowerShellCredential();
// Azure Developer CLI (azd)
var credential = new AzureDeveloperCliCredential();
// Visual Studio
var credential = new VisualStudioCredential();
// 대화형 브라우저
var credential = new InteractiveBrowserCredential();
환경 기반 구성
// 프로덕션 및 개발
TokenCredential credential = builder.Environment.IsProduction()
? new ManagedIdentityCredential("<client-id>")
: new DefaultAzureCredential();
소버린 클라우드
var credential = new DefaultAzureCredential(
new DefaultAzureCredentialOptions
{
AuthorityHost = AzureAuthorityHosts.AzureGovernment
});
// 사용 가능한 기관 호스트:
// AzureAuthorityHosts.AzurePublicCloud (기본값)
// AzureAuthorityHosts.AzureGovernment
// AzureAuthorityHosts.AzureChina
자격 증명 유형 참조
| 범주 | 자격 증명 | 용도 |
|---|---|---|
| 체인 | DefaultAzureCredential | 개발부터 프로덕션까지 미리 구성된 체인 |
ChainedTokenCredential | 사용자 지정 자격 증명 체인 | |
| Azure 호스팅 | ManagedIdentityCredential | Azure 관리 ID |
WorkloadIdentityCredential | Kubernetes 워크로드 ID | |
EnvironmentCredential | 환경 변수 | |
| 서비스 주체 | ClientSecretCredential | 클라이언트 ID + 비밀 |
ClientCertificateCredential | 클라이언트 ID + 인증서 | |
ClientAssertionCredential | 서명된 클라이언트 어설션 | |
| 사용자 | InteractiveBrowserCredential | 브라우저 기반 인증 |
DeviceCodeCredential | 디바이스 코드 흐름 | |
OnBehalfOfCredential | 위임된 ID | |
| 개발자 | AzureCliCredential | Azure CLI |
AzurePowerShellCredential | Azure PowerShell | |
AzureDeveloperCliCredential | Azure Developer CLI | |
VisualStudioCredential | Visual Studio |
모범 사례
1. 프로덕션에서 결정적 자격 증명 사용
// 개발
var devCredential = new DefaultAzureCredential();
// 프로덕션 - 특정 자격 증명 사용
var prodCredential = new ManagedIdentityCredential(
ManagedIdentityId.FromUserAssignedClientId("<client-id>"));
2. 자격 증명 인스턴스 재사용
// 좋음: 여러 클라이언트에서 공유되는 단일 자격 증명 인스턴스
var credential = new DefaultAzureCredential();
var blobClient = new BlobServiceClient(blobUri, credential);
var secretClient = new SecretClient(vaultUri, credential);
3. 재시도 정책 구성
var options = new ManagedIdentityCredentialOptions(
ManagedIdentityId.FromUserAssignedClientId(clientId))
{
Retry =
{
MaxRetries = 3,
Delay = TimeSpan.FromSeconds(0.5),
}
};
var credential = new ManagedIdentityCredential(options);
4. 디버깅을 위한 로깅 활성화
using Azure.Core.Diagnostics;
using AzureEventSourceListener listener = new((args, message) =>
{
if (args is { EventSource.Name: "Azure-Identity" })
{
Console.WriteLine(message);
}
}, EventLevel.LogAlways);
오류 처리
using Azure.Identity;
using Azure.Security.KeyVault.Secrets;
var client = new SecretClient(
new Uri("https://myvault.vault.azure.net"),
new DefaultAzureCredential());
try
{
KeyVaultSecret secret = await client.GetSecretAsync("secret1");
}
catch (AuthenticationFailedException e)
{
Console.WriteLine($"인증 실패: {e.Message}");
}
catch (CredentialUnavailableException e)
{
Console.WriteLine($"자격 증명을 사용할 수 없음: {e.Message}");
}
주요 예외
| 예외 | 설명 |
|---|---|
AuthenticationFailedException | 인증 오류의 기본 예외 |
CredentialUnavailableException | 현재 환경에서 자격 증명을 인증할 수 없음 |
AuthenticationRequiredException | 대화형 인증 필요 |
관리 ID 지원
지원되는 Azure 서비스:
- Azure App Service 및 Azure Functions
- Azure Arc
- Azure Cloud Shell
- Azure Kubernetes Service (AKS)
- Azure Service Fabric
- Azure Virtual Machines
- Azure Virtual Machine Scale Sets
스레드 안전성
모든 자격 증명 구현은 스레드로부터 안전합니다. 단일 자격 증명 인스턴스는 여러 클라이언트 및 스레드에서 안전하게 공유할 수 있습니다.
관련 패키지
| 패키지 | 용도 | 설치 |
|---|---|---|
Azure.Identity | 인증 (이 라이브러리) | dotnet add package Azure.Identity |
Microsoft.Extensions.Azure | DI 통합 | dotnet add package Microsoft.Extensions.Azure |
Azure.Identity.Broker | 브로커 인증 | dotnet add package Azure.Identity.Broker |