문제 해결: AgentID 문제에 대한 일반적인 Microsoft Entra SDK

일반적인 SDK 배포 및 운영 문제에 대한 솔루션입니다.

빠른 진단

SDK 상태 확인

# Check if SDK is running
kubectl get pods -l app=myapp

# Check SDK logs
kubectl logs <pod-name> -c sidecar

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

구성 확인

# View SDK environment variables
kubectl exec <pod-name> -c sidecar -- env | grep AzureAd

# Check ConfigMap
kubectl get configmap sidecar-config -o yaml

# Check Secrets
kubectl get secret sidecar-secrets -o yaml

일반적인 문제

컨테이너가 시작되지 않음

증상

Pod가 CrashLoopBackOff 또는 Error 상태로 표시됩니다.

가능성 있는 원인

필수 구성 누락

# Check logs for configuration errors
kubectl logs <pod-name> -c sidecar

# Look for messages like:
# "AzureAd:TenantId is required"
# "AzureAd:ClientId is required"

해결 방법:

# Ensure all required configuration is set
env:
- name: AzureAd__TenantId
  value: "<your-tenant-id>"
- name: AzureAd__ClientId
  value: "<your-client-id>"

잘못된 자격 증명 구성

# Check for credential errors in logs
kubectl logs <pod-name> -c sidecar | grep -i "credential"

해결 방법: 자격 증명 구성 및 Key Vault 또는 비밀에 대한 액세스를 확인합니다.

포트 충돌

# Check if port 5000 is already in use
kubectl exec <pod-name> -c sidecar -- netstat -tuln | grep 5000

해결 방법: 필요한 경우 SDK 포트를 변경합니다.

env:
- name: ASPNETCORE_URLS
  value: "http://+:5001"

401 권한 없음 오류

증상

SDK에 대한 요청은 401 권한 없음을 반환합니다.

가능성 있는 원인

누락된 권한 부여 헤더

# Test with curl
curl -v http://localhost:5000/AuthorizationHeader/Graph
# Should show 401 because no Authorization header

해결 방법: 권한 부여 헤더 포함:

curl -H "Authorization: Bearer <token>" \
  http://localhost:5000/AuthorizationHeader/Graph

유효하지 않거나 만료된 토큰

# Check token claims
kubectl exec <pod-name> -c sidecar -- curl -H "Authorization: Bearer <token>" \
  http://localhost:5000/Validate

해결 방법: Microsoft Entra ID에서 새 토큰을 가져옵니다.

대상 그룹 불일치

# Check logs for audience validation errors
kubectl logs <pod-name> -c sidecar | grep -i "audience"

해결 방법: 대상 그룹 구성이 토큰과 일치하는지 확인합니다.

env:
- name: AzureAd__Audience
  value: "api://<your-api-id>"

범위 유효성 검사 실패

# Check logs for scope errors
kubectl logs <pod-name> -c sidecar | grep -i "scope"

해결 방법: 토큰에 필요한 범위가 포함되어 있는지 확인합니다.

env:
- name: AzureAd__Scopes
  value: "access_as_user"  # Or remove to disable scope validation

자세한 오류를 이해하려면 로그 수준을 늘려야 할 수 있습니다.

Logging__LogLevel__Default=Debug 
Logging__LogLevel__Microsoft.Identity.Web=Debug 
Logging__LogLevel__Microsoft.AspNetCore=Debug 

400 잘못된 요청 - 에이전트 ID 유효성 검사

증상

에이전트 ID 매개 변수가 있는 요청은 400 잘못된 요청을 반환합니다.

오류: AgentIdentity가 없는 AgentUsername

요청:

curl -H "Authorization: Bearer <token>" \
  "http://localhost:5000/AuthorizationHeader/Graph?AgentUsername=user@contoso.com"

오류 응답:

{
  "status": 400,
  "detail": "AgentUsername requires AgentIdentity to be specified"
}

해결 방법: AgentIdentity 매개 변수 포함:

curl -H "Authorization: Bearer <token>" \
  "http://localhost:5000/AuthorizationHeader/Graph?AgentIdentity=<client-id>&AgentUsername=user@contoso.com"

오류: AgentUsername 및 AgentUserId 둘 다 지정됨

요청:

curl -H "Authorization: Bearer <token>" \
  "http://localhost:5000/AuthorizationHeader/Graph?AgentIdentity=<id>&AgentUsername=user@contoso.com&AgentUserId=<oid>"

오류 응답:

{
  "status": 400,
  "detail": "AgentUsername and AgentUserId are mutually exclusive"
}

해결 방법: 다음 중 하나만 사용합니다.

# Use AgentUsername
curl -H "Authorization: Bearer <token>" \
  "http://localhost:5000/AuthorizationHeader/Graph?AgentIdentity=<id>&AgentUsername=user@contoso.com"

# OR use AgentUserId
curl -H "Authorization: Bearer <token>" \
  "http://localhost:5000/AuthorizationHeader/Graph?AgentIdentity=<id>&AgentUserId=<oid>"

오류: 잘못된 AgentUserId 형식

요청:

curl -H "Authorization: Bearer <token>" \
  "http://localhost:5000/AuthorizationHeader/Graph?AgentIdentity=<id>&AgentUserId=invalid-guid"

오류 응답:

{
  "status": 400,
  "detail": "AgentUserId must be a valid GUID"
}

해결 방법: 유효한 GUID를 제공합니다.

curl -H "Authorization: Bearer <token>" \
  "http://localhost:5000/AuthorizationHeader/Graph?AgentIdentity=<id>&AgentUserId=12345678-1234-1234-1234-123456789012"

404 찾을 수 없음 - 서비스가 구성되지 않음

증상

{
  "status": 404,
  "detail": "Downstream API 'UnknownService' not configured"
}

가능성 있는 원인

서비스 이름 오타

# Wrong service name in URL
curl -H "Authorization: Bearer <token>" \
  http://localhost:5000/AuthorizationHeader/Grafh
# Should be "Graph"

해결 방법: 구성에서 올바른 서비스 이름을 사용합니다.

DownstreamApis 구성 누락

해결 방법: 서비스 구성 추가:

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

토큰 획득 실패

증상

토큰을 가져올 때 500 내부 서버 오류가 발생했습니다.

AADSTS 오류 코드

AADSTS50076: Multi-Factor Authentication 필요합니다

AADSTS50076: Due to a configuration change made by your administrator, 
or because you moved to a new location, you must use multi-factor authentication.

해결 방법: 사용자가 MFA를 완료해야 합니다. 이는 조건부 액세스 정책에 대한 예상 동작입니다.

AADSTS65001: 사용자 동의 필요

AADSTS65001: The user or administrator has not consented to use the application.

해결 방법:

1. 애플리케이션에 대한 관리자 동의 요청
2. 위임된 권한이 제대로 구성되었는지 확인

AADSTS700016: 애플리케이션 DLL을 찾을 수 없음

AADSTS700016: Application with identifier '<client-id>' was not found.

해결 방법: ClientId가 올바르고 애플리케이션이 테넌트에 있는지 확인합니다.

AADSTS7000215: 잘못된 클라이언트 암호

AADSTS7000215: Invalid client secret is provided.

해결 방법:

1. 클라이언트 암호가 올바른지 확인
2. 비밀이 만료되었는지 확인
3. 새 비밀 생성 및 구성 업데이트

AADSTS700027: 인증서 또는 프라이빗 키가 구성되지 않음

AADSTS700027: The certificate with identifier '<thumbprint>' was not found.

해결 방법:

1. 인증서가 앱 등록에 등록되었는지 확인
2. SDK에서 인증서 구성 확인
3. 컨테이너에서 인증서에 액세스할 수 있는지 확인

토큰 캐시 문제

해결 방법: 토큰 캐시 지우기 및 다시 시작:

kubectl rollout restart deployment <deployment-name>

분산 캐시의 경우(Redis):

# Clear Redis cache
redis-cli FLUSHDB

네트워크 연결 문제

Microsoft Entra ID에 연결할 수 없음

증상: 토큰을 획득할 때 시간 초과 오류가 발생합니다.

진단:

# Test connectivity from SDK container
kubectl exec <pod-name> -c sidecar -- curl -v https://login.microsoftonline.com

# Check DNS resolution
kubectl exec <pod-name> -c sidecar -- nslookup login.microsoftonline.com

해결 방법:

• 네트워크 정책 확인
• 방화벽 규칙에서 HTTPS가 login.microsoftonline.com에 접근할 수 있도록 설정되어 있는지 확인하십시오.
• DNS가 올바르게 작동하는지 확인

다운스트림 API에 연결할 수 없음

진단:

# Test connectivity to downstream API
kubectl exec <pod-name> -c sidecar -- curl -v https://graph.microsoft.com

# Check configuration
kubectl exec <pod-name> -c sidecar -- env | grep DownstreamApis__Graph__BaseUrl

해결 방법:

• 다운스트림 API URL이 올바른지 확인
• 네트워크 아웃바운드 규칙 확인
• 클러스터에서 API에 액세스할 수 있는지 확인

애플리케이션이 SDK에 연결할 수 없음

증상

애플리케이션은 SDK를 호출할 때 연결 오류를 표시합니다.

진단:

# Test from application container
kubectl exec <pod-name> -c app -- curl -v http://localhost:5000/health

# Check if sidecar is listening
kubectl exec <pod-name> -c sidecar -- netstat -tuln | grep 5000

해결 방법:

• SIDECAR_URL 환경 변수 확인
• SDK가 실행 중인지 확인합니다. kubectl get pods
• 포트 5000이 차단되지 않았는지 확인

성능 문제

느린 토큰 획득

진단:

# Enable detailed logging
# Add to SDK configuration:
# - name: Logging__LogLevel__Microsoft.Identity.Web
#   value: "Debug"

# Check logs for timing information
kubectl logs <pod-name> -c sidecar | grep "Token acquisition"

해결 방법:

1. 토큰 캐시 확인: 캐싱을 사용하도록 설정하고 작동하는지 확인합니다.
2. 리소스 증가: SDK에 더 많은 CPU/메모리 할당
3. 네트워크 대기 시간: Microsoft Entra ID에 대한 대기 시간 확인
4. 연결 풀링: HTTP 연결 재사용 확인

높은 메모리 사용량

진단:

# Check resource usage
kubectl top pod <pod-name> --containers

# Check for memory leaks in logs
kubectl logs <pod-name> -c sidecar | grep -i "memory"

해결 방법:

1. 메모리 제한 늘리기
2. 토큰 캐시 크기 문제 확인
3. 애플리케이션 사용 패턴 검토
4. 여러 복제본에 대한 분산 캐시 고려

인증서 문제

인증서를 찾을 수 없음

증상:

Certificate with thumbprint '<thumbprint>' not found in certificate store.

해결 방법:

• 인증서가 올바르게 탑재되었는지 확인
• 인증서 저장소 경로 확인
• 인증서 권한이 올바른지 확인

인증서 만료됨

증상:

The certificate has expired.

해결 방법:

1. 새 인증서 생성
2. Microsoft Entra ID에 등록
3. SDK 구성 업데이트
4. 컨테이너 다시 배포

Key Vault 액세스 거부됨

증상:

Access denied to Key Vault '<vault-name>'.

해결 방법:

• 관리 ID에 Key Vault에 대한 액세스 정책이 있는지 확인
• Key Vault 방화벽 규칙 확인
• Key Vault에 인증서가 있는지 확인

서명된 SHR(HTTP 요청) 문제

잘못된 PoP 토큰

증상: 다운스트림 API는 PoP 토큰을 거부합니다.

진단:

# Check if PoP token is being requested
kubectl logs <pod-name> -c sidecar | grep -i "pop"

# Verify PopPublicKey is configured correctly
kubectl exec <pod-name> -c sidecar -- env | grep PopPublicKey

해결 방법:

• 공개 키가 base64로 올바르게 인코딩되었는지 확인
• 다운스트림 API가 PoP 토큰을 지원하는지 확인
• PoP 토큰 형식 확인

프라이빗 키 누락

증상: HTTP 요청에 서명할 수 없습니다.

해결 방법: 애플리케이션에서 서명 요청에 프라이빗 키를 사용할 수 있는지 확인합니다.

오류 참조 테이블

디버깅 도구

자세한 로깅 사용

env:
- name: Logging__LogLevel__Default
  value: "Debug"
- name: Logging__LogLevel__Microsoft.Identity.Web
  value: "Trace"
- name: Logging__LogLevel__Microsoft.AspNetCore
  value: "Debug"

경고: 디버그/추적 로깅은 중요한 정보를 기록할 수 있습니다. 개발에서만 사용하거나 프로덕션에서 일시적으로 사용합니다.

테스트 토큰 유효성 검사

# Validate token
curl -H "Authorization: Bearer <token>" \
  http://localhost:5000/Validate | jq .

# Check claims
curl -H "Authorization: Bearer <token>" \
  http://localhost:5000/Validate | jq '.claims'

테스트 토큰 획득

# Get authorization header
curl -H "Authorization: Bearer <token>" \
  http://localhost:5000/AuthorizationHeader/Graph | jq .

# Extract and decode token
curl -H "Authorization: Bearer <token>" \
  http://localhost:5000/AuthorizationHeader/Graph | \
  jq -r '.authorizationHeader' | \
  cut -d' ' -f2 | \
  jwt decode -

Application Insights로 모니터링

구성된 경우:

# Query Application Insights
az monitor app-insights query \
  --app <app-insights-name> \
  --analytics-query "traces | where message contains 'token acquisition' | take 100"

도움말 보기

진단 정보 수집

문제를 열 때 다음을 포함합니다.

1. SDK 버전:

   kubectl describe pod <pod-name> | grep -A 5 "sidecar:"
   

2. 구성 (중요한 데이터 수정):

   kubectl get configmap sidecar-config -o yaml
   

3. 로그 (마지막 100줄):

   kubectl logs <pod-name> -c sidecar --tail=100
   

4. 오류 메시지: SDK의 전체 오류 응답

5. 요청 세부 정보: HTTP 메서드, 엔드포인트, 사용된 매개 변수

지원 리소스

• GitHub 문제: microsoft-identity-web/issues
• Microsoft Q&A: Microsoft ID 플랫폼
• 스택 오버플로: 태그 [microsoft-identity-web]

문제 해결 모범 사례

1. 상태 검사 시작: 항상 SDK가 정상인지 먼저 확인
2. 로그 확인: SDK 로그에 중요한 진단 정보가 포함되어 있습니다.
3. 구성 확인: 필요한 모든 설정이 있고 올바른지 확인
4. 증분 테스트: 간단한 요청으로 시작하고 복잡성을 점진적으로 추가합니다.
5. 상관 관계 ID 사용: 서비스 간 추적을 위한 상관 관계 ID 포함
6. 지속적으로 모니터링: 인증 실패에 대한 경고 설정
7. 문서 문제: 향후 참조를 위해 문제 및 해결에 대한 메모 유지

관련 리소스

• 설치 가이드
• 구성 참조
• 보안 모범 사례
• 자주 묻는 질문(FAQ)