Authentifizieren von Benutzern und Erwerben von Token für interaktive Agents

Interaktive Agents ergreifen Aktionen im Auftrag von Benutzern. Um im Namen der Benutzer sicher zu handeln, authentifiziert der Agent den Benutzer, erhält die Zustimmung für erforderliche Berechtigungen und erwirbt Zugriffstoken für nachgeschaltete APIs. Dieser Artikel führt Sie durch den Ablauf der End-to-End-Authentifizierung und des Tokenerwerbs für Ihren interaktiven Agent:

  1. Erteilen von Berechtigungen durch vererbbare Berechtigungen oder Einwilligung.
  2. Authentifizieren Sie den Benutzer, und rufen Sie ein Zugriffstoken ab.
  3. Überprüfen Sie das Token, und extrahieren Sie Benutzeransprüche.
  4. Rufen Sie Token für Downstream-APIs mithilfe des On-Behalf-Of-Flusses (OBO) auf.

Hinweis

In diesem Artikel werden interaktive Agenten behandelt, die im Namen der angemeldeten Benutzer mit dem OBO-Flussverfahren handeln. Wenn Ihr Agent eine eigene benutzerähnliche Identität benötigt (ein Szenario für digitale Mitarbeiter), lesen Sie die Benutzerkonten des Agents und den OAuth-Fluss des Agents.

Voraussetzungen

Bevor Sie beginnen, stellen Sie sicher, dass Sie folgendes haben:

  • Ein Agentidentitäts-Blueprint. Notieren Sie die ID der Blueprint-App für Agentenidentität (Client-ID).
  • Eine Agentidentität.
  • Eine clientanwendung, die in Microsoft Entra registriert ist, um die Benutzerauthentifizierung zu verarbeiten.
  • Vertrautheit mit dem OAuth 2.0-Autorisierungscodefluss.
  • Die Möglichkeit, eine ASP.NET Core Web-API auszuführen, wenn Sie die Tokenüberprüfung und OBO-Beispiele in diesem Artikel verwenden möchten.

Für die Administratorautorisierung benötigen Sie auch Folgendes:

Bevor der Agent im Namen eines Benutzers handeln kann, muss der Benutzer oder ein Administrator den erforderlichen Berechtigungen zustimmen. Es gibt zwei Ansätze zum Erteilen von Berechtigungen:

  • Vererbbare Berechtigungen: Berechtigungen für den Blueprint vorab erstellen, sodass Agentidentitäten diese automatisch erben.
  • Anfordern der Zustimmung: Registrieren Sie einen Umleitungs-URI, und fordern Sie Benutzer oder Administratoren auf, die Zustimmung über eine OAuth-Anforderung zu erteilen oder den Endpunkt für die Administratorzustimmung zu verwenden.

Verwenden von vererbbaren Berechtigungen

Konfigurieren Sie vererbbare Berechtigungen für den Agentidentitäts-Blueprint, um einen Basissatz delegierter Bereiche und Anwendungsrollen vorab zu autorisieren. Mit dem Blueprint erstellte Agentidentitäten erben diese Berechtigungen automatisch ohne interaktive Zustimmungsaufforderungen. Weitere Informationen finden Sie unter Konfigurieren vererbbarer Berechtigungen für Agentidentitäts-Blueprints.

Um eine Einwilligung über einen OAuth-Ablauf anzufordern, muss Ihr Blueprint für die Agent-Identität zunächst mit einer Umleitungs-URI konfiguriert werden. Für Blueprints muss der Umleitungs-URI ein Webanwendungstyp sein. Im Gegensatz zu Umleitungs-URIs für App-Registrierungen kann ein Umleitungs-URI für eine Blaupause nicht zum Abrufen delegierter Berechtigungstoken verwendet werden. Nur response_type=none wird in der OAuth2-Anforderung unterstützt, was bedeutet, dass die Zustimmung der Anforderung nur erfasst wird und keine Token zurückgegeben werden.

Registrieren eines Umleitungs-URI

Um den Umleitungs-URI im Blueprint für die Agentidentität zu aktualisieren, müssen Sie zunächst ein Zugriffstoken mit der delegierten Berechtigung AgentIdentityBlueprint.ReadWrite.All abrufen. Senden Sie dann eine PATCH-Anforderung an das Anwendungsobjekt für den Agent-Identitäts-Blueprint:

PATCH https://graph.microsoft.com/beta/applications/<agent-blueprint-id>
OData-Version: 4.0
Content-Type: application/json
Authorization: Bearer <token>

{
  "web": {
    "redirectUris": [
      "https://myagentapp.com/authorize"
    ]
  }
}

Bevor der Agent im Namen eines Benutzers handeln kann, muss der Benutzer den erforderlichen Berechtigungen zustimmen. Die Zustimmungsanforderung des Benutzers gibt kein Token zurück. Stattdessen zeichnet er auf, dass der Benutzer dem Agent die Berechtigung erteilt hat, in ihrem Namen zu handeln. Der Tokenerwerb erfolgt bei der Authentifizierung des Benutzers und anfordern eines Tokens.

Von Bedeutung

Verwenden Sie die Agent-Identitätsclient-ID im client_id Parameter, nicht die Agent-Identitäts-Blueprint-ID.

Um einen Benutzer zur Zustimmung aufzufordern, erstellen Sie eine Autorisierungs-URL, und leiten Sie den Benutzer an ihn weiter. Der Agent kann diese URL auf unterschiedliche Weise präsentieren, z. B. als Link in einer Chatnachricht.

https://login.microsoftonline.com/contoso.onmicrosoft.com/oauth2/v2.0/authorize?
  client_id=<agent-identity-id>
  &response_type=none
  &redirect_uri=https%3A%2F%2Fmyagentapp.com%2Fauthorize
  &response_mode=query
  &scope=User.Read
  &state=xyz123

Wenn der Benutzer diese URL öffnet, fordert Microsoft Entra ID ihn auf, sich anzumelden und seine Zustimmung zu erteilen. Nach der Zustimmung wird der Benutzer an den Umleitungs-URI zurückgesendet.

Die wichtigsten Parameter in der Autorisierungs-URL für die Benutzergenehmigung sind:

  • client_id: Die Client-ID der Agent-Identität (nicht die Client-ID der Agent-Identitätsblaupause).
  • response_type: Auf none setzen, da diese Anforderung ausschließlich die Zustimmung aufzeichnet. Die Tokenbeschaffung verwendet response_type=code in Den Benutzer authentifizieren und ein Token anfordern.
  • redirect_uri: Muss exakt mit dem Umleitungs-URI übereinstimmen, der für den Agentidentitäts-Blueprint konfiguriert ist.
  • scope: Geben Sie die benötigten delegierten Berechtigungen an (z. B User.Read. ).
  • state: Optionaler Parameter für die Aufrechterhaltung des Zustands zwischen der Anforderung und dem Rückruf.

Weitere Informationen zu OAuth-Autorisierungskonzepten finden Sie unter Berechtigungen und Zustimmung in der Microsoft Identity Platform.

Agents können auch eine Genehmigung von einem Microsoft Entra ID-Administrator anfordern, der dem Agenten die Zustimmung für alle Benutzer in seinem Mandanten erteilen kann. Je nach den im Mandanten konfigurierten Zustimmungseinstellungen kann die Administratorzustimmung erforderlich sein.

Um eine Administratorgenehmigung für den gesamten Mandanten zu erteilen, weisen Sie einen Administrator an, die folgende URL aufzurufen. Verwenden Sie die Agent-Identitäts-ID im client_id Parameter.

https://login.microsoftonline.com/contoso.onmicrosoft.com/v2.0/adminconsent
?client_id=<agent-identity-id>
&scope=User.Read
&redirect_uri=<redirect-uri>
&state=xyz123

Nachdem der Administrator die Zustimmung erteilt hat, gelten die Berechtigungen für den gesamten Mandanten. Benutzer müssen nicht erneut zustimmen.

Hinweis

Konfigurieren Sie einen Umleitungs-URI in Ihrem Blueprint, und fügen Sie einen state Parameter in die Zustimmungsanforderung ein. Wenn die Zustimmung erteilt wurde, wird der Benutzer zur Redirect-URI weitergeleitet, wo Sie eine Bestätigung anzeigen können. Ihr Endpunkt kann den state Parameter verwenden, um diese Berechtigung nachzuverfolgen. Für Einzelmandanten-Agents können Sie alternativ Tokenanforderungen wiederholen, bis die Zustimmung erteilt wird, da die Mandanten-ID bereits bekannt ist.

Authentifizieren des Benutzers und Anfordern eines Tokens

Nachdem die Zustimmung erteilt wurde, initiiert die Client-App (z. B. eine Frontend- oder mobile App) eine OAuth 2.0-Autorisierungscodeanforderung, um ein Token abzurufen, bei dem die Zielgruppe der Agentidentitäts-Blueprint ist. In diesem Schritt steht client_id für die eigene registrierte Anwendungs-ID der Client-App, nicht für die Agentenidentität oder den Blueprint der Agentenidentität.

Hinweis

Das redirect_uri in dieser Anfrage gehört zur Registrierung der Client-App, nicht zur Redirect-URI des Blueprints, die im vorherigen Zustimmungsschritt konfiguriert wurde.

  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-app-id>
&response_type=code
&redirect_uri=<redirect_uri>
&response_mode=query
&scope=api://<agent-blueprint-id>/access_agent
&state=abc123

  2. Nachdem sich der Benutzer angemeldet hat, empfängt Ihre App einen Autorisierungscode am Umleitungs-URI. Tauschen Sie den Autorisierungscode gegen ein Access-Token aus:

    POST https://login.microsoftonline.com/<my-test-tenant>/oauth2/v2.0/token
Content-Type: application/x-www-form-urlencoded

client_id=<client-app-id>
&grant_type=authorization_code
&code=<authorization_code>
&redirect_uri=<redirect_uri>
&scope=api://<agent-blueprint-id>/access_agent
&client_secret=<client-secret>

    Fügen Sie den client_secret Parameter nur bei Verwendung eines vertraulichen Clients ein.

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

Überprüfen des Zugriffstokens

Die Web-API muss das eingehende Zugriffstoken überprüfen, bevor der Agent handeln kann. Verwenden Sie immer eine genehmigte Bibliothek, um Token zu überprüfen. Schreiben Sie keinen eigenen Tokenüberprüfungscode.

  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 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 der appsettings.json Datei:

    Warnung

    Geheime Clientschlüssel dürfen in Produktionsumgebungen aufgrund von Sicherheitsrisiken nicht als Clientanmeldeinformationen für Agent-Identitätsblaupausen verwendet werden. Verwenden Sie stattdessen sicherere Authentifizierungsmethoden wie Verbundidentitätsanmeldeinformationen (FIC) mit verwalteten Identitäten oder Clientzertifikaten. Diese Methoden bieten eine verbesserte Sicherheit, da vertrauliche geheime Schlüssel nicht direkt in Ihrer Anwendungskonfiguration gespeichert werden müssen.

    "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 unter Microsoft. Identity.Web documentation.

Überprüfen von Benutzeransprüchen

Nach der Überprüfung des Zugriffstokens kann der Agent den Benutzer identifizieren und Autorisierungsprüfungen durchführen. Im folgenden Beispiel-API-Routing werden Benutzeransprüche aus dem Zugriffstoken extrahiert und in der API-Antwort zurückgegeben:

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();

Das Abrufen von Token für nachgelagerte APIs

Nachdem ein interaktiver Agent das Token des Benutzers überprüft hat, kann er Zugriffstoken anfordern, um nachgeschaltete APIs im Auftrag des Benutzers aufzurufen. Der On-Behalf-Of (OBO)-Flow ermöglicht es dem Agenten:

  • Empfangen eines Zugriffstokens von einem Client.
  • Tauschen Sie es gegen ein neues Zugriffstoken für eine nachgelagerte API wie Microsoft Graph.
  • Verwenden Sie dieses neue Token, um im Namen des ursprünglichen Benutzers auf geschützte Ressourcen zuzugreifen.

Die Microsoft.Identity.Web-Bibliothek vereinfacht die OBO-Implementierung durch automatisches Behandeln des Tokenaustauschs, sodass Sie den Fluss nicht manuell implementieren müssen, indem Sie dem Protokoll folgen.

  1. Installieren Sie die erforderlichen NuGet-Pakete:

    dotnet add package Microsoft.Identity.Web
dotnet add package Microsoft.Identity.Web.AgentIdentities

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

    // Program.cs
using Microsoft.AspNetCore.Authorization;
using Microsoft.Identity.Abstractions;
using Microsoft.Identity.Web;
using Microsoft.Identity.Web.Resource;
using Microsoft.Identity.Web.TokenCacheProviders.InMemory;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddMicrosoftIdentityWebApiAuthentication(builder.Configuration)
    .EnableTokenAcquisitionToCallDownstreamApi();
builder.Services.AddAgentIdentities();
builder.Services.AddInMemoryTokenCaches();

var app = builder.Build();

app.UseAuthentication();
app.UseAuthorization();

app.Run();

  3. Tauschen Sie in der Agent-API das Zugriffstoken für eingehende Benutzer für ein neues Zugriffstoken für die Agentidentität aus. Microsoft.Identity.Web validiert das eingehende Zugriffstoken und führt den On-Behalf-Of-Tokenaustausch durch:

    app.MapGet("/agent-obo-user", async (HttpContext httpContext) =>
{
    string agentIdentity = "<your-agent-identity>";
    IAuthorizationHeaderProvider authorizationHeaderProvider = httpContext.RequestServices.GetService<IAuthorizationHeaderProvider>()!;
    AuthorizationHeaderProviderOptions options = new AuthorizationHeaderProviderOptions().WithAgentIdentity(agentIdentity);

    string authorizationHeaderWithUserToken = await authorizationHeaderProvider.CreateAuthorizationHeaderForUserAsync(["https://graph.microsoft.com/.default"], options);

    var response = new { header = authorizationHeaderWithUserToken };
    return Results.Json(response);
})
.RequireAuthorization();

Unter der Haube umfasst der OBO-Fluss zwei Tokenaustausche: Zuerst ruft der Blueprint für Agentenidentität mithilfe seiner Clientanmeldeinformationen ein Austausch-Token ab, und dann tauscht die Agentenidentität dieses Token zusammen mit dem Zugriffstoken des Benutzers gegen ein nachgelagertes API-Token ein. Eine vollständige Schritt-für-Schritt-Anleitung zum Protokoll einschließlich HTTP-Anforderungsformaten und Tokenvalidierung finden Sie im Abschnitt On-Behalf-Of-Fluss in Agents.

Verwandte Inhalte

Weitere Informationen zu Agenttoken und verwandten APIs:

  • Last updated on