Agentidentitäten: autonome und interaktive Agentmuster

Agentidentitäten ermöglichen anspruchsvolle Authentifizierungsszenarien, in denen eine Agentanwendung autonom oder im Auftrag von Benutzern agiert. Mithilfe von Agentidentitäten mit dem Microsoft Entra SDK für AgentID können Sie sowohl autonome Agents erstellen, die in ihrem eigenen Kontext als auch in interaktiven Agents arbeiten, die im Auftrag von Benutzern handeln. 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 der Agentidentität.
  • AgentUsername – Benutzerprinzipalname (UPN) für einen bestimmten Benutzer.
  • AgentUserId - Benutzerobjekt-ID (OID) für einen bestimmten Benutzer als Alternative zu UPN.

Rangfolgeregeln

AgentUsername und AgentUserId schließen sich gegenseitig aus. Anforderungen, die beide Parameter enthalten, schlagen fehl, wie in Regel 2 beschrieben: gegenseitige Exklusivität. Stellen Sie pro Anforderung nur einen dieser Parameter bereit.

Microsoft Entra ID Konfiguration

Bevor Sie Agentidentitäten in Ihrer Anwendung konfigurieren, richten Sie die erforderlichen Komponenten in Microsoft Entra ID ein. Informationen zum Registrieren einer neuen Anwendung im Microsoft Entra ID Mandanten finden Sie unter Registern einer Anwendung.

Voraussetzungen für Agentidentitäten

  1. Agentanwendungsregistrierung:

    • Registrieren Sie die übergeordnete Agent-Anwendung in Microsoft Entra ID.
    • Konfigurieren sie API-Berechtigungen für downstream-APIs.
    • Richten Sie Client-Anmeldeinformationen ein (FIC+MSI, Zertifikat oder Geheimnis).

  2. Agentidentitätskonfiguration:

    • Erstellen Sie Agentidentitäten mithilfe des Agent-Blueprints.
    • Weisen Sie den Agentidentitäten erforderliche Berechtigungen zu.

  3. Anwendungsberechtigungen:

    • Erteilen sie Anwendungsberechtigungen für autonome Szenarien.
    • Erteilung von delegierten Berechtigungen für Szenarien der Benutzerdelegierung.
    • Stellen Sie sicher, 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

Um sich erfolgreich zu authentifizieren, müssen Sie die Agentidentitätsparameter ordnungsgemäß verwenden. Die folgenden Regeln regeln die Verwendung von AgentIdentity, und AgentUsernameAgentUserId Parametern. Befolgen Sie diese Regeln, um Überprüfungsfehler zu vermeiden, die das SDK zurückgibt.

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 Sie beide Parameter angeben, 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 vs 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.

Entwurfsmuster 1: Autonomer Agent

Die Agentanwendung wird unabhängig im eigenen Anwendungskontext ausgeführt und ruft Anwendungstoken ab.

Szenario: Ein Batchverarbeitungsdienst, der Dateien eigenständig 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 erstellt 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 Benutzer-Agent (nach Benutzername)

Der Agent wird im Auftrag eines bestimmten Benutzers ausgeführt, 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 für die 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. Die 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 Autorisierungsheader 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 Sie keine Agentparameter bereitstellen, 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

Code-Beispiele

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 Agent ID = "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 Sie Agent-Identitätsparameter falsch konfigurieren oder falsch verwenden, gibt das SDK Überprüfungsfehler zurück. In den folgenden Abschnitten werden häufige Fehlerszenarien und die entsprechenden Antworten beschrieben. 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 der Eingabe: Überprüfen Sie vor dem Senden von Anforderungen immer die Agentidentitätsparameter.
  2. Verwenden Sie objekt-IDs, wenn verfügbar: Objekt-IDs sind stabiler.
  3. Implementieren Sie die richtige Fehlerbehandlung: Behandeln Sie Fehler bei der Agentidentitätsüberprüfung ordnungsgemäß.
  4. Sichere Agent-Anmeldeinformationen: Schützen von Agentidentitäts-Client-IDs und Anmeldeinformationen.
  5. Agentenvorgänge prüfen: Protokollieren und Überwachen der Nutzung von Agenten-Identitäten für Sicherheit und Compliance.
  6. Testen Sie beide Muster: Überprüfen Sie in Ihren Tests sowohl autonome als auch delegierte Szenarien.
  7. Dokumentabsicht: Dokumentieren Sie eindeutig, welches Agentmuster für jeden Anwendungsfall geeignet ist.

Verwandte Inhalte

  • Last updated on