Problembehandlung: Allgemeine Probleme mit dem Microsoft Entra SDK für AgentID

Lösungen für allgemeine SDK-Bereitstellungs- und Betriebsprobleme.

Schnelldiagnose

SDK-Zustand überprüfen

# 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

Konfiguration überprüfen

# 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

Häufige Probleme

Container startet nicht

Symptom

Pod zeigt CrashLoopBackOff oder Error status an.

Mögliche Ursachen

Fehlende erforderliche Konfiguration

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

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

Lösung:

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

Ungültige Konfiguration von Anmeldeinformationen

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

Lösung: Überprüfen Sie die Konfiguration von Anmeldeinformationen und den Zugriff auf Schlüsseltresor oder geheime Schlüssel.

Portkonflikt

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

Lösung: Ändern Sie bei Bedarf den SDK-Port:

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

401 Unberechtigte Fehler

Symptom

Anforderungen an das SDK geben 401 Unauthorized zurück.

Mögliche Ursachen

Fehlender Autorisierungsheader

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

Lösung: Autorisierungsheader einschließen:

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

Ungültiges oder abgelaufenes Token

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

Lösung: Abrufen eines neuen Tokens aus der Microsoft Entra-ID.

Benutzergruppenkonflikt

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

Lösung: Überprüfen sie, ob die Zielgruppenkonfiguration mit dem Token übereinstimmt:

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

Gültigkeitsbereichsprüfungsfehler

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

Lösung: Stellen Sie sicher, dass das Token erforderliche Bereiche enthält:

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

Um die detaillierten Fehler zu verstehen, müssen Sie möglicherweise die Protokollebene erhöhen:

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

400 Ungültige Anforderung – Agent-Identitätsüberprüfung

Symptom

Anforderungen mit Agent-Identitätsparametern geben 400 Ungültige Anforderung zurück.

Fehler: "AgentUsername" ohne "AgentIdentity"

Anforderung

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

Fehlerantwort:

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

Lösung: AgentIdentity-Parameter einschließen:

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

Fehler: "AgentUsername" und "AgentUserId" beide angegeben

Anforderung

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

Fehlerantwort:

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

Lösung: Verwenden Sie nur eine:

# 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>"

Fehler: Ungültiges AgentUserId-Format

Anforderung

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

Fehlerantwort:

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

Lösung: Bereitstellen einer gültigen GUID:

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

404 nicht gefunden – Dienst nicht konfiguriert

Symptom

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

Mögliche Ursachen

Typo des Dienstnamens

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

Lösung: Verwenden Sie den richtigen Dienstnamen aus der Konfiguration.

Fehlende DownstreamApis-Konfiguration

Lösung: Dienstkonfiguration hinzufügen:

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

Tokenerwerbsfehler

Symptom

500 Interner Serverfehler beim Abrufen von Token.

AADSTS-Fehlercodes

AADSTS50076: Mehrstufige Authentifizierung erforderlich

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

Lösung: Der Benutzer muss MFA abschließen. Dies wird für Richtlinien für bedingten Zugriff erwartet.

AADSTS65001: Zustimmung des Benutzers erforderlich

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

Lösung:

1. Anfordern der Administratorzustimmung für die Anwendung
2. Sicherstellen, dass delegierte Berechtigungen ordnungsgemäß konfiguriert sind

AADSTS700016: Anwendung nicht gefunden

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

Lösung: Überprüfen Sie, ob ClientId korrekt ist und die Anwendung im Mandanten vorhanden ist.

AADSTS7000215: Ungültiges Client-Secret

AADSTS7000215: Invalid client secret is provided.

Lösung:

1. Überprüfen, ob der geheime Clientschlüssel korrekt ist
2. Überprüfen, ob der geheime Schlüssel abgelaufen ist
3. Neues Geheimnis generieren und Konfiguration aktualisieren

AADSTS700027: Zertifikat oder privater Schlüssel nicht konfiguriert

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

Lösung:

1. Überprüfen, ob das Zertifikat bei der App-Registrierung registriert ist
2. Überprüfen der Zertifikatkonfiguration im SDK
3. Stellen Sie sicher, dass auf das Zertifikat vom Container aus zugegriffen werden kann.

Token-Cache-Probleme

Lösung: Löschen sie den Tokencache, und starten Sie es neu:

kubectl rollout restart deployment <deployment-name>

Für verteilten Cache (Redis):

# Clear Redis cache
redis-cli FLUSHDB

Netzwerkkonnektivitätsprobleme

Microsoft Entra-ID kann nicht erreicht werden

Symptom: Timeoutfehler beim Abrufen von Tokens.

Diagnose:

# 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

Lösung:

• Überprüfen von Netzwerkrichtlinien
• Überprüfen Sie, ob die Firewallregeln HTTPS-Verbindungen zu login.microsoftonline.com zulassen.
• Sicherstellen, dass DNS ordnungsgemäß funktioniert

Die Verbindung zu nachgeschalteten APIs ist nicht möglich.

Diagnose:

# 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

Lösung:

• Überprüfen, ob die nachgeschaltete API-URL korrekt ist
• Überprüfen Sie die Netzwerkausgangsregeln
• Sicherstellen, dass auf die API über den Cluster zugegriffen werden kann

Die Anwendung kann das SDK nicht erreichen.

Symptom

Die Anwendung zeigt Verbindungsfehler beim Aufrufen des SDK an.

Diagnose:

# 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

Lösung:

• Überprüfen Sie die Umgebungsvariable SIDECAR_URL
• Überprüfen Sie, ob das SDK ausgeführt wird: kubectl get pods
• Sicherstellen, dass Port 5000 nicht blockiert ist

Leistungsprobleme

Langsame Tokenerfassung

Diagnose:

# 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"

Lösungen:

1. Tokencache überprüfen: Sicherstellen, dass zwischenspeichern aktiviert und funktioniert
2. Ressourcen erhöhen: Mehr CPU/Arbeitsspeicher für das SDK zuweisen
3. Netzwerklatenz: Überprüfen Sie die Latenz zu Microsoft Entra-ID
4. Verbindungspooling: Überprüfen der Wiederverwendung von HTTP-Verbindungen

Hohe Speicherauslastung

Diagnose:

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

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

Lösungen:

1. Erhöhen der Speicherbeschränkungen
2. Überprüfen auf Probleme mit der Tokencachegröße
3. Überprüfen von Anwendungsnutzungsmustern
4. Erwägen des verteilten Caches für mehrere Replikate

Zertifikatprobleme

Zertifikat nicht gefunden

Symptom:

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

Lösung:

• Überprüfen Sie, ob das Zertifikat korrekt eingebunden ist
• Überprüfen des Zertifikatspeicherpfads
• Sicherstellen, dass Zertifikatberechtigungen korrekt sind

Zertifikat abgelaufen

Symptom:

The certificate has expired.

Lösung:

1. Generieren eines neuen Zertifikats
2. Registrieren in der Microsoft Entra-ID
3. Die SDK-Konfiguration aktualisieren
4. Erneutes Bereitstellen von Containern

Zugriff auf Key Vault verweigert

Symptom:

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

Lösung:

• Überprüfen, ob die verwaltete Identität über Zugriffsrichtlinie für Key Vault verfügt
• Überprüfen der Firewallregeln des Key Vault
• Sicherstellen, dass das Zertifikat im Key Vault vorhanden ist

Probleme mit signierter HTTP-Anforderung (SHR)

Ungültiges PoP-Token

Symptom: Downstream-API lehnt PoP-Token ab.

Diagnose:

# 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

Lösung:

• Überprüfen, ob der öffentliche Schlüssel ordnungsgemäß base64-codiert ist
• Sicherstellen, dass die downstream-API PoP-Token unterstützt
• Überprüfen des PoP-Tokenformats

Fehlender privater Schlüssel

Symptom: HTTP-Anforderung kann nicht signiert werden.

Lösung: Stellen Sie sicher, dass der private Schlüssel für die Anwendung für Signaturanforderungen verfügbar ist.

Fehlerreferenztabelle

Debugtools

Detaillierte Protokollierung aktivieren

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

Warnung: Die Debug-/Ablaufverfolgungsprotokollierung protokolliert möglicherweise vertrauliche Informationen. Wird nur in der Entwicklung oder vorübergehend in der Produktion verwendet.

Tokenüberprüfung testen

# 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'

Testen der Tokenakquise

# 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 -

Überwachen mit Application Insights

Wenn konfiguriert:

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

Hilfe erhalten

Sammeln von Diagnoseinformationen

Schließen Sie beim Öffnen eines Problems Folgendes ein:

1. SDK-Version:

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

2. Konfiguration (vertrauliche Daten redigieren):

   kubectl get configmap sidecar-config -o yaml
   

3. Protokolle (letzte 100 Zeilen):

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

4. Fehlermeldungen: Vollständige Fehlerantwort aus dem SDK

5. Anforderungsdetails: HTTP-Methode, Endpunkt, verwendete Parameter

Supportressourcen

• GitHub-Probleme: microsoft-identity-web/issues
• Microsoft Q&A: Microsoft Identity Platform
• Stack Overflow: Tag [microsoft-identity-web]

Bewährte Methoden für die Problembehandlung

1. Beginnen Sie mit der Integritätsprüfung: Überprüfen Sie immer, ob das SDK zuerst fehlerfrei ist.
2. Protokolle überprüfen: SDK-Protokolle enthalten wertvolle Diagnoseinformationen
3. Überprüfen der Konfiguration: Stellen Sie sicher, dass alle erforderlichen Einstellungen vorhanden und korrekt sind.
4. Inkrementelles Testen: Beginnen Sie mit einfachen Anforderungen, fügen Sie komplexität schrittweise hinzu
5. Korrelations-IDs verwenden: Korrelations-IDs zur Ablaufverfolgung über Dienste hinweg einfügen
6. Kontinuierlich überwachen: Einrichten von Warnungen für Authentifizierungsfehler
7. Dokumentprobleme: Notizen zu Problemen und Lösungen für zukünftige Referenzen aufbewahren

Verwandte Ressourcen

• Installationshandbuch
• Konfigurationsreferenz
• Bewährte Methoden für Sicherheit
• Häufig gestellte Fragen