구성 참조: AgentID 설정에 대한 Microsoft Entra SDK

이 가이드에서는 컨테이너화된 환경에서 애플리케이션에 대한 토큰 획득 및 관리를 처리하는 컨테이너화된 인증 서비스인 AgentID용 Microsoft Entra SDK에 대한 구성 옵션을 제공합니다. SDK는 애플리케이션이 인증 라이브러리를 직접 포함할 필요 없이 Microsoft Entra ID 인증, OBO(On-Behalf-of) 토큰 흐름 및 다운스트림 API 호출을 관리하여 ID 통합을 간소화합니다.

이 가이드에서는 Kubernetes 배포 패턴에 중점을 두지만 Docker, Azure Container Instances 및 기타 컨테이너 오케스트레이션 플랫폼을 비롯한 컨테이너화된 환경에서 SDK를 배포할 수 있습니다.

AKS(Azure Kubernetes Service)에 배포하거나, 개발 환경을 설정하거나, 프로덕션 워크로드를 구성하는 경우 이 참조에서는 Microsoft Entra ID를 사용하여 애플리케이션을 보호하는 데 필요한 구성 패턴, 자격 증명 유형 및 환경 변수를 다룹니다.

구성 개요

AgentID용 Microsoft Entra SDK는 ASP.NET Core 규칙에 따라 구성 원본을 사용하여 구성됩니다. 구성 값은 다음을 비롯한 여러 메서드를 통해 제공할 수 있습니다.

• 환경 변수(Kubernetes에 권장)
• Entra ID 구성 - appsettings.json 컨테이너에 연결되거나 yaml 파일에 포함된 파일입니다.
• 명령줄 인수
• Azure App Configuration 또는 Key Vault(고급 시나리오의 경우)

핵심 엔트라 ID 설정

에이전트 ID 배포용 Microsoft Entra SDK는 들어오는 토큰을 인증하고 다운스트림 API에 대한 토큰을 획득하기 위해 핵심 Entra ID 설정이 필요합니다. 보안 인증을 보장하려면 일반적으로 환경 변수로 다음 YAML 형식의 적절한 클라이언트 자격 증명을 사용합니다.

필수 구성

먼저 들어오는 토큰을 인증하고 다운스트림 API에 대한 토큰을 획득하도록 SDK에 대한 핵심 Entra ID 설정을 구성합니다.

env:
- name: AzureAd__Instance
  value: "https://login.microsoftonline.com/"
- name: AzureAd__TenantId
  value: "<your-tenant-id>"
- name: AzureAd__ClientId
  value: "<your-client-id>"

클라이언트 자격 증명 구성

AgentID용 Microsoft Entra SDK는 다운스트림 API에 대한 토큰을 획득할 때 Microsoft Entra ID로 인증하기 위한 여러 클라이언트 자격 증명 유형을 지원합니다. 배포 환경 및 보안 요구 사항에 가장 적합한 자격 증명 유형을 선택하고 선택한 구성이 시나리오에 적합한지 확인합니다.

각 자격 증명 형식은 다음과 같은 다양한 시나리오를 제공합니다.

• 클라이언트 암호: 개발 및 테스트를 위한 간단한 설정(프로덕션에는 권장되지 않음)
• Key Vault 인증서: 중앙 집중식 인증서 관리가 있는 프로덕션 환경
• 파일 인증서: 인증서가 파일로 탑재되는 경우(예: Kubernetes 비밀을 통해)
• 인증서 저장소: 인증서 저장소가 있는 Windows 환경
• 컨테이너용 워크로드 ID: 파일 기반 토큰 프로젝션과 함께 Azure AD 워크로드 ID를 사용하여 AKS에 권장됨
• VM/App Services용 관리 ID: 시스템 또는 사용자 할당 관리 ID가 있는 Azure Virtual Machines 및 App Services(컨테이너용이 아님)

다음 YAML 형식으로 하나 이상의 자격 증명 원본을 구성합니다.

클라이언트 암호

이 구성은 서비스 대 서비스 인증을 위해 클라이언트 암호를 사용하여 Entra ID 인증을 설정합니다.

- name: AzureAd__ClientCredentials__0__SourceType
  value: "ClientSecret"
- name: AzureAd__ClientCredentials__0__ClientSecret
  value: "<your-client-secret>"

Key Vault의 인증서

이 구성은 Azure Key Vault에 저장된 인증서를 사용하여 Entra ID 인증을 설정합니다.

- name: AzureAd__ClientCredentials__0__SourceType
  value: "KeyVault"
- name: AzureAd__ClientCredentials__0__KeyVaultUrl
  value: "https://<your-keyvault>.vault.azure.net"
- name: AzureAd__ClientCredentials__0__KeyVaultCertificateName
  value: "<certificate-name>"

파일의 인증서

이 구성은 파일로 저장된 인증서를 사용하여 Entra ID 인증을 설정합니다.

- name: AzureAd__ClientCredentials__0__SourceType
  value: "Path"
- name: AzureAd__ClientCredentials__0__CertificateDiskPath
  value: "/path/to/certificate.pfx"
- name: AzureAd__ClientCredentials__0__CertificatePassword
  value: "<certificate-password>"

저장소의 인증서

이 구성은 로컬 인증서 저장소의 인증서를 사용하여 Entra ID 인증을 설정합니다.

- name: AzureAd__ClientCredentials__0__SourceType
  value: "StoreWithThumbprint"
- name: AzureAd__ClientCredentials__0__CertificateStorePath
  value: "CurrentUser/My"
- name: AzureAd__ClientCredentials__0__CertificateThumbprint
  value: "<thumbprint>"

컨테이너에 대한 워크로드 ID(AKS에 권장)

이 구성은 AKS(컨테이너화된 배포)에 Azure AD 워크로드 ID를 사용하여 Entra ID 인증을 설정합니다. 이는 파일 기반 토큰 프로젝션을 사용하므로 컨테이너 기반 시나리오에 권장되는 방법입니다.

- name: AzureAd__ClientCredentials__0__SourceType
  value: "SignedAssertionFilePath"

참고: Pod가 서비스 계정 주석 및 Pod 레이블로 올바르게 구성되면 토큰 파일 경로 /var/run/secrets/azure/tokens/azure-identity-token 또는 환경 변수가 Azure 워크로드 ID 웹후크에 의해 자동으로 프로젝션됩니다. 전체 설치 지침은 관리 ID 사용을 참조하세요.

VM 및 App Services에 대한 관리 ID

Virtual Machines 또는 App Services(컨테이너 아님)의 클래식 Azure 관리 ID 시나리오의 경우 다음을 사용합니다 SignedAssertionFromManagedIdentity.

- name: AzureAd__ClientCredentials__0__SourceType
  value: "SignedAssertionFromManagedIdentity"
- name: AzureAd__ClientCredentials__0__ManagedIdentityClientId
  value: "<managed-identity-client-id>"

중요: 컨테이너화된 환경(Kubernetes, AKS, Docker)에는 사용하지 SignedAssertionFromManagedIdentity 마세요. AKS의 경우 위에 표시된 대로 사용합니다 SignedAssertionFilePath . Kubernetes 및 Docker의 경우 클라이언트 인증서를 사용합니다. 자세한 내용은 를 참조 https://aka.ms/idweb/client-credentials

추가 리소스

모든 자격 증명 구성 옵션 및 해당 사용에 대한 자세한 내용은 microsoft-identity-abstractions-for-dotnet 리포지토리의 CredentialDescription 사양 을 참조하세요.

자격 증명 우선 순위

우선 순위 기반 선택을 사용하여 여러 자격 증명을 구성합니다.

# First priority - Key Vault certificate
- name: AzureAd__ClientCredentials__0__SourceType
  value: "KeyVault"
- name: AzureAd__ClientCredentials__0__KeyVaultUrl
  value: "https://prod-keyvault.vault.azure.net"
- name: AzureAd__ClientCredentials__0__KeyVaultCertificateName
  value: "prod-cert"

# Second priority - Client secret (fallback)
- name: AzureAd__ClientCredentials__1__SourceType
  value: "ClientSecret"
- name: AzureAd__ClientCredentials__1__ClientSecret
  valueFrom:
    secretKeyRef:
      name: app-secrets
      key: client-secret

AgentID용 Microsoft Entra SDK는 숫자 순서(0, 1, 2 등)로 자격 증명을 평가하고 성공적으로 인증하는 첫 번째 자격 증명을 사용합니다.

다운스트림 API 구성

애플리케이션이 OBO(On-Behalf-of) 토큰 흐름을 사용하여 호출해야 하는 다운스트림 API를 구성합니다. AgentID용 Microsoft Entra SDK는 토큰 획득을 관리하고 이러한 API 호출에 대한 인증 헤더를 제공합니다. 각 다운스트림 API에는 토큰 획득 및 HTTP 요청 처리를 위한 고유한 구성 이름 및 특정 매개 변수가 필요합니다.

기본 URL, 필수 범위 및 선택적 매개 변수를 사용하여 각 다운스트림 API를 정의합니다. SDK는 들어오는 사용자 토큰을 사용하여 토큰 획득을 자동으로 처리하고 애플리케이션의 API 호출에 적절한 권한 부여 헤더를 제공합니다.

- name: DownstreamApis__Graph__BaseUrl
  value: "https://graph.microsoft.com/v1.0"
- name: DownstreamApis__Graph__Scopes
  value: "User.Read Mail.Read"
- name: DownstreamApis__Graph__RelativePath
  value: "/me"

- name: DownstreamApis__MyApi__BaseUrl
  value: "https://api.contoso.com"
- name: DownstreamApis__MyApi__Scopes
  value: "api://myapi/.default"

토큰 획득 옵션

토큰 획득 동작을 미세 조정합니다.

- name: DownstreamApis__Graph__AcquireTokenOptions__Tenant
  value: "<specific-tenant-id>"

- name: DownstreamApis__Graph__AcquireTokenOptions__AuthenticationScheme
  value: "Bearer"

- name: DownstreamApis__Graph__AcquireTokenOptions__CorrelationId
  value: "<correlation-id>"

서명된 SHR(HTTP 요청) 구성

보안 강화를 위해 서명된 HTTP 요청을 사용하도록 설정합니다.

- name: DownstreamApis__SecureApi__AcquireTokenOptions__PopPublicKey
  value: "<base64-encoded-public-key>"

- name: DownstreamApis__SecureApi__AcquireTokenOptions__PopClaims
  value: '{"custom_claim": "value"}'

로깅 구성

로깅 수준 구성:

- name: Logging__LogLevel__Default
  value: "Information"
- name: Logging__LogLevel__Microsoft.Identity.Web
  value: "Debug"
- name: Logging__LogLevel__Microsoft.AspNetCore
  value: "Warning"

ASP.NET Core 설정

- name: ASPNETCORE_ENVIRONMENT
  value: "Production"
- name: ASPNETCORE_URLS
  value: "http://+:5000"

Per-Request 구성 재정의

모든 토큰 획득 엔드포인트는 쿼리 매개 변수를 수락하여 구성을 재정의합니다.

# Override scopes
GET /AuthorizationHeader/Graph?optionsOverride.Scopes=User.Read&optionsOverride.Scopes=Mail.Read

# Request app token instead of OBO
GET /AuthorizationHeader/Graph?optionsOverride.RequestAppToken=true

GET /AuthorizationHeaderUnauthenticated/Graph?optionsOverride.RequestAppToken=true

# Override tenant
GET /AuthorizationHeader/Graph?optionsOverride.AcquireTokenOptions.Tenant=<tenant-id>

# Override relative path
GET /DownstreamApi/Graph?optionsOverride.RelativePath=me/messages

# Enable SHR for this request
GET /AuthorizationHeader/Graph?optionsOverride.AcquireTokenOptions.PopPublicKey=<base64-key>

에이전트 ID 재정의

요청 시 에이전트 ID를 지정합니다.

# Autonomous agent
GET /AuthorizationHeader/Graph?AgentIdentity=<agent-client-id>

# Autonomous agent with specific agent user identity (by username)
GET /AuthorizationHeader/Graph?AgentIdentity=<agent-client-id>&AgentUsername=user@contoso.com

# Autonomous agent with specific agent user identity (by object ID)
GET /AuthorizationHeader/Graph?AgentIdentity=<agent-client-id>&AgentUserId=<user-object-id>

중요 규칙:

• AgentUsername 및 AgentUserId 필요 AgentIdentity
• AgentUsername 상호 AgentUserId 배타적입니다.

자세한 의미 체계는 에이전트 ID 를 참조하세요.

전체 구성 예제

다음은 구성과 비밀을 적절히 분리하여 SDK를 배포하는 방법을 보여 주는 프로덕션 준비 예제를 제공합니다. 이 예제에서는 여러 다운스트림 API를 구성하고, 민감하지 않은 설정에 Kubernetes ConfigMaps를 사용하고, 비밀에 자격 증명을 안전하게 저장하고, 보안 배포를 위해 환경별 구성을 적용하는 방법을 보여 줍니다.

이 패턴은 구성 데이터를 중요한 자격 증명에서 분리하여 보안을 유지하면서 다양한 환경을 효과적으로 관리할 수 있도록 하는 Kubernetes 모범 사례를 따릅니다.

Kubernetes ConfigMap

ConfigMap은 Entra ID 설정, 다운스트림 API 및 로깅 수준을 포함하여 SDK에 대한 중요하지 않은 구성 설정을 저장합니다.

apiVersion: v1
kind: ConfigMap
metadata:
  name: sidecar-config
data:
  ASPNETCORE_ENVIRONMENT: "Production"
  ASPNETCORE_URLS: "http://+:5000"
  
  AzureAd__Instance: "https://login.microsoftonline.com/"
  AzureAd__TenantId: "common"
  AzureAd__ClientId: "your-app-client-id"
  AzureAd__Scopes: "access_as_user"
  
  DownstreamApis__Graph__BaseUrl: "https://graph.microsoft.com/v1.0"
  DownstreamApis__Graph__Scopes: "User.Read Mail.Read"
  
  DownstreamApis__MyApi__BaseUrl: "https://api.contoso.com"
  DownstreamApis__MyApi__Scopes: "api://myapi/.default"
  
  Logging__LogLevel__Default: "Information"
  Logging__LogLevel__Microsoft.Identity.Web: "Debug"

Kubernetes 비밀

비밀은 ConfigMap과 별도로 클라이언트 비밀과 같은 중요한 자격 증명을 저장합니다.

apiVersion: v1
kind: Secret
metadata:
  name: sidecar-secrets
type: Opaque
stringData:
  AzureAd__ClientCredentials__0__ClientSecret: "your-client-secret"

ConfigMap 및 비밀을 사용하여 배포

배포는 ConfigMap 및 Secret을 모두 SDK 컨테이너에 탑재하여 구성과 자격 증명이 제대로 구분되도록 합니다.

apiVersion: apps/v1
kind: Deployment
metadata:
  name: myapp
spec:
  template:
    spec:
      containers:
      - name: sidecar
        image: mcr.microsoft.com/entra-sdk/auth-sidecar:1.0.0
        envFrom:
        - configMapRef:
            name: sidecar-config
        - secretRef:
            name: sidecar-secrets

환경별 구성

배포 환경에 대한 보안, 로깅 및 테넌트 격리를 조정하도록 환경별 설정을 구성합니다. 각 환경에는 개발 효율성, 스테이징 유효성 검사 및 프로덕션 보안 요구 사항의 균형을 맞추기 위해 다양한 구성 접근 방식이 필요합니다.

발달

- name: ASPNETCORE_ENVIRONMENT
  value: "Development"
- name: Logging__LogLevel__Default
  value: "Debug"
- name: AzureAd__TenantId
  value: "<dev-tenant-id>"

Staging

- name: ASPNETCORE_ENVIRONMENT
  value: "Staging"
- name: Logging__LogLevel__Default
  value: "Information"
- name: AzureAd__TenantId
  value: "<staging-tenant-id>"

프로덕션

- name: ASPNETCORE_ENVIRONMENT
  value: "Production"
- name: Logging__LogLevel__Default
  value: "Warning"
- name: Logging__LogLevel__Microsoft.Identity.Web
  value: "Information"
- name: AzureAd__TenantId
  value: "<prod-tenant-id>"
- name: ApplicationInsights__ConnectionString
  value: "<app-insights-connection>"

Validation

AgentID용 Microsoft Entra SDK는 시작 시 구성의 유효성을 검사하고 다음 사항에 대한 오류를 기록합니다.

• 필수 설정 누락(TenantId, ClientId)
• 잘못된 자격 증명 구성
• 잘못된 형식의 다운스트림 API 정의
• URL 또는 범위 형식이 잘못되었습니다.

컨테이너 로그에서 유효성 검사 메시지를 확인합니다.

kubectl logs <pod-name> -c sidecar

모범 사례

1. 자격 증명에 비밀 사용: Kubernetes 비밀 또는 Azure Key Vault에 클라이언트 비밀 및 인증서를 저장합니다. 참고 항목 https://aka.ms/msidweb/client-credentials
2. 환경별 별도 구성: ConfigMaps를 사용하여 환경별 설정 관리
3. 적절한 로깅 사용: 개발 시 디버그 로깅 사용, 프로덕션 환경에서 정보/경고 사용
4. 상태 검사 구성: 상태 검사 엔드포인트가 제대로 구성되었는지 확인
5. 컨테이너용 워크로드 ID 사용: AKS(컨테이너화된 배포)의 경우 보안 강화를 위해 클라이언트 비밀보다 Azure AD 워크로드 ID SignedAssertionFilePath 를 사용하는 것이 좋습니다.
6. VM/App Services에 관리 ID 사용: Azure VM 및 App Services의 경우 시스템 또는 사용자가 할당한 관리 ID를 사용합니다.
7. 배포 시 유효성 검사: 프로덕션 배포 전 스테이징에서 구성 테스트

또한 참조하십시오

• 에이전트 ID
• 엔드포인트 참조
• 보안 모범 사례
• Troubleshooting