Gebruikers verifiëren en tokens verkrijgen voor interactieve agents

Interactieve agents voeren acties uit namens gebruikers. De agent verifieert de gebruiker, krijgt toestemming voor vereiste machtigingen en verkrijgt toegangstokens voor downstream-API's om veilig te handelen namens gebruikers. In dit artikel wordt u begeleid bij de end-to-end verificatie- en tokenovernamestroom voor uw interactieve agent:

  1. Machtigingen verlenen via overgenomen machtigingen of toestemming.
  2. Verifieer de gebruiker en haal een toegangstoken op.
  3. Valideer het token en haal gebruikersclaims op.
  4. Tokens verkrijgen voor downstream-API's met de On-Behalf-Of (OBO)-stroom.

Opmerking

In dit artikel worden interactieve agents behandeld die namens aangemelde gebruikers handelen met behulp van de OBO-stroom. Als uw agent een eigen gebruikersachtige identiteit nodig heeft (een digitaal werkrolscenario), raadpleegt u de gebruikersaccounts van de agent en de OAuth-stroom van het gebruikersaccount van de agent.

Vereiste voorwaarden

Voordat u begint, moet u ervoor zorgen dat u het volgende heeft:

  • Een blauwdruk voor agentidentiteit. Noteer de blueprint-app-id van de agentidentiteit (client-id).
  • Een agent-id.
  • Een clienttoepassing die is geregistreerd in Microsoft Entra voor het afhandelen van gebruikersverificatie.
  • Bekendheid met de OAuth 2.0-autorisatiecodestroom.
  • De mogelijkheid om een ASP.NET Core web-API uit te voeren als u van plan bent om de tokenvalidatie en OBO-voorbeelden in dit artikel te gebruiken.

Voor beheerdersautorisatie hebt u ook het volgende nodig:

Voordat de agent namens een gebruiker kan handelen, moet de gebruiker of beheerder toestemming geven voor de vereiste machtigingen. Er zijn twee benaderingen voor het verlenen van machtigingen:

  • Overgenomen machtigingen: machtigingen voor de blauwdruk vooraf verifiëren, zodat agentidentiteiten deze automatisch overnemen.
  • Toestemming aanvragen: registreer een omleidings-URI en vraag gebruikers of beheerders om toestemming te verlenen via een OAuth-aanvraag of gebruik het eindpunt voor beheerderstoestemming.

Overgenomen machtigingen gebruiken

Configureer overerfbare machtigingen in de blauwdruk van de agentidentiteit om een basisset gedelegeerde machtigingsbereiken en toepassingsrollen vooraf te autoriseren. Agentidentiteiten die zijn gemaakt op basis van de blauwdruk nemen deze machtigingen automatisch over zonder interactieve toestemmingsprompts. Zie Overerfbare machtigingen configureren voor blueprints voor agentidentiteiten voor meer informatie.

Als u toestemming wilt aanvragen via een OAuth-stroom, moet uw blauwdruk voor de agent-identiteit eerst worden geconfigureerd met een omleidings-URI. Voor blauwdrukken moet de omleidings-URI een webtoepassingstype zijn. In tegenstelling tot omleidings-URI's voor app-registraties, kan een omleidings-URI op een blauwdruk niet worden gebruikt om gedelegeerde machtigingstokens te verkrijgen. Alleen response_type=none wordt ondersteund in de OAuth2-aanvraag, wat betekent dat de aanvraag alleen toestemming registreert en dat er geen tokens worden geretourneerd.

Een omleidings-URI registreren

Als u de omleidings-URI wilt bijwerken in de blauwdruk voor de agentidentiteit, moet u eerst een toegangstoken met de gedelegeerde machtiging AgentIdentityBlueprint.ReadWrite.Allverkrijgen. Verzend vervolgens een PATCH-aanvraag naar het toepassingsobject voor de blauwdruk voor de agentidentiteit:

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

Voordat de agent namens een gebruiker kan handelen, moet de gebruiker toestemming geven voor de vereiste machtigingen. De aanvraag voor toestemming van de gebruiker retourneert geen token. In plaats daarvan wordt vastgelegd dat de gebruiker de agent toestemming heeft gegeven om namens hen actie te ondernemen. Tokenverwerving vindt plaats in Verificatie van de gebruiker en vraagt een token aan.

Belangrijk

Gebruik de client-ID van de agentidentiteit in de client_id parameter, niet de blauwdruk-ID van de agentidentiteit.

Als u een gebruiker om toestemming wilt vragen, maakt u een autorisatie-URL en stuurt u de gebruiker ernaar om. De agent kan deze URL op verschillende manieren presenteren, bijvoorbeeld als een koppeling in een chatbericht.

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

Wanneer de gebruiker deze URL opent, Microsoft Entra ID hem of haar vraagt zich aan te melden en toestemming te verlenen. Na toestemming wordt de gebruiker teruggestuurd naar de omleidings-URI.

De belangrijkste parameters in de autorisatie-URL voor gebruikerstoestemming zijn:

  • client_id: De client-id van de agentidentiteit (niet de client-id van de blauwdruk van de agentidentiteit).
  • response_type: Ingesteld op none omdat deze aanvraag alleen toestemming registreert. Het ophalen van tokens wordt gebruikt response_type=code bij Het verifiëren van de gebruiker en het aanvragen van een token.
  • redirect_uri: moet exact overeenkomen met de omleidings-URI die is geconfigureerd op de blauwdruk voor de agentidentiteit.
  • scope: Geef de gedelegeerde machtigingen op die u nodig hebt (bijvoorbeeld User.Read).
  • state: Optionele parameter voor het onderhouden van de status tussen de aanvraag en callback.

Zie machtigingen en toestemming in de Microsoft identity platform voor meer informatie over OAuth-autorisatieconcepten.

Agents kunnen ook autorisatie aanvragen bij een Microsoft Entra ID-beheerder, die toestemming kan verlenen aan de agent voor alle gebruikers in hun tenant. Beheerderstoestemming is mogelijk vereist, afhankelijk van de toestemmingsinstellingen die zijn geconfigureerd in de tenant.

Als u tenantbrede beheerderstoestemming wilt verlenen, stuurt u een beheerder naar de volgende URL. Gebruik de id van de agent in de 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

Nadat de beheerder toestemming heeft verleend, zijn de machtigingen van toepassing op de hele tenant. Gebruikers hoeven niet opnieuw toestemming te geven.

Opmerking

Configureer een omleidings-URI op uw blauwdruk en neem een state parameter op in de toestemmingsaanvraag. Wanneer toestemming wordt verleend, wordt de gebruiker verzonden naar de omleidings-URI, waar u bevestiging kunt weergeven. Uw eindpunt kan de state parameter gebruiken om die machtiging bij te houden. Voor agents met één tenant kunt u tokenaanvragen ook opnieuw proberen totdat toestemming is verleend, omdat de tenant-id al bekend is.

De gebruiker verifiëren en een token aanvragen

Nadat toestemming is verleend, initieert de client-app (zoals een front-end- of mobiele app) een OAuth 2.0-autorisatiecodeaanvraag om een token te verkrijgen waarbij de doelgroep de blauwdruk voor de agentidentiteit is. In deze stap verwijst client_id naar de eigen geregistreerde applicatie-id van de client-app, niet naar de identiteit van de agent of de blauwdruk van de agentidentiteit.

Opmerking

De redirect_uri in dit verzoek behoort tot de registratie van de client-app, en niet tot de redirect-URI van de blueprint die in de vorige toestemmingsstap is geconfigureerd.

  1. De gebruiker omleiden naar het Microsoft Entra ID-autorisatie-eindpunt met de volgende parameters:

    GET https://login.microsoftonline.com/<your-tenant-id>/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. Nadat de gebruiker zich heeft aangemeld, ontvangt uw app een autorisatiecode op de omleidings-URI. Exchange de autorisatiecode voor een toegangstoken:

    POST https://login.microsoftonline.com/<your-tenant-id>/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>

    Neem de client_secret parameter alleen op als u een vertrouwelijke client gebruikt.

    Het JSON-antwoord bevat een toegangstoken dat kan worden gebruikt voor toegang tot de API van de agent.

Het toegangstoken valideren

De web-API moet het binnenkomende toegangstoken valideren voordat de agent kan handelen. Gebruik altijd een goedgekeurde bibliotheek om tokens te valideren. Schrijf uw eigen tokenvalidatiecode niet.

  1. Installeer het NuGet-pakket Microsoft.Identity.Web:

    dotnet add package Microsoft.Identity.Web

  2. Implementeer Microsoft Entra ID verificatie in uw ASP.NET Core-web-API-project:

    // Program.cs
using Microsoft.AspNetCore.Authentication.JwtBearer;
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. Verificatiereferenties configureren in het appsettings.json bestand:

    Waarschuwing

    Cliëntgeheimen mogen niet worden gebruikt als klantreferenties in productieomgevingen voor blauwdrukken van agentidentiteit om beveiligingsrisico's te voorkomen. Gebruik in plaats daarvan veiligere verificatiemethoden, zoals federatieve identiteitsreferenties (FIC) met beheerde identiteiten of clientcertificaten. Deze methoden bieden verbeterde beveiliging door de noodzaak weg te nemen om gevoelige geheimen rechtstreeks in uw toepassingsconfiguratie op te slaan.

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

Voor meer informatie over Microsoft. Identity.Web, zie Microsoft. Identity.Web-documentatie.

Gebruikersclaims valideren

Na validatie van toegangstokens kan de agent de gebruiker identificeren en autorisatiecontroles uitvoeren. Met de volgende voorbeeld-API-route worden gebruikersclaims uit het toegangstoken geëxtraheerd en geretourneerd in het API-antwoord:

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

Tokens verkrijgen voor downstream-API's

Nadat een interactieve agent het token van de gebruiker heeft gevalideerd, kan deze toegangstokens aanvragen om downstream-API's aan te roepen namens de gebruiker. Met de On-Behalf-Of flow (OBO) kan de agent het volgende doen:

  • Een toegangstoken ontvangen van een client.
  • Exchange het voor een nieuw toegangstoken voor een downstream-API, zoals Microsoft Graph.
  • Gebruik dat nieuwe token om namens de oorspronkelijke gebruiker toegang te krijgen tot beveiligde resources.

De Microsoft.Identity.Web bibliotheek vereenvoudigt de OBO-implementatie door tokenuitwisseling automatisch te verwerken, dus u hoeft de stroom niet handmatig te implementeren door het protocol te volgen.

  1. Installeer de vereiste NuGet-pakketten:

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

  2. Werk in uw ASP.NET Core web-API-project de implementatie van de Microsoft Entra ID verificatie bij:

    // 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. In de agent-API moet u het binnenkomende toegangstoken voor gebruikers uitwisselen voor een nieuw toegangstoken voor de agentidentiteit. Microsoft.Identity.Web valideert het binnenkomende toegangstoken en verwerkt de uitwisseling van het 'on-behalf-of'-token:

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

Onder de schermen omvat de OBO-stroom twee tokenuitwisselingen: eerst verkrijgt de blauwdruk van de agentidentiteit een exchange-token met behulp van de clientreferentie en vervolgens de agentidentiteit wisselt dat token uit, samen met het toegangstoken van de gebruiker voor een downstream-API-token. Zie On-behalf-of-flow in agents voor de volledige uitleg van het protocol, inclusief HTTP-aanvraagindelingen en tokenvalidatiegegevens.

Verwante inhoud

Meer informatie over agenttokens en gerelateerde API's:

  • Last updated on