Hinweis
Für den Zugriff auf diese Seite ist eine Autorisierung erforderlich. Sie können versuchen, sich anzumelden oder das Verzeichnis zu wechseln.
Für den Zugriff auf diese Seite ist eine Autorisierung erforderlich. Sie können versuchen, das Verzeichnis zu wechseln.
Die meisten autonomen Agents sollten APIs mit ihren Agentidentitäts- und Anwendungsberechtigungen aufrufen. Erstellen Sie das Benutzerkonto eines Agents nur, wenn eine Microsoft 365 Workload ein Benutzerobjekt erfordert.
Das Benutzerkonto eines Agents ist eine dedizierte Benutzeridentität für den Agent. Er ist nicht der angemeldete Benutzer eines interaktiven Agents. Jedes Konto verfügt über eine 1:1-Beziehung mit einer Agentidentität.
Ermitteln, ob der Agent ein Benutzerobjekt benötigt
| Scenario | Ist das Benutzerkonto eines Agents erforderlich? | Guidance |
|---|---|---|
| Aufrufen einer API, die Anwendungsberechtigungen unterstützt | No | Verwenden Sie die Agent-Identität und den reinen App-Zugriff. |
| Hinzufügen des Agents als Mitglied eines Microsoft Teams Teams | Ja | Die Teammitgliedschaft wird Verzeichnisbenutzern zugewiesen. Siehe Hinzufügen von Mitgliedern zu einem Team. |
| Weisen Sie dem Agent ein eigenes Exchange Online Postfach zu | Ja | Ein Postfach wird für ein Benutzerobjekt bereitgestellt. Siehe Erstellen von Benutzerpostfächern in Exchange Online. |
| Teilen Sie ein SharePoint- oder OneDrive-Element direkt für den Agenten als Person | Ja | Verwenden Sie das Benutzerkonto des Agents als Freigabeempfänger. Sehen Sie sich die Freigabe von Dateien und Ordnern an. |
| Verwenden eines Microsoft 365 Diensts, der pro Benutzer lizenziert ist | Ja | Weisen Sie nur die lizenzen zu, die vom Dienst benötigt werden. Siehe Zuweisen von Lizenzen zu Benutzern. |
Erstellen Sie nicht nur das Benutzerkonto eines Agents, weil der Agent ohne eine Person ausgeführt wird. Wenn der Zieldienst Anwendungsberechtigungen oder workloadspezifische Anwendungszugriffssteuerelemente unterstützt, verwenden Sie stattdessen die Agentidentität.
Bereitstellen des Zugriffs
- Erstellen Sie das Benutzerkonto eines Agents , und ordnen Sie es der Agent-Identität zu.
- Weisen Sie dem Konto nur die benötigten Microsoft 365-Lizenzen zu.
- Fügen Sie das Konto zum erforderlichen Team hinzu, stellen Sie sein Postfach bereit oder geben Sie die erforderlichen SharePoint-Ressourcen frei, indem Sie der Dienstdokumentation in der vorherigen Tabelle folgen.
-
Gewähren Sie der Agentidentität delegierte Berechtigungen für die Microsoft 365 Bereiche, die der Workload erfordert, etwa
Mail.ReadWriteoderFiles.ReadWrite. Die Agentidentität verwendet diese delegierten Berechtigungen, wenn sie als Benutzerkonto des Agents authentifiziert wird.
Durch das Erstellen des Benutzerobjekts wird kein Zugriff auf ein Team, ein Postfach, eine Website, eine Datei oder eine API gewährt. Schließen Sie die workloadspezifische Zuordnung separat ab.
Authentifizieren als Benutzerkonto des Agents
Der Ablauf für das Benutzerkonto des Agenten umfasst keinen angemeldeten Benutzer. Verwenden Sie WithAgentUserIdentity, um das dedizierte Benutzerkonto zu identifizieren.
Microsoft.Identity.Web.AgentIdentities führt den Agent-ID-Tokenaustausch aus.
In diesem Beispiel wird Blueprint-to-Child-Token-Exchange verwendet. Verwenden Sie die Paketinstallation und Laufzeitkonfiguration, einschließlich Microsoft.Identity.Web.AgentIdentities, AddAgentIdentities()Tokenerwerb, einen HTTP-Client und einen Tokencache. Konfigurieren Der Client-ID und anmeldeinformationen des Blueprints in der Laufzeit; übergeben Sie die Client-ID der untergeordneten Agent-Identität und das zugehörige Benutzerkonto an WithAgentUserIdentity. Ersetzen Sie nicht das Nur-App-Setup mit einer Instanz, die diese Agent-ID-Austauschregistrierung nicht enthält.
Der folgende Code ist ein Endpunktfragment, kein vollständiger Host. Führen Sie ihre using-Direktiven oben auf Program.cs zusammen und platzieren Sie die Zuordnung vor app.Run(). Konfigurieren Sie die Richtlinie für eingehende AgentUser Autorisierung , bevor Sie den Postfachendpunkt verfügbar machen. Ermitteln Sie den Agenten und das Konto aus der Konfiguration vertrauenswürdiger Anwendungen, nicht aus vom Aufrufer bereitgestellten Werten.
Identifizieren Sie das Benutzerkonto des Agenten anhand der UPN:
using System.Net.Http.Headers;
using System.Security.Claims;
using Microsoft.Identity.Abstractions;
using Microsoft.Identity.Web;
app.MapGet("/mailbox", async (
IAuthorizationHeaderProvider authorizationHeaderProvider,
IHttpClientFactory httpClientFactory) =>
{
var options = new AuthorizationHeaderProviderOptions()
.WithAgentUserIdentity("<agent-identity-client-id>", "<agent-user-upn>");
string authorizationHeader = await authorizationHeaderProvider
.CreateAuthorizationHeaderForUserAsync(
["https://graph.microsoft.com/.default"],
options,
new ClaimsPrincipal());
HttpClient client = httpClientFactory.CreateClient();
client.DefaultRequestHeaders.Authorization =
AuthenticationHeaderValue.Parse(authorizationHeader);
using HttpResponseMessage response =
await client.GetAsync("https://graph.microsoft.com/v1.0/me/messages");
response.EnsureSuccessStatusCode();
return Results.Content(
await response.Content.ReadAsStringAsync(),
"application/json");
})
.RequireAuthorization("AgentUser");
Oder identifizieren Sie das Konto anhand der Objekt-ID:
var options = new AuthorizationHeaderProviderOptions()
.WithAgentUserIdentity("<agent-identity-client-id>", Guid.Parse("<agent-user-object-id>"));
Übergeben Sie new ClaimsPrincipal(), weil kein Benutzer angemeldet ist. Die Benutzeridentität stammt aus WithAgentUserIdentity, nicht aus dem Anforderungskontext. Gewähren Sie dem Benutzerkonto des Agents nur die delegierten Berechtigungen, die die Workload benötigt. Implementieren Sie den Tokenaustausch nicht direkt.
Informationen zum Protokollmodell und zu Sicherheitseinschränkungen finden Sie unter OAuth-Protokolle in Microsoft Entra-Agent-ID. Die vollständige API-Referenz finden Sie unter Microsoft.Identity.Web auf GitHub.
Bei einem autorisierten eingehenden Aufrufer gibt ein erfolgreicher /mailbox-Aufruf die Nachrichten des konfigurierten Agentbenutzers zurück, nicht das Postfach des Aufrufers. Eine leere Nachrichtensammlung kann gültig sein. Wenn der Aufruf fehlschlägt, überprüfen Sie die Identitäts-zu-Konto-Zuordnung, delegierte Erteilung und Exchange Postfachbereitstellung separat. Im Beispiel löst ein nachgeschalteter Nichterfolgsstatus eine Ausnahme aus, anstatt diesen Status an den eingehenden Anrufer weiterzuleiten.
Für reine Testressourcen befolgen Sie nach dem Entfernen jeglichen workloadspezifischen Zugriffs, den Sie erstellt haben, die Schritte unter Delete an agent's user account. Löschen Sie kein freigegebenes Postfach oder Konto.
Nächster Schritt
Benutzerkonto des Agenten verwalten