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.
Ein Upstream-Client meldet den Benutzer an und sendet ein Zugriffstoken an Ihre Agent-API. In diesem Artikel wird die ASP.NET Core-Agent-API konfiguriert, um dieses Token zu überprüfen und einen lokalen Testclient zu zeigen, der sich bei einem Benutzer anmeldet und aufruft/whoami.
Die Authentifizierung stellt die Identität des Aufrufers fest. Die Steuerung des Benutzerzugriffs auf Agenten legt separat fest, ob diese Identität den Agenten aufrufen kann.
Prerequisites
- Abschluss von Erstellen einer Identität für Ihren Agenten, einschließlich der Mandantenaktivierung und Administratorübergabe. Notieren Sie die freigegebene Client-ID und die Objekt-ID der Agentidentität.
- .NET 10 SDK. In den Beispielen wird Microsoft.Identity.Web 4.17.0 verwendet.
- Eine Upstream-Clientanwendung, die Benutzer anmelden und ein Zugriffstoken für die Agent-API anfordern kann, oder die Berechtigung zum Registrieren des lokalen Testclients.
- Verwenden Sie für den Zustimmungsschritt in der Vorschau den Verwaltungsclient mit Administratoreinwilligung für die zusätzliche delegierte Graph-Berechtigung
DelegatedPermissionGrant.ReadWrite.All. Verwenden Sie einen Administrator, der berechtigt ist, diesen delegierten Berechtigungen zuzustimmen. Wählen Sie die unterstützte Rolle mit den geringsten Berechtigungen unter Mandantenweite Administratoreinwilligung erteilen aus, und bestätigen Sie alle zusätzlichen Einwilligungsanforderungen für die Vorschauversion mit Ihrem Microsoft Vertreter. - Ein vertrauenswürdiges lokales HTTPS-Entwicklungszertifikat für lokale Tests. Führen Sie
dotnet dev-certs https --trustaus und genehmigen Sie die Vertrauensaufforderung auf Ihrem Entwicklungscomputer. Deaktivieren Sie die Zertifikatüberprüfung nicht.
Lokalen Testclient registrieren
Überspringen Sie diesen Abschnitt, wenn Sie bereits über einen Client verfügen, der Benutzer anmeldet und Ihren Agent aufruft. Dieser Testclient ist eine separate, normale App-Registrierung, keine weitere Agentidentität.
- Registrieren Sie eine Einzelmandantenanwendung namens Agent-API-Testclient im Mandanten des Agents.
- Fügen Sie unter "Authentifizierung" die Plattform für Mobile und Desktopanwendungen mit Umleitungs-URI
http://localhosthinzu. Es ist kein Client Secret erforderlich. - Notieren Sie die Anwendungs-ID (Client). Suchen Sie unter Enterprise-Anwendungen die entsprechende Anwendung, und notieren Sie die Objekt-ID. Tokenanforderungen verwenden die Client-ID; zustimmungserteilungen verwenden die Objekt-ID der Unternehmensanwendung.
Der Client verwendet einen Browser und PKCE. Die Loopbackumleitung empfängt die Autorisierungsantwort lokal; API-Aufrufe verwenden weiterhin HTTPS.
Konfigurieren der delegierten Berechtigung
Der Upstreamclient benötigt eine delegierte Berechtigung, um die Agent-API für den angemeldeten Benutzer aufzurufen.
- Machen Sie auf dem Blueprint einen Bezeichner-URI und einen delegierten Bereich verfügbar. Verwenden Sie
access_agentals Bereichswert für diese exemplarische Vorgehensweise. Vorhandene Scopes beibehalten undapi.requestedAccessTokenVersionauf2festlegen. - Deklarieren Sie diesen Bereich im Upstreamclient
requiredResourceAccess. Verwenden Sie die Client-ID des freigegebenen Agents alsresourceAppIdund die GUID des verfügbar gemachten Bereichs mit"type": "Scope". - Gewähren Sie dem vorgelagerten Client den Zugriff für den Testbenutzer, wie im nächsten Abschnitt beschrieben. Während der Vorschau unterstützt die Browser-Einwilligung keine Agent-Identität als Ressource.
Weitere Informationen finden Sie unter Konfigurieren einer Clientanwendung für den Zugriff auf eine Web-API und Berechtigungen sowie die Zustimmung in der Microsoft Identity Platform.
Konfigurieren Sie den Upstreamclient, indem Sie dem Authentifizierungsfluss für diesen Clienttyp folgen. Siehe z. B. den OAuth 2.0-Autorisierungscodefluss. Fordern Sie den vollqualifizierten Agent-API-Scope an:
api://<agent-client-id>/access_agent
Verwenden Sie eine Authentifizierungsbibliothek im Upstreamclient. Senden Sie keine ID-Token oder Autorisierungscodes an die Agent-API.
Upstream-Clientzugriff gewähren
Verwenden Sie den Verwaltungsclient für diese Microsoft Graph Anforderungen, nicht die Laufzeitanmeldeinformationen des Agents. Dadurch wird der upstream-Client autorisiert, den Agent anzurufen; sie gewährt dem Agent keinen Zugriff auf nachgeschaltete APIs.
Öffnen Sie vor dem Ausführen der Anfragen die Registrierung der Verwaltungs-App im Microsoft Entra Admin Center. Wählen Sie unter API-Berechtigungen die Option Berechtigung hinzufügen>Microsoft Graph>Delegierte Berechtigungen aus, fügen Sie DelegatedPermissionGrant.ReadWrite.All hinzu, und lassen Sie einen autorisierten Administrator die Einwilligung erteilen. Behalten Sie die beiden Verwaltungsberechtigungen aus der Bereitstellung bei. Fügen Sie diese Berechtigungen nicht dem Agent oder dem Testclient hinzu.
Erneut mit allen drei zugestimmten Scopes verbinden:
Disconnect-MgGraph
Connect-MgGraph -ClientId "<management-app-client-id>" `
-TenantId "<tenant-id>" `
-Scopes "AgentIdentityBlueprint.ReadWrite.All", "AgentIdentity.ReadWrite.All", "DelegatedPermissionGrant.ReadWrite.All" `
-ContextScope Process
Verwenden Sie Invoke-MgGraphRequest, wie unter Einrichten des Verwaltungsclients gezeigt.
Prüfen Sie, ob eine vorhandene anwendbare Berechtigung vorliegt:
GET https://graph.microsoft.com/v1.0/oauth2PermissionGrants?$filter=clientId eq '<upstream-client-service-principal-object-id>' and resourceId eq '<agent-identity-object-id>'Beachten Sie die Paginierung. Eine geeignete mandantenweite Gewährung oder eine Gewährung für den Testbenutzer kann
access_agentbereits enthalten.Wenn keine anwendbare Berechtigung vorhanden ist, gewähren Sie dem Benutzer, der sich anmeldet, Zugriff:
POST https://graph.microsoft.com/v1.0/oauth2PermissionGrants Content-Type: application/json { "clientId": "<upstream-client-service-principal-object-id>", "resourceId": "<agent-identity-object-id>", "consentType": "Principal", "principalId": "<user-object-id>", "scope": "access_agent" }clientIdund sind Dienstprinzipal-resourceId, nicht OAuth-Client-IDs. Wenn für diesen Benutzer bereits eine Berechtigungserteilung vorhanden ist, der Scope jedoch fehlt, aktualisieren Sie den Scope der OAuth2-Berechtigungserteilung mit der Vereinigung der vorhandenen und erforderlichen Scopes. Erstellen Sie kein Duplikat und entfernen Sie keine nicht zusammenhängenden Bereiche.Notieren Sie die Grant-ID
idfür die Bereinigung. Melden Sie sich als dieser Benutzer an, wenn Sie den Testclient ausführen. Erzwingen Sie keine neue Zustimmungsaufforderung für die Agentressource.
Konfigurieren der Tokenüberprüfung
Erstellen Sie das Agent-API-Projekt, wenn Sie noch keines haben:
dotnet new webapi --framework net10.0 --name AgentApi
cd AgentApi
Installiere Microsoft.Identity.Web aus dem Projektverzeichnis:
dotnet add package Microsoft.Identity.Web --version 4.17.0
Konfigurieren der Agent-API in appsettings.json:
{
"AzureAd": {
"Instance": "https://login.microsoftonline.com/",
"TenantId": "<tenant-id>",
"ClientId": "<agent-client-id>"
}
}
Ersetzen Sie das Program.cs des Projekts durch den folgenden Code. Er erfordert den access_agent Bereich, bevor die überprüfte Identität des Aufrufers zurückgegeben wird:
using System.Security.Claims;
using Microsoft.Identity.Web;
using Microsoft.Identity.Web.Resource;
var builder = WebApplication.CreateBuilder(args);
builder.Services.AddMicrosoftIdentityWebApiAuthentication(
builder.Configuration);
builder.Services.AddAuthorization();
var app = builder.Build();
app.UseAuthentication();
app.UseAuthorization();
app.MapGet("/whoami", (HttpContext context) =>
{
context.VerifyUserHasAnyAcceptedScope("access_agent");
ClaimsPrincipal user = context.User;
string? objectId = user.GetObjectId();
string? tenantId = user.GetTenantId();
return Results.Ok(new { objectId, tenantId });
})
.RequireAuthorization();
app.Run();
AddMicrosoftIdentityWebApiAuthentication überprüft die Tokensignatur, den Aussteller, die Zielgruppe und die Lebensdauer. Autorisierungsrichtlinien können dann Scopes, App-Rollen und andere Claims auswerten.
VerifyUserHasAnyAcceptedScope weist ein gültiges Token zurück, das die delegierte Berechtigung access_agent nicht enthält.
Verwenden Sie GetTenantId() und GetObjectId(), um die stabile Identität zu lesen. Diese Hilfsprogramme behandeln sowohl die ursprünglichen JWT-Anspruchsnamen als auch die Von der Authentifizierungs-Middleware zugeordneten Anspruchsnamen.
Den Anforderungspfad verstehen
- Der Upstream-Client meldet den Benutzer an.
- Der Client ruft ein Zugriffstoken für
access_agent. - Der Client sendet
Authorization: Bearer <token>an die Agent-API. - Die ASP.NET Core-Authentifizierungs-Middleware überprüft das Token.
- Die Agent-API wendet die Autorisierungsrichtlinie an.
Testclient ausführen
Starten Sie die Agent-API:
dotnet run --urls https://localhost:5001
Erstellen Sie in einem anderen Terminal ein Konsolenprojekt außerhalb des Agent-API-Verzeichnisses:
dotnet new console --framework net10.0 --name AgentTestClient
cd AgentTestClient
dotnet add package Microsoft.Identity.Client
Ersetzen Sie Program.cs des Konsolenprojekts durch diesen Code. Ersetzen Sie die Mandanten-ID, die Client-ID des Testclients und die freigegebene Client-ID des Agenten:
using System.Net.Http.Headers;
using Microsoft.Identity.Client;
var client = PublicClientApplicationBuilder.Create("<upstream-client-id>")
.WithAuthority("https://login.microsoftonline.com/<tenant-id>")
.WithRedirectUri("http://localhost")
.Build();
var result = await client
.AcquireTokenInteractive(["api://<agent-client-id>/access_agent"])
.ExecuteAsync();
using var http = new HttpClient();
http.DefaultRequestHeaders.Authorization =
new AuthenticationHeaderValue("Bearer", result.AccessToken);
using var response = await http.GetAsync("https://localhost:5001/whoami");
Console.WriteLine($"HTTP {(int)response.StatusCode}");
response.EnsureSuccessStatusCode();
Console.WriteLine(await response.Content.ReadAsStringAsync());
Führen Sie dotnet run aus, und melden Sie sich als der in der Zustimmungserteilung benannte Benutzer an. Erwarten Sie HTTP 200 sowie die Objekt-ID und die Mandanten-ID dieses Benutzers. Eine Anfrage an /whoami ohne Token muss 401 zurückgeben. Protokollieren Sie das Token nicht, und verwenden Sie auch kein ID-Token an seiner Stelle.
Wenn Ihre API einen anderen delegierten Bereich verfügbar macht und Ihr Testclient die Zustimmung dafür hat, fordern Sie auch ein Token für diesen Bereich allein an und rufen Sie sie auf /whoami. Vergewissern Sie sich, dass das Token über die Audience der Agent-API verfügt, aber access_agent nicht enthält und dass die Anforderung abgelehnt wird. Für diesen optionalen Bereichs-negativ-Test ist ein zweiter Bereich erforderlich; Das minimale lokale Setup definiert nur access_agent. Ein Token für eine andere Audience testet die Audience-Validierung, nicht die Scope-Autorisierung.
Wenn die Anmeldung fehlschlägt, überprüfen Sie den Umleitungs-URI des Testclients und die Bewilligung pro Benutzer, bevor Sie die Konfiguration des Agents ändern. Wenn HTTPS fehlschlägt, stellen Sie das Vertrauen in das Entwicklungszertifikat her, anstatt die Überprüfung zu umgehen.
Bereinigen des lokalen Tests
Beenden Sie beide Projekte, wenn Sie fertig sind. Halten Sie die Registrierung des Testclients und des Agents bei, wenn Sie mit der nächsten Aufgabe fortfahren. Wenn Sie keine Testzuweisung mehr benötigen, löschen Sie sie mit DELETE https://graph.microsoft.com/v1.0/oauth2PermissionGrants/<grant-id> über den Verwaltungsclient, bevor Sie die Client-App-Registrierung löschen. Löschen Sie keine freigegebenen Clients oder Berechtigungen, die von anderen Benutzern verwendet werden.
Nächster Schritt
Rufen Sie eine benutzerdefinierte API als angemeldeter Benutzer auf. Informationen zum Einschränken, welche Benutzer den Agent aufrufen können, finden Sie unter Steuern des Benutzerzugriffs auf Agents.