Freigeben über

Agentidentitäten: Autonome und interaktive Agentmuster

Agentidentitäten ermöglichen anspruchsvolle Authentifizierungsszenarien, in denen eine Agentanwendung autonom oder im Auftrag von Benutzern agiert. Die Verwendung von Agentidentitäten mit dem Microsoft Entra SDK für AgentID ermöglicht sowohl autonomen Agenten, die in ihrem eigenen Kontext agieren, als auch interaktiven Agenten, die im Auftrag von Benutzern agieren. Um diese Szenarien zu vereinfachen, unterstützt das SDK bestimmte Abfrageparameter zum Angeben von Agentidentitäten und Benutzerkontexten.

Ausführliche Anleitungen zu Agentidentitäten finden Sie in der Dokumentation zur Microsoft Agent Identity Platform.

Überblick

Agentidentitäten unterstützen zwei primäre Muster:

  • Autonomer Agent: Der Agent arbeitet in seinem eigenen Anwendungskontext
  • Interaktiver Agent: Ein interaktiver Agent arbeitet im Auftrag eines Benutzers.

Das SDK akzeptiert drei optionale Abfrageparameter:

  • AgentIdentity - GUID für die Agentenidentität
  • AgentUsername - Benutzerprinzipalname (UPN) für einen bestimmten Benutzer
  • AgentUserId - Benutzerobjekt-ID (OID) für einen bestimmten Benutzer als Alternative zu UPN

Rangfolgeregeln

Wenn sowohl AgentUsername als auch AgentUserId vorhanden sind, obwohl die Validierung dies verhindert, hat die Implementierung den Benutzernamen als Vorrang:

AgentUsername > AgentUserId

Die Bereitstellung von beiden AgentUsername und AgentUserId sollte jedoch vermieden werden und führt zu einem Überprüfungsfehler im strikten Überprüfungsmodus.

Microsoft Entra ID-Konfiguration

Bevor Sie Agentidentitäten in Ihrer Anwendung konfigurieren, müssen Sie die erforderlichen Komponenten in der Microsoft Entra-ID einrichten. Wenn Sie eine neue Anwendung im Microsoft Entra ID-Mandanten registrieren möchten, lesen Sie die Registrierung einer Anwendung , um weitere Details zu erhalten.

Voraussetzungen für Agentidentitäten

  1. Agent-Anwendungsregistrierung:

    • Registrieren Sie die übergeordnete Agenten-Anwendung in Microsoft Entra ID.
    • Konfigurieren von API-Berechtigungen für nachgeschaltete APIs
    • Einrichten von Clientanmeldeinformationen (FIC+MSI oder Zertifikat oder geheimer Schlüssel)

  2. Agent-Identitätskonfiguration:

    • Erstellen von Agentidentitäten mithilfe des Agent-Blueprints
    • Zuweisen der erforderlichen Berechtigungen zu Agentidentitäten

  3. Anwendungsberechtigungen:

    • Erteilen von Anwendungsberechtigungen für autonome Szenarien
    • Delegierte Berechtigungen für Benutzerdelegierungsszenarien erteilen
    • Sicherstellen, dass die Administratorzustimmung bei Bedarf bereitgestellt wird

Ausführliche schrittweise Anleitungen zum Konfigurieren von Agentidentitäten in Microsoft Entra ID finden Sie in der Dokumentation zur Microsoft Agent Identity Platform

Semantische Regeln

Die sicherstellung der korrekten Verwendung von Agentidentitätsparametern ist für die erfolgreiche Authentifizierung von entscheidender Bedeutung. Die folgenden Regeln regeln die Verwendung von AgentIdentity, AgentUsernameund AgentUserId Parametern und sollten befolgt werden, um Überprüfungsfehler zu vermeiden, die vom SDK zurückgegeben werden.

Regel 1: AgentIdentity-Anforderung

AgentUsername oder AgentUserId müssen mit AgentIdentity kombiniert werden.

Wenn Sie angeben AgentUsername oder AgentUserId ohne AgentIdentity, schlägt die Anforderung mit einem Überprüfungsfehler fehl.

# INVALID - AgentUsername without AgentIdentity
GET /AuthorizationHeader/Graph?AgentUsername=user@contoso.com

# VALID - AgentUsername with AgentIdentity
GET /AuthorizationHeader/Graph?AgentIdentity=agent-client-id&AgentUsername=user@contoso.com

Regel 2: Gegenseitige Exklusivität

AgentUsername und AgentUserId sind sich gegenseitig ausschließende Parameter.

Sie können nicht sowohl AgentUsername als auch AgentUserId in derselben Anforderung angeben. Wenn beides angegeben wird, schlägt die Anforderung mit einem Überprüfungsfehler fehl.

# INVALID - Both AgentUsername and AgentUserId specified
GET /AuthorizationHeader/Graph?AgentIdentity=agent-id&AgentUsername=user@contoso.com&AgentUserId=user-oid

# VALID - Only AgentUsername
GET /AuthorizationHeader/Graph?AgentIdentity=agent-id&AgentUsername=user@contoso.com

# VALID - Only AgentUserId
GET /AuthorizationHeader/Graph?AgentIdentity=agent-id&AgentUserId=user-object-id

Regel 3: Autonom und interaktiv

Die Kombination von Parametern bestimmt das Authentifizierungsmuster:

Die Parameter Muster Description
nur AgentIdentity Autonomer Agent Erwirbt Anwendungstoken für die Agentidentität
AgentIdentity + AgentUsername Interaktiver Agent Beschafft Benutzertoken für den angegebenen Benutzer (durch UPN)
AgentIdentity + AgentUserId Interaktiver Agent Beschafft benutzertoken für den angegebenen Benutzer (nach Objekt-ID)

Beispiele:

# Autonomous agent - application context
GET /AuthorizationHeader/Graph?AgentIdentity=agent-id

# Interactive agent - user context by username
GET /AuthorizationHeader/Graph?AgentIdentity=agent-id&AgentUsername=user@contoso.com

# Interactive agent - user context by user ID
GET /AuthorizationHeader/Graph?AgentIdentity=agent-id&AgentUserId=user-object-id

Verwendungsmuster

Für jedes Verwendungsmuster bestimmt die Kombination von Parametern den Authentifizierungsfluss und den Typ des erworbenen Tokens.

Muster 1: Autonomer Agent

Die Agentanwendung arbeitet unabhängig in ihrem eigenen Anwendungskontext und erwirbt Anwendungstoken.

Szenario: Ein Batchverarbeitungsdienst, der Dateien autonom verarbeitet.

GET /AuthorizationHeader/Graph?AgentIdentity=12345678-1234-1234-1234-123456789012

Tokenmerkmale:

  • Tokentyp: Anwendungstoken
  • Betreff (sub): Objekt-ID der Agentanwendung
  • Token, das für die Identität des Agents ausgestellt wurde
  • Berechtigungen: Anwendungsberechtigungen, die der Agentidentität zugewiesen sind

Anwendungsfälle:

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

Muster 2: Autonomer User-Agent (Benutzername-basiert)

Der Agent arbeitet im Auftrag eines bestimmten Benutzers, der von dessen UPN identifiziert wird.

Szenario: Ein KI-Assistent, der im Namen eines Benutzers in einer Chatanwendung agiert.

GET /AuthorizationHeader/Graph?AgentIdentity=12345678-1234-1234-1234-123456789012&AgentUsername=alice@contoso.com

Tokenmerkmale:

  • Tokentyp: Benutzertoken
  • Betreff (sub): Objekt-ID des Benutzers
  • Agentidentitätsaspekt, der in Token-Ansprüchen enthalten ist
  • Berechtigungen: Interaktive Berechtigungen, die für den Benutzer gelten

Anwendungsfälle:

  • Interaktive Agent-Anwendungen
  • KI-Assistenten mit Benutzerdelegierung
  • Benutzerweite Automatisierung
  • Personalisierte Workflows

Muster 3: Autonomer Benutzer-Agent (nach Objekt-ID)

Der Agent arbeitet im Auftrag eines bestimmten Benutzers, der durch seine Objekt-ID identifiziert wird.

Szenario: Ein Workflowmodul, das benutzerspezifische Aufgaben mithilfe von gespeicherten Benutzer-IDs verarbeitet.

GET /AuthorizationHeader/Graph?AgentIdentity=12345678-1234-1234-1234-123456789012&AgentUserId=87654321-4321-4321-4321-210987654321

Tokenmerkmale:

  • Tokentyp: Benutzertoken
  • Betreff (sub): Objekt-ID des Benutzers
  • Agentidentitätsaspekt, der in Token-Ansprüchen enthalten ist
  • Berechtigungen: Interaktive Berechtigungen, die für den Benutzer gelten

Anwendungsfälle:

  • Lang andauernde Workflows mit gespeicherten Benutzerkennungen
  • Batchvorgänge im Auftrag mehrerer Benutzer
  • Systeme, die Objekt-IDs zur Benutzerreferenz verwenden

Muster 4: Interaktiver Agent (im Auftrag des Benutzers, der ihn aufruft)

Eine Agent-Web-API empfängt ein Benutzertoken, überprüft es und führt delegierte Aufrufe im Namen dieses Benutzers aus.

Szenario: Eine Web-API, die als interaktiver Agent fungiert, der eingehende Benutzertoken überprüft und delegierte Aufrufe an nachgeschaltete Dienste tätigt.

Ablauf:

  1. Agent-Web-API empfängt Benutzertoken von der aufrufenden Anwendung
  2. Überprüft das Token über den /Validate Endpunkt.
  3. Ruft Token für downstream-APIs ab, indem /AuthorizationHeader nur mit AgentIdentity und dem eingehenden Autorisierungs-Header aufgerufen wird.
# Step 1: Validate incoming user token
GET /Validate
Authorization: Bearer <user-token>

# Step 2: Get authorization header on behalf of the user
GET /AuthorizationHeader/Graph?AgentIdentity=<agent-client-id>
Authorization: Bearer <user-token>

Tokenmerkmale:

  • Tokentyp: Benutzertoken (OBO-Fluss)
  • Betreff (sub): Objekt-ID des ursprünglichen Benutzers
  • Agent fungiert als Vermittler für den Benutzer
  • Berechtigungen: Interaktive Berechtigungen, die für den Benutzer gelten

Anwendungsfälle:

  • Web-APIs, die als Agents fungieren
  • Interaktive Agent-Dienste
  • Agentenbasierte Middleware, die an nachgelagerte APIs delegiert
  • Dienste, die den Benutzerkontext überprüfen und weiterleiten

Muster 5: Reguläre Anforderung (kein Agent)

Wenn keine Agentparameter bereitgestellt werden, verwendet das SDK die Identität des eingehenden Tokens.

Szenario: Standardfluss ohne Agentidentitäten im Auftrag von (OBO).

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

Tokenmerkmale:

  • Tokentyp: Hängt von eingehendem Token und der Konfiguration ab
  • Verwendet standardmäßigen OBO- oder Clientanmeldeinformationsfluss
  • Keine Agentenidentitätsfacetten

Codebeispiele

Die folgenden Codeausschnitte veranschaulichen, wie sie die verschiedenen Agent-Identitätsmuster mithilfe verschiedener Programmiersprachen implementieren und wie sie mit den SDK-Endpunkten interagieren. Der Code veranschaulicht, wie außerhalb des Prozesses erfolgende Anrufe an das SDK verarbeitet werden, um sich Autorisierungs-Header für nachfolgende API-Aufrufe zu beschaffen.

TypeScript: Autonomer Agent

const sidecarUrl = "http://localhost:5000";
const agentId = "12345678-1234-1234-1234-123456789012";

async function runBatchJob() {
  const response = await fetch(
    `${sidecarUrl}/AuthorizationHeader/Graph?AgentIdentity=${agentId}`,
    {
      headers: {
        'Authorization': 'Bearer system-token'
      }
    }
  );
  
  const { authorizationHeader } = await response.json();
  // Use authorizationHeader for downstream API calls
}

Python: Agent mit Benutzeridentität

import requests

sidecar_url = "http://localhost:5000"
agent_id = "12345678-1234-1234-1234-123456789012"
user_email = "alice@contoso.com"

response = requests.get(
    f"{sidecar_url}/AuthorizationHeader/Graph",
    params={
        "AgentIdentity": agent_id,
        "AgentUsername": user_email
    },
    headers={"Authorization": f"Bearer {system_token}"}
)

token = response.json()["authorizationHeader"]

TypeScript: Interaktiver Agent

async function delegateCall(userToken: string) {
  // Validate incoming token
  const validation = await fetch(
    `${sidecarUrl}/Validate`,
    {
      headers: { 'Authorization': `Bearer ${userToken}` }
    }
  );
  
  const claims = await validation.json();
  
  // Call downstream API on behalf of user
  const response = await fetch(
    `${sidecarUrl}/DownstreamApi/Graph`,
    {
      headers: { 'Authorization': `Bearer ${userToken}` }
    }
  );
  
  return await response.json();
}

C# mit HttpClient

using System.Net.Http;

var httpClient = new HttpClient();

// Autonomous agent
var autonomousUrl = $"http://localhost:5000/AuthorizationHeader/Graph" +
    $"?AgentIdentity={agentClientId}";
var response = await httpClient.GetAsync(autonomousUrl);

// Delegated agent with username
var delegatedUrl = $"http://localhost:5000/AuthorizationHeader/Graph" +
    $"?AgentIdentity={agentClientId}" +
    $"&AgentUsername={Uri.EscapeDataString(userPrincipalName)}";
response = await httpClient.GetAsync(delegatedUrl);

// Delegated agent with user ID
var delegatedByIdUrl = $"http://localhost:5000/AuthorizationHeader/Graph" +
    $"?AgentIdentity={agentClientId}" +
    $"&AgentUserId={userObjectId}";
response = await httpClient.GetAsync(delegatedByIdUrl);

Fehlerszenarien

Wenn Agentidentitätsparameter falsch konfiguriert oder falsch verwendet werden, gibt das SDK Überprüfungsfehler zurück. Nachfolgend finden Sie häufige Fehlerszenarien und deren entsprechende Antworten. Weitere Informationen zur Fehlerbehandlung finden Sie im Handbuch zur Problembehandlung.

Fehlende AgentIdentity mit AgentUsername

Anforderung

GET /AuthorizationHeader/Graph?AgentUsername=user@contoso.com

Antwort:

{
  "type": "https://tools.ietf.org/html/rfc7231#section-6.5.1",
  "title": "Bad Request",
  "status": 400,
  "detail": "AgentUsername requires AgentIdentity to be specified"
}

Sowohl AgentUsername als auch AgentUserId angegeben

Anforderung

GET /AuthorizationHeader/Graph?AgentIdentity=agent-id&AgentUsername=user@contoso.com&AgentUserId=user-oid

Antwort:

{
  "type": "https://tools.ietf.org/html/rfc7231#section-6.5.1",
  "title": "Bad Request",
  "status": 400,
  "detail": "AgentUsername and AgentUserId are mutually exclusive"
}

Ungültiges AgentUserId-Format

Anforderung

GET /AuthorizationHeader/Graph?AgentIdentity=agent-id&AgentUserId=invalid-guid

Antwort:

{
  "type": "https://tools.ietf.org/html/rfc7231#section-6.5.1",
  "title": "Bad Request",
  "status": 400,
  "detail": "AgentUserId must be a valid GUID"
}

Bewährte Methoden

  1. Überprüfen von Eingaben: Agentidentitätsparameter immer überprüfen, bevor Anforderungen ausgeführt werden
  2. Verwenden von Objekt-IDs nach Verfügbarkeit: Objekt-IDs sind stabiler
  3. Implementieren der richtigen Fehlerbehandlung: Behandeln von Fehlern bei der Agentidentitätsüberprüfung ordnungsgemäß
  4. Sichere Agenten-Anmeldeinformationen: Schützen von Agentenidentität, Client-IDs und Anmeldeinformationen.
  5. Audit-Agenten-Operationen: Protokollierung und Überwachung der Agentenidentität für Sicherheit und Compliance
  6. Beide Muster testen: Überprüfen von autonomen und delegierten Szenarien in Ihren Tests
  7. Dokumentabsicht: Eindeutig dokumentieren, welches Agentmuster für jeden Anwendungsfall geeignet ist

Siehe auch

  • Last updated on