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

Interaktive Agents ergreifen Aktionen im Auftrag von Benutzern. Um dies sicher zu tun, muss der Agent den Benutzer authentifizieren, die Zustimmung für die erforderlichen Berechtigungen einholen und Zugriffstoken für downstream-APIs erwerben. Dieser Artikel führt Sie durch die Implementierung des End-to-End-Flusses für Ihren interaktiven Agent:

Registrieren Sie einen Umleitungs-URI für Ihre Agent-Identitätsblaupause.
Konfigurieren der Benutzer- oder Administratorautorisierung (Zustimmung).
Authentifizieren Sie den Benutzer, und rufen Sie ein Zugriffstoken ab.
Überprüfen Sie das Token, und extrahieren Sie Benutzeransprüche.
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.

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

Administratorzugriff, um die Zustimmung für Anwendungsberechtigungen zu erteilen.

Registrieren eines Umleitungs-URI

Um delegierte Berechtigungen zu unterstützen, muss Ihr Agentidentitäts-Blueprint mit einem gültigen Umleitungs-URI konfiguriert werden. Dieser URI bezeichnet den Ort, an den die Microsoft Entra ID Benutzer weiterleitet, nachdem sie die Einwilligung zu Ihrem Agent zugewiesen oder verweigert hat.

Microsoft Graph-API
Microsoft Graph PowerShell

Um diese Anforderung zu senden, müssen Sie zuerst ein Zugriffstoken mit der delegierten Berechtigung AgentIdentityBlueprint.ReadWrite.Allabrufen.

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"
    ]
  }
}

Connect-MgGraph -Scopes "AgentIdentityBlueprint.ReadWrite.All" -TenantId <your-test-tenant>

$applicationId = "<agent-blueprint-id>"
$web = @{
    redirectUris= @(
        "https://myagentapp.com/authorize"
    )
}

$body = @{
    web   =  $web
}

Invoke-MgGraphRequest -Method PATCH `
        -Uri "https://graph.microsoft.com/beta/applications/$applicationId" `
        -Headers @{ "OData-Version" = "4.0" } `
        -Body ($body | ConvertTo-Json)

Konfigurieren der Benutzerautorisierung

Bevor der Agent im Namen eines Benutzers handeln kann, muss der Benutzer den erforderlichen Berechtigungen zustimmen. Dieser Zustimmungsschritt gibt kein Token zurück. Stattdessen zeichnet er auf, dass der Benutzer dem Agent die Berechtigung erteilt hat, in ihrem Auftrag zu handeln. Der Tokenerwerb erfolgt in einem späteren Schritt.

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.

Von Bedeutung

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

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, werden sie von Microsoft Entra ID aufgefordert, sich anzumelden und die im Parameter scope angegebenen Berechtigungen zu erteilen. Nachdem die Zustimmung erteilt wurde, wird der Benutzer an den angegebenen Umleitungs-URI umgeleitet.

Die wichtigsten Parameter in der Zustimmungs-URL 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. Für den Tokenerwerb wird response_type=code in einer separaten Anforderung verwendet.
redirect_uri: Muss genau mit dem übereinstimmen, was Sie im vorherigen Schritt konfiguriert haben.
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.

Konfigurieren der Administratorautorisierung

Agents können auch eine Autorisierung von einem Microsoft Entra ID-Administrator anfordern, der dem Agent eine Autorisierung für alle Benutzer in ihrem Mandanten erteilen kann. Anwendungsberechtigungen erfordern eine Administratorautorisierung, da einzelne Benutzer ihnen nicht zustimmen können.

Um die Zustimmung des Administrators zu erteilen, erstellen Sie die Autorisierungs-URL, die den Administrator zur Aktion auffordert. Verwenden Sie die Agent-Identitäts-ID in der folgenden Anforderung.

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

Nachdem der Administrator die Zustimmung erteilt hat, werden die Berechtigungen mandantenweit angewendet, und Benutzer in diesem Mandanten müssen diesen Berechtigungen nicht einzeln zustimmen.

Authentifizieren des Benutzers und Anfordern eines Tokens

Nachdem die Autorisierung konfiguriert 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 bezieht sich client_id auf die registrierte Anwendungs-ID der Client-App selbst, nicht auf die ID der Agent-Identität oder der Agent-Identitätsblaupause.

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

Nachdem sich der Benutzer angemeldet hat, empfängt Ihre App einen Autorisierungscode am Umleitungs-URI. Tauschen Sie es gegen ein Zugriffstoken ein.
```
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

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. Implementieren Sie niemals Ihren eigenen Tokenüberprüfungscode.

Installieren Sie das Microsoft.Identity.Web NuGet-Paket:
```
dotnet add package Microsoft.Identity.Web
```

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

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

Nachdem Sie das Zugriffstoken überprüft haben, kann der Agent 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();

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.

Microsoft Identity Web
Microsoft Graph SDK

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.

Installieren Sie die erforderlichen NuGet-Pakete:

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

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

Tauschen Sie in der Agent-API das eingehende Zugriffstoken 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();

Wenn Sie das Microsoft Graph SDK verwenden, können Sie sich mit dem GraphServiceClient bei Microsoft Graph authentifizieren.

Installieren Sie die erforderlichen NuGet-Pakete:

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

Konfigurieren Sie in Ihrem ASP.NET Core Web-API-Projekt die Authentifizierung, und fügen Sie Unterstützung für Microsoft Graph hinzu:

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

var builder = WebApplication.CreateBuilder(args);

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

var app = builder.Build();

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

app.Run();

Fordern Sie beim Dienstanbieter einen GraphServiceClient an und rufen Sie Microsoft Graph APIs mit der Agent-Identität auf.

app.MapGet("/agent-obo-user", async (HttpContext httpContext) =>
{
    string agentIdentity = "<your-agent-identity>";

    GraphServiceClient graphServiceClient = httpContext.RequestServices.GetService<GraphServiceClient>()!;
    var me = await graphServiceClient.Me.GetAsync(r => r.Options.WithAuthenticationOptions(
        o =>
        {
            o.WithAgentIdentity(agentIdentity);
        }));
    return me.UserPrincipalName;
})
.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.

Feedback

War diese Seite hilfreich?

Last updated on 2026-05-01