Authentifizieren von Benutzern in interaktiven Agents

Agents benötigen häufig Aktionen im Auftrag von Benutzern, die den Agent verwenden. Der erste Schritt zum Erstellen eines interaktiven Agents besteht darin, den Benutzer zu authentifizieren. In diesem Artikel wird der Prozess des Erstellens eines einfachen Webdiensts erläutert, der einen Benutzer authentifiziert. Der Blueprint für die Agentenidentität wird verwendet, um den Webdienst zu sichern. Die Schritte umfassen:

1. Ein Client ruft einen Zugriffstoken ab, der für den Agenten-Identitäts-Blueprint vorgesehen ist.
2. Überprüfen Sie dieses Token in der API des Agents.
3. Extrahieren Sie Ansprüche über den Benutzer, die für die Autorisierung verwendet werden können.

Voraussetzungen

Blueprints der Agentenidentität. Notieren Sie die ID der Blueprint-App für Agentenidentität (Client-ID).

Anfordern eines Tokens für den Agentidentitäts-Blueprint

Um einen Benutzer zu authentifizieren, sollte die Client-App (z. B. eine Frontend- oder mobile App) eine OAuth 2.0-Autorisierungsanforderung initiieren, um ein Token abzurufen, bei dem die Zielgruppe der Agentidentitäts-Blueprint ist.

1. Leiten Sie den Benutzer mit den folgenden Parametern an den Microsoft Entra ID-Autorisierungsendpunkt um:

   GET https://login.microsoftonline.com/<my-test-tenant>/oauth2/v2.0/authorize?client_id=<client-id>
   &response_type=code
   &redirect_uri=<redirect_uri>
   &response_mode=query
   &scope=api://<agent-blueprint-id>/access_agent
   &state=abc123
   

2. Sobald sich der Benutzer anmeldet, empfängt Ihre App einen Autorisierungscode am Umleitungs-URI. Sie tauschen es für ein Zugriffstoken aus:

   POST https://login.microsoftonline.com/<my-test-tenant>/oauth2/v2.0/token
   Content-Type: application/x-www-form-urlencoded
   
   client_id=<client-id>
   grant_type=authorization_code
   code=<authorization_code>
   redirect_uri=<redirect_uri>
   scope=api://<agent-blueprint-id>/access_agent
   client_secret=<client-secret>  # Only if using a confidential client
   

   Die JSON-Antwort enthält ein Zugriffstoken, das für den Zugriff auf die API des Agents verwendet werden kann.

Überprüfen des Tokens in der API des Agents

Der Agent, der in der Regel über eine Web-API verfügbar gemacht wird, muss das Zugriffstoken überprüfen. Verwenden Sie immer eine genehmigte Bibliothek, um die Tokenüberprüfung durchzuführen und sollten niemals Ihren eigenen Tokenüberprüfungscode implementieren.

1. Installieren Sie das Microsoft.Identity.Web NuGet-Paket:

   dotnet add package Microsoft.Identity.Web
   

2. Implementieren Sie in Ihrem ASP.NET Core Web API-Projekt die Microsoft Entra ID-Authentifizierung:

   // Program.cs
   using Microsoft.Identity.Web;
   
   var builder = WebApplication.CreateBuilder(args);
   
   builder.Services.AddAuthentication(JwtBearerDefaults.AuthenticationScheme)
       .AddMicrosoftIdentityWebApi(builder.Configuration.GetSection("AzureAd"));
   
   var app = builder.Build();
   
   app.UseAuthentication();
   app.UseAuthorization();
   

3. Konfigurieren von Authentifizierungsanmeldeinformationen in appsettings.json Datei:

"AzureAd": {
"Instance": "https://login.microsoftonline.com/",
"TenantId": "<my-test-tenant>",
"ClientId": "<agent-blueprint-id>",
"Audience": "<agent-blueprint-id>",
"ClientCredentials": [
    {
    "SourceType": "ClientSecret",
    "ClientSecret": "your-client-secret"
    }
]
}

Weitere Informationen zu Microsoft.Identity.Web finden Sie in offiziellen Dokumenten.

Überprüfen von Benutzeransprüchen

Nachdem Sie das Zugriffstoken überprüft haben, kann der Agent nun den Benutzer identifizieren und Autorisierungsprüfungen durchführen. Diese Beispiel-API-Route extrahiert Benutzeransprüche aus dem Zugriffstoken und gibt sie in der API-Antwort zurück:

app.MapGet("/hello-agent", (HttpContext httpContext) =>
{   
    var claims = httpContext.User.Claims.Select(c => new
    {
        Type = c.Type,
        Value = c.Value
    });

    return Results.Ok(claims);
})
.RequireAuthorization();

Verwandte Inhalte

Tokenansprüche