Häufig gestellte Fragen zum Microsoft Entra SDK für AgentID

Allgemeine Fragen

Was ist das Microsoft Entra SDK für AgentID?

Das Microsoft Entra SDK für AgentID ist ein containerisierter Webdienst, der Tokenakquisition, Validierung und sichere nachgeschaltete API-Aufrufe verarbeitet. Sie wird zusammen mit Ihrer Anwendung als Begleitcontainer ausgeführt, sodass Sie identitätslogik in einen dedizierten Dienst entladen können. Durch die Zentrale von Identitätsvorgängen im SDK müssen Sie keine komplexe Tokenverwaltungslogik in jeden Dienst einbetten, wodurch die Codeduplizierung und potenzielle Sicherheitsrisiken reduziert werden.

Warum sollte ich das Microsoft Entra SDK für AgentID anstelle von Microsoft.Identity.Web verwenden?

Merkmal	Microsoft.Identity.Web	Microsoft Entra SDK für AgentID
Sprachunterstützung	Nur C# / .NET	Jede Sprache (HTTP)
Deployment	In-Process-Bibliothek	Separater Container
Tokenerwerb	✅ Direkte MSAL.NET	✅ Über HTTP-API
Tokenzwischenspeicherung	✅Im Arbeitsspeicher verteilt ✅	✅Im Arbeitsspeicher verteilt ❌
OBO-Fluss	✅ Eingebaute Unterstützung	✅ Über HTTP-Endpunkt
Clientanmeldeinformationen	✅ Eingebaute Unterstützung	✅ Über HTTP-Endpunkt
Verwaltete Identität	✅ Direkter Support	✅ Direkter Support
Agentidentitäten	✅ Über Erweiterungen	✅ Abfrageparameter
Tokenüberprüfung	✅ Middleware	✅ /Validate-Endpunkt
Downstream-API	✅ IDownstreamApi	✅ /DownstreamApi-Endpunkt
Microsoft Graph	✅ Graph SDK-Integration	⚠– Via DownstreamApi
Leistung	⚡ Prozessintern (am schnellsten)	🔄 HTTP-Overhead
Configuration	`appsettings.json` und Code	`appsettings.json` und Umgebungsvariablen
Debuggen	✅ Standardmäßiges .NET-Debugging	⚠– Containerdebugging
Neuladen im laufenden Betrieb	✅ .NET Hot Reload (Direktes Neuladen)	❌ Containerneustart
Paketupdates	📦 NuGet-Pakete	🐳 Containerimages
Lizenz	MIT	MIT

Ausführliche Anleitungen finden Sie im Vergleichshandbuch .

Ist das Microsoft Entra SDK für AgentID produktionsbereit?

Ja, das SDK ist produktionsbereit. Weitere Informationen finden Sie in den GitHub-Versionen für die neuesten Versionsstatus- und Produktionsbereitschaftsrichtlinien.

Sind Containerimages verfügbar?

Ja – Informationen zu verfügbaren Images und Versionstags finden Sie im Installationshandbuch .

Kann ich das SDK außerhalb von Kubernetes ausführen?

Ja – Anweisungen zum Ausführen des SDK in Docker Compose oder anderen Containerumgebungen finden Sie im Installationshandbuch (Docker Compose, Azure Container Instances, AWS ECS/Fargate, Standalone Docker).

Welche Netzwerkports verwendet das SDK?

Standardport: 5000 (konfigurierbar)

Auf das SDK sollte nur über Ihren Anwendungscontainer zugegriffen werden, der nicht extern verfügbar gemacht wird.

Einsatz

Erfahren Sie mehr über Bereitstellungsoptionen, Ressourcenanforderungen und integration in Containerplattformen wie Docker Compose und Kubernetes.

Was sind die Ressourcenanforderungen?

Ja – siehe Installationshandbuch für Ressourcenanforderungen.

Kann ich das SDK mit Docker Compose verwenden?

Ja – siehe Installationshandbuch für Docker Compose-Beispiele.

Wie kann ich in AKS mit verwalteter Identität bereitstellen?

Ja – Folgen Sie dem Installationshandbuch im Azure Kubernetes-Dienst (AKS) mit verwalteter Identität .

Konfiguration

Konfigurieren Sie die SDK-Einstellungen, einschließlich Anmeldeinformationen, downstream-APIs und Anforderungsüberschreibungen, um Ihren Bereitstellungsanforderungen zu entsprechen.

Ist ein Konfigurationsverweis verfügbar?

Ja – detaillierte Konfigurationsoptionen finden Sie in der Konfigurationsreferenz .

Sollte ich geheime Clientschlüssel oder Zertifikate verwenden?

Bevorzugen Sie Zertifikate gegenüber geheimen Clientschlüsseln:

Sicherer
Einfachere Drehung
Empfohlen von Microsoft

Optimal: Verwenden von verwalteter Identität in Azure (keine Anmeldeinformationen erforderlich)

Anleitungen finden Sie unter "Bewährte Methoden für die Sicherheit ".

Kann ich mehrere downstream-APIs konfigurieren?

Ja. Konfigurieren Sie jeden mit einem eigenen Abschnitt:

DownstreamApis__Graph__BaseUrl: "https://graph.microsoft.com/v1.0"
DownstreamApis__Graph__Scopes: "User.Read"

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

Wie überschreibt ich die Konfiguration pro Anforderung?

Verwenden von Abfrageparametern für Endpunkte:

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

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

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

Weitere Informationen finden Sie in der Konfigurationsreferenz für alle Optionen.

Agentidentitäten

Agentidentitäten ermöglichen Szenarien, in denen eine Agentanwendung autonom oder im Auftrag eines Benutzers mit ordnungsgemäßer Kontextisolation und Bereichsdefinition ausgeführt werden kann.

Was sind Agentidentitäten?

Agentidentitäten ermöglichen Szenarien, in denen eine Agentanwendung entweder agiert:

Autonom - im eigenen Anwendungskontext
Interaktiv – im Namen des Benutzers, der ihn aufgerufen hat

Eine umfassende Dokumentation finden Sie unter Agent-Identitäten .

Wann sollte ich den autonomen Agent-Modus verwenden?

Verwenden Sie den autonomen Agent-Modus für:

Batchverarbeitung ohne Benutzerkontext
Hintergrundaufgaben
System-zu-System-Vorgänge
Geplante Aufträge

Beispiel:

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

Wann sollte ich den interaktiven Agent-Modus verwenden?

Verwenden Sie den delegierten Agent-Modus für:

Interaktive Agent-Anwendungen
KI-Assistenten, die im Auftrag von Benutzern handeln
Benutzerweite Automatisierung
Personalisierte Workflows

Beispiel:

GET /AuthorizationHeader/Graph?AgentIdentity=<agent-client-id>&AgentUsername=user@contoso.com

Warum kann ich AgentUsername nicht ohne AgentIdentity verwenden?

AgentUsername ist ein Modifizierer, der angibt, welchen Benutzer der Agent im Auftrag von. Es muss AgentIdentity angegeben werden, welcher Agentkontext verwendet werden soll. Ohne AgentIdentity, hat der Parameter keine Bedeutung.

Warum schließen sich AgentUsername und AgentUserId gegenseitig aus?

Sie sind zwei Möglichkeiten, denselben Benutzer zu identifizieren:

AgentUsername - Benutzerprinzipalname (UPN)
AgentUserId - Objekt-ID (OID)

Beides ermöglicht Mehrdeutigkeit. Wählen Sie das Szenario aus, das ihrem Szenario entspricht:

Wird verwendet AgentUsername , wenn Sie über den UPN des Benutzers verfügen
Verwenden, AgentUserId wenn Sie über die Objekt-ID des Benutzers verfügen

API-Verwendung

Das SDK macht mehrere HTTP-Endpunkte für Tokenakquisition, Validierung und nachgeschaltete API-Aufrufe verfügbar, die sowohl authentifizierte als auch nicht authentifizierte Flüsse unterstützen.

Welche Endpunkte macht das SDK verfügbar?

/Validate – Überprüfen von Token- und Rückgabeansprüchen
/AuthorizationHeader/{serviceName} - Autorisierungsheader mit Token abrufen
/AuthorizationHeaderUnauthenticated/{serviceName} – Abrufen eines Tokens ohne eingehendes Benutzertoken
/DownstreamApi/{serviceName} – Direktes Aufrufen der downstream-API
/DownstreamApiUnauthenticated/{serviceName} – Aufrufen der downstream-API ohne eingehendes Benutzertoken
/healthz - Gesundheitssonde

Details finden Sie in der Endpunktreferenz .

Was ist der Unterschied zwischen authentifizierten und nicht authentifizierten Endpunkten?

Authentifiziert: Anforderung des Bearertokens im Authorization Header (für OBO-Flüsse) Nicht authentifiziert: Kein eingehendes Token überprüfen (nur für App- oder Agentszenarien)

Wie kann ich ein Benutzertoken überprüfen?

GET /Validate
Authorization: Bearer <user-token>

Die Antwort enthält alle Ansprüche aus dem Token.

Wie erhalte ich ein Zugriffstoken für eine downstream-API?

GET /AuthorizationHeader/Graph
Authorization: Bearer <user-token>

Die Antwort enthält einen Autorisierungsheader, der für die Verwendung mit nachgeschalteter API bereit ist.

Kann ich die HTTP-Methode oder den Pfad pro Anforderung außer Kraft setzen?

Ja, mit Abfrageparametern:

# Override method
GET /DownstreamApi/Graph?optionsOverride.HttpMethod=POST

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

Tokenzwischenspeicherung

Das SDK speichert Token automatisch im Arbeitsspeicher zwischen, um die Leistung zu optimieren und redundante Tokenakquisitionsanforderungen zu reduzieren.

Gibt es die SDK-Cachetoken?

Ja – das SDK speichert Token im Arbeitsspeicher standardmäßig zwischen.

Wie lange werden Token zwischengespeichert?

Token werden bis zum nahen Ablauf zwischengespeichert und dann automatisch aktualisiert. Die genaue Dauer hängt von der Tokenlebensdauer ab (in der Regel 1 Stunde für Entra-ID-Token).

Kann ich die Zwischenspeicherung deaktivieren?

Die Tokenzwischenspeicherung ist automatisch und optimiert. Es gibt derzeit keine Option zum Deaktivieren.

Wird der Tokencache über SDK-Instanzen hinweg freigegeben?

Nein – jede SDK-Instanz verwaltet einen eigenen Speichercache. Bei Bereitstellungen mit hoher Verfügbarkeit verfügt jeder Pod über eine unabhängige Zwischenspeicherung.

Sicherheit

Sichere SDK-Bereitstellungen folgen bewährten Methoden für Microsoft Entra-Identität und Datenschutz, einschließlich verwalteter Identitätsnutzung, Netzwerkisolation und ordnungsgemäßer Behandlung von Anmeldeinformationen.

Ist es sicher, das SDK auszuführen?

Ja – lesen Sie die bewährten Methoden für die Sicherheit.

Sollte ich das SDK extern verfügbar machen?

Never – The SDK should only be accessible from your application container. Ausführliche bewährte Methoden für die Sicherheit finden Sie unter "Bewährte Methoden für Sicherheit".

Wie sollte ich das SDK sichern?

Ausführliche Anleitungen finden Sie unter "Bewährte Methoden für Sicherheit ".

Welche Anmeldeinformationen sollte ich verwenden?

Einstellungsreihenfolge:

Managed Identity (Azure) – Sicherste, keine Anmeldeinformationen
Zertifikate – Sicher, kann gedreht werden
Geheime Clientschlüssel – Weniger bevorzugt, im sicheren Tresor behalten

Ist das SDK compliance-zertifiziert?

Überprüfen Sie das GitHub-Repository auf aktuelle Complianceinformationen.

Leistung

Die SDK-Leistung hängt von der Effektivität des Tokenzwischenspeicherns und der Latenz von Netzwerk-Roundtrips ab, wobei typische Reaktionszeiten zwischen 10 und 50 ms für zwischengespeicherte Token auftreten.

Welche Auswirkungen hat die Leistung des SDK?

Typische HTTP-Roundtrip: 10-50 ms

Die Zwischenspeicherung von Token minimiert wiederholte Käufe. Die erste Anforderung ist langsamer (Tokenerwerb), nachfolgende Anforderungen verwenden zwischengespeicherte Token.

Wie vergleicht die SDK-Leistung mit In-Process-Bibliotheken?

In-Process-Bibliotheken sind schneller (kein Netzwerk-Roundtrip), aber das SDK bietet:

Sprachagnostischer Zugriff
Zentrale Konfiguration
Cache für gemeinsame Token über Dienste hinweg
Vereinfachte Skalierung

Ausführliche Informationen finden Sie im Vergleichshandbuch .

Kann ich das SDK horizontal skalieren?

Ja. Bereitstellen mehrerer SDK-Replikate mithilfe der Kubernetes-Bereitstellung. Jeder Pod verwaltet unabhängige Tokenzwischenspeicherung.

Migration

Der Wechsel von Microsoft.Identity.Web zum SDK bietet Vorteile bei der unterstützung mehrerer Sprachen, der zentralisierten Konfiguration und der vereinfachten Skalierung über Dienste hinweg.

Kann ich von Microsoft.Identity.Web zum Microsoft Entra SDK für AgentID migrieren?

Ja – Detaillierte Migrationsschritte finden Sie im Vergleichshandbuch

Support

Erhalten Sie Hilfe zu Problemen, finden Sie zusätzliche Dokumentationen und greifen Sie über offizielle Kanäle auf Communityressourcen zu.

Wo kann ich Fehler melden?

Melden Sie Probleme im GitHub-Repository mithilfe der Entra-ID-Vorlage.

Problembehandlung

Wenn Probleme mit dem SDK auftreten, lesen Sie das umfassende Handbuch zur Problembehandlung für Diagnoseschritte, allgemeine Probleme und Lösungen im Handbuch zur Problembehandlung.