설치 가이드: AgentID용 Microsoft Entra SDK 배포

AgentID용 Microsoft Entra SDK는 애플리케이션에 대한 보안 토큰 획득을 간소화하는 컨테이너화된 인증 서비스를 배포할 준비가 된 서비스입니다. 이 설치 가이드에서는 Kubernetes, Docker 및 Azure 환경에서 SDK 컨테이너를 배포하기 위한 단계별 지침을 제공하므로 애플리케이션 코드에 중요한 자격 증명을 직접 포함할 필요가 없습니다.

필수 조건

MCR(Microsoft Container Registry)에 대한 액세스
컨테이너 런타임(Docker, Kubernetes 또는 컨테이너 서비스)
새 앱을 Microsoft Entra 관리 센터에 등록하고, 해당 조직 디렉터리의 계정만을 위해 구성합니다. 애플리케이션 등록에서 자세한 내용을 참조하세요. 다음 값을 애플리케이션 개요 페이지에서 기록하여 나중에 사용하십시오.
- 애플리케이션(클라이언트) ID
- 디렉터리(테넌트) ID
애플리케이션에 대한 자격 증명:
- 안전하게 저장된 클라이언트 암호 또는 인증서(예: Azure Key Vault)
Azure 배포의 경우: Azure CLI 또는 Azure Portal에 대한 액세스

컨테이너 이미지

AgentID용 Microsoft Entra SDK는 MCR에서 컨테이너 이미지로 배포됩니다.

mcr.microsoft.com/entra-sdk/auth-sidecar:<tag>

버전 태그

latest - 안정적인 최신 릴리스
<version> - 특정 버전(예: 1.0.0)
<version>-preview - 미리 보기 릴리스

비고

컨테이너 이미지는 현재 미리 보기로 제공됩니다. GitHub 릴리스에서 최신 버전 태그를 확인합니다.

배포 패턴

AgentID용 Microsoft Entra SDK는 애플리케이션과 함께 도우미 컨테이너로 실행되도록 설계되었습니다. 이렇게 하면 애플리케이션이 HTTP 호출을 통해 토큰 획득 및 관리를 SDK로 오프로드하고 애플리케이션 코드에서 중요한 자격 증명을 유지할 수 있습니다. 다음은 일반적인 배포 패턴이며 특정 환경에 맞게 조정되어야 합니다.

Kubernetes 패턴

보안 Pod-로컬 통신을 위해 애플리케이션 컨테이너와 동일한 Pod에 AgentID용 Microsoft Entra SDK를 배포합니다. 이 패턴은 앱과 함께 인증 서비스를 실행하여 애플리케이션 코드에서 자격 증명을 격리하는 동시에 빠른 HTTP 기반 토큰 획득을 가능하게 합니다.

apiVersion: v1
kind: Pod
metadata:
  # Your application container
  name: myapp
spec:
  containers:
  - name: app
    image: myregistry/myapp:latest
    ports:
    - containerPort: 8080
    env:
    - name: SIDECAR_URL
      value: "http://localhost:5000"
  # Microsoft Entra SDK for AgentID container
  - name: sidecar
    image: mcr.microsoft.com/entra-sdk/auth-sidecar:1.0.0
    ports:
    - containerPort: 5000
    env:
    - name: AzureAd__TenantId
      value: "your-tenant-id"
    - name: AzureAd__ClientId
      value: "your-client-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: "your-cert-name"

Kubernetes 배포

Azure의 Kubernetes 자습서 - Azure Kubernetes Services를 대상으로 지정하려는 경우 AKS(Azure Kubernetes Service)에 대한 애플리케이션 준비 자습서를 참조하세요. 이 패턴은 배포 리소스를 사용하여 애플리케이션 및 AgentID 컨테이너용 Microsoft Entra SDK를 관리하여 크기 조정 및 업데이트를 허용합니다. 또한 배포는 상태 검사 및 리소스 할당을 처리하여 프로덕션 환경에서 안전한 작업을 보장합니다.

apiVersion: apps/v1
kind: Deployment
metadata:
  name: myapp-deployment
spec:
  replicas: 3
  selector:
    matchLabels:
      app: myapp
  template:
    metadata:
      labels:
        app: myapp
    spec:
      serviceAccountName: myapp-sa
      containers:
      - name: app
        image: myregistry/myapp:latest
        ports:
        - containerPort: 8080
        env:
        - name: SIDECAR_URL
          value: "http://localhost:5000"
        resources:
          requests:
            memory: "256Mi"
            cpu: "250m"
          limits:
            memory: "512Mi"
            cpu: "500m"
      
      - name: sidecar
        image: mcr.microsoft.com/entra-sdk/auth-sidecar:1.0.0
        ports:
        - containerPort: 5000
        env:
        - name: AzureAd__TenantId
          valueFrom:
            configMapKeyRef:
              name: app-config
              key: tenant-id
        - name: AzureAd__ClientId
          valueFrom:
            configMapKeyRef:
              name: app-config
              key: client-id
        - name: AzureAd__Instance
          value: "https://login.microsoftonline.com/"
        resources:
          requests:
            memory: "128Mi"
            cpu: "100m"
          limits:
            memory: "256Mi"
            cpu: "250m"
        livenessProbe:
          httpGet:
            path: /health
            port: 5000
          initialDelaySeconds: 10
          periodSeconds: 10
        readinessProbe:
          httpGet:
            path: /health
            port: 5000
          initialDelaySeconds: 5
          periodSeconds: 5

Docker Compose

Docker 환경에서 작업할 때 Docker Compose를 사용하여 다중 컨테이너 애플리케이션을 정의하고 실행할 수 있습니다. 다음 예제에서는 로컬 개발 환경에서 애플리케이션 컨테이너와 함께 AgentID용 Microsoft Entra SDK를 설정하는 방법을 보여 줍니다.

version: '3.8'

services:
  app:
    image: myregistry/myapp:latest
    ports:
      - "8080:8080"
    en - sidecar environment:
      - AzureAd__TenantId=${TENANT_ID}
      - AzureAd__ClientId=${CLIENT_ID}
      - AzureAd__ClientCredentials__0__SourceType=ClientSecret
      - AzureAd__ClientCredentials__0__ClientSecret=${CLIENT_SECRET}
    networks:
      - app-network

networks:
  app-network:
    driver: bridge

관리 ID를 사용하는 AKS(Azure Kubernetes Service)

AKS에 배포할 때 Azure 관리 ID 를 사용하여 구성에 자격 증명을 저장하지 않고 AgentID용 Microsoft Entra SDK를 인증할 수 있습니다. 먼저 AKS 클러스터에서 Azure AD 워크로드 ID를 사용하도록 설정하고 관리 ID에 대한 페더레이션 ID 자격 증명을 만들어야 합니다. 그런 다음 인증에 관리 ID를 사용하도록 SDK를 구성합니다.

1단계: 관리 ID 만들기

관리 ID를 만들고 적절한 권한을 할당합니다.

# Create managed identity
az identity create \
  --resource-group myResourceGroup \
  --name myapp-identity

# Get the identity details
IDENTITY_CLIENT_ID=$(az identity show \
  --resource-group myResourceGroup \
  --name myapp-identity \
  --query clientId -o tsv)

IDENTITY_OBJECT_ID=$(az identity show \
  --resource-group myResourceGroup \
  --name myapp-identity \
  --query principalId -o tsv)

2단계: 권한 할당

다운스트림 API에 액세스할 수 있는 관리 ID 권한을 부여합니다.

# Example: Grant permission to call Microsoft Graph
az ad app permission add \
  --id $IDENTITY_CLIENT_ID \
  --api 00000003-0000-0000-c000-000000000000 \
  --api-permissions e1fe6dd8-ba31-4d61-89e7-88639da4683d=Scope

3단계: 워크로드 ID 구성

워크로드 ID 페더레이션을 사용하여 서비스 계정을 만듭니다.

export AKS_OIDC_ISSUER=$(az aks show \
  --resource-group myResourceGroup \
  --name myAKSCluster \
  --query "oidcIssuerProfile.issuerUrl" -o tsv)

az identity federated-credential create \
  --name myapp-federated-identity \
  --identity-name myapp-identity \
  --resource-group myResourceGroup \
  --issuer $AKS_OIDC_ISSUER \
  --subject system:serviceaccount:default:myapp-sa

4단계: 워크로드 ID를 사용하여 배포

다음 배포 예제에서 AgentID용 Microsoft Entra SDK는 파일 기반 토큰 프로젝션을 사용하여 인증에 Azure AD 워크로드 ID를 사용하도록 구성됩니다. 자격 증명 형식은 SignedAssertionFilePath 워크로드 ID 웹후크에서 프로젝션된 파일에서 토큰을 읽습니다.

apiVersion: v1
kind: ServiceAccount
metadata:
  name: myapp-sa
  namespace: default
  annotations:
    azure.workload.identity/client-id: "<MANAGED_IDENTITY_CLIENT_ID>"

---
apiVersion: apps/v1
kind: Deployment
metadata:
  name: myapp-deployment
spec:
  template:
    metadata:
      labels:
        azure.workload.identity/use: "true"
    spec:
      serviceAccountName: myapp-sa
      containers:
      - name: app
        image: myregistry/myapp:latest
        env:
        - name: SIDECAR_URL
          value: "http://localhost:5000"
      
      - name: sidecar
        image: mcr.microsoft.com/entra-sdk/auth-sidecar:1.0.0
        ports:
        - containerPort: 5000
        env:
        - name: AzureAd__TenantId
          value: "your-tenant-id"
        - name: AzureAd__ClientId
          value: "<MANAGED_IDENTITY_CLIENT_ID>"
        
        # Workload Identity credentials - uses file-based token projection
        - name: AzureAd__ClientCredentials__0__SourceType
          value: "SignedAssertionFilePath"

참고: 워크로드 아이덴티티 웹후크는 Pod에 필요한 레이블 및 서비스 계정 주석이 있는 경우 페더레이션된 토큰을 /var/run/secrets/azure/tokens/azure-identity-token 또는 환경 변수로 자동으로 투영합니다.

네트워크 구성

에이전트 ID용 Microsoft Entra SDK와 외부 서비스 간의 보안 통신을 보장하면서 무단 액세스를 제한하려면 올바른 네트워크 구성이 필요합니다. 적절한 구성은 보안 취약성을 방지하고 Microsoft Entra ID 엔드포인트에 대한 안정적인 연결을 보장합니다. 배포 환경에 따라 SDK에 대한 네트워크 액세스를 구성하려면 다음 지침을 사용합니다.

내부 통신만

내부 Pod-local 통신에 대해서만 AgentID용 Microsoft Entra SDK를 구성하려면 사용자 환경에 따라 애플리케이션의 엔드포인트 URL을 localhost 가리키거나 127.0.0.1가리키도록 설정합니다.

containers:
- name: sidecar
  env:
  - name: Kestrel__Endpoints__Http__Url
    value: "http://127.0.0.1:5000" # Same pod, localhost communication

주의

LoadBalancer나 인그레스를 통해 Microsoft Entra SDK for AgentID를 외부에 노출하지 마세요. 애플리케이션 컨테이너에서만 액세스할 수 있어야 합니다.

네트워크 정책

네트워크 액세스를 추가로 제한하려면 Kubernetes 네트워크 정책을 구현하여 SDK 컨테이너 간 트래픽을 제한하는 것이 좋습니다.

apiVersion: networking.k8s.io/v1
kind: NetworkPolicy
metadata:
  name: sidecar-network-policy
spec:
  podSelector:
    matchLabels:
      app: myapp
  policyTypes:
  - Ingress
  - Egress
  ingress:
  # No external ingress rules - only pod-local communication
  egress:
  - to:
    - namespaceSelector:
        matchLabels:
          name: kube-system
    ports:
    - protocol: TCP
      port: 53  # DNS
  - to:
    - podSelector: {}
  - to:
    # Allow outbound to Microsoft Entra ID
    ports:
    - protocol: TCP
      port: 443

상태 검사

AgentID용 Microsoft Entra SDK는 활동성 및 준비 상태 프로브에 대한 엔드포인트를 노출 /health 하여 컨테이너가 안전하게 실행되도록 합니다. 다음 프로브를 포함하도록 배포를 구성합니다.

livenessProbe:
  httpGet:
    path: /health
    port: 5000
  initialDelaySeconds: 10
  periodSeconds: 10

readinessProbe:
  httpGet:
    path: /health
    port: 5000
  initialDelaySeconds: 5
  periodSeconds: 5

리소스 요구 사항

권장되는 리소스 할당은 다음과 같지만 토큰 획득 빈도, 구성된 다운스트림 API 수 및 캐시 크기 요구 사항에 따라 조정해야 합니다.

리소스 프로필	Memory	CPU (중앙 처리 장치)
최소	128Mi	100미터
Recommended	256Mi	250m
트래픽이 높음	512Mi	500m

크기 조정 고려 사항

AgentID용 Microsoft Entra SDK는 애플리케이션을 사용하여 크기를 조정하도록 설계되었습니다.

상태 비지정 디자인: 각 SDK 인스턴스는 자체 토큰 캐시를 유지 관리합니다.
수평 크기 조정: 애플리케이션 Pod를 더 추가하여 크기 조정(각각 자체 SDK 인스턴스 포함)
캐시 온난화: 트래픽이 많은 시나리오에 대한 캐시 온난화 전략을 구현하는 것이 좋습니다.

배포 문제 해결

발생할 수 있는 일반적인 문제는 잘못된 구성 값, Microsoft Entra ID에 대한 네트워크 연결 또는 누락된 자격 증명 또는 인증서 때문일 수 있습니다. 관리 ID 또는 서비스 주체에 올바른 애플리케이션 권한, 관리자 동의 부여(필요한 경우) 및 올바른 역할 할당이 있는지 확인합니다.

다음은 배포 문제를 해결하는 데 도움이 되는 몇 가지 일반적인 문제 해결 단계입니다.

컨테이너가 시작되지 않음

컨테이너 로그 확인:

kubectl logs <pod-name> -c sidecar

상태 검사 실패

AgentID용 Microsoft Entra SDK가 응답하고 있는지 확인합니다.

kubectl exec <pod-name> -c sidecar -- curl http://localhost:5000/health

문제 해결에 대한 자세한 단계는 문제 해결 가이드를 참조하세요.

다음 단계

설정 구성 - ID 구성 설정
엔드포인트 검토 - HTTP API 탐색
보안 모범 사례 - 배포 강화
시나리오 선택 - 안내 예제로 시작

피드백

이 페이지가 도움이 되었나요?

Last updated on 2025-11-14