Authentifier les utilisateurs et acquérir des jetons pour les agents interactifs

Les agents interactifs prennent des mesures pour le compte des utilisateurs. Pour agir en toute sécurité pour le compte des utilisateurs, l’agent authentifie l’utilisateur, obtient le consentement pour les autorisations requises et acquiert des jetons d’accès pour les API en aval. Cet article vous guide tout au long du flux d’authentification de bout en bout et d’acquisition de jetons pour votre agent interactif :

  1. Accordez des autorisations par le biais d’autorisations héritées ou de consentement.
  2. Authentifiez l’utilisateur et obtenez un jeton d’accès.
  3. Validez le jeton et extrayez les revendications utilisateur.
  4. Obtenez des jetons pour les API en aval à l’aide du flux On-Behalf-Of (OBO).

Note

Cet article traite des agents interactifs qui agissent pour le compte des utilisateurs connectés à l’aide du flux OBO. Si votre agent a besoin de son propre identité de type utilisateur (scénario de travail numérique), consultez les comptes d’utilisateur de l’agent et le flux OAuth du compte d’utilisateur de l’agent.

Prerequisites

Avant de commencer, assurez-vous d’avoir :

  • Un plan directeur d’identité d'agent. Enregistrez l’ID d’application du blueprint d’identité de l’agent (ID client).
  • Une identité d’agent.
  • Une application cliente inscrite dans Microsoft Entra pour gérer l’authentification utilisateur.
  • Connaissance du flux de code d’autorisation OAuth 2.0.
  • Possibilité d’exécuter une API web ASP.NET Core si vous envisagez d’utiliser les exemples de validation de jeton et d’OBO dans cet article.

Pour l’autorisation d’administrateur, vous avez également besoin des éléments suivants :

Avant que l’agent puisse agir au nom d’un utilisateur, l’utilisateur ou l’administrateur doit donner son consentement aux autorisations requises. Il existe deux approches pour accorder des autorisations :

  • Autorisations héritées : préautorisez des autorisations sur le modèle afin que les identités d’agent en héritent automatiquement.
  • Demander le consentement : inscrivez un URI de redirection et invitez les utilisateurs ou les administrateurs à accorder le consentement via une demande OAuth ou utilisez le point de terminaison de consentement de l’administrateur.

Utiliser des autorisations héritées

Configurez les autorisations héritables sur le modèle d’identité de l’agent afin de préautoriser un ensemble de base d’étendues déléguées et de rôles d’application. Les identités d’agent créées à partir du blueprint héritent automatiquement de ces autorisations sans invite de consentement interactif. Pour plus d’informations, consultez Configurer les autorisations pouvant être héritées pour les modèles d’identité d’agent.

Pour demander le consentement via un flux OAuth, votre blueprint d’identité de l’agent doit d’abord être configuré avec un URI de redirection. Pour les blueprints, l’URI de redirection doit être un type d’application web . Contrairement aux URI de redirection définies sur les inscriptions d’application, une URI de redirection configurée dans un blueprint ne peut pas être utilisée pour obtenir des jetons d’autorisation déléguée. Seul response_type=none est pris en charge dans la requête OAuth2, ce qui signifie que la requête enregistre uniquement le consentement et qu’aucun jeton n’est renvoyé.

Inscrire un URI de redirection

Pour mettre à jour l’URI de redirection dans le blueprint d’identité de l’agent, vous devez d’abord obtenir un jeton d’accès avec la permission déléguée AgentIdentityBlueprint.ReadWrite.All. Envoyez ensuite une requête PATCH à l’objet d’application pour le blueprint d’identité de l’agent :

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

Avant que l’agent puisse agir au nom d’un utilisateur, l’utilisateur doit donner son consentement aux autorisations requises. La demande de consentement de l’utilisateur ne retourne pas de jeton. Au lieu de cela, il enregistre que l’utilisateur a accordé à l’agent l’autorisation d’agir en son nom. L’acquisition de jetons se produit dans Authentifier l’utilisateur et demander un jeton.

Important

Utilisez l’ID client d’identité de l’agent dans le paramètre client_id, et non l’ID de plan de base d'identité de l’agent.

Pour inviter un utilisateur à donner son consentement, construisez une URL d’autorisation et redirigez-le vers celui-ci. L’agent peut présenter cette URL de différentes manières, par exemple, en tant que lien dans un message de conversation.

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

Lorsque l’utilisateur ouvre cette URL, Microsoft Entra ID les invite à se connecter et à accorder son consentement. Une fois le consentement donné, l’utilisateur est renvoyé à l’URI de redirection.

Les paramètres clés dans l’URL d’autorisation de consentement de l’utilisateur sont les suivants :

  • client_id: ID client d’identité de l’agent (et non ID client du blueprint d’identité de l’agent).
  • response_type: défini sur none car cette demande enregistre le consentement uniquement. L’acquisition de jetons est utilisée response_type=code dans Authentifier l’utilisateur et demander un jeton.
  • redirect_uri: doit correspondre exactement à l’URI de redirection configuré sur le blueprint d’identité de l’agent.
  • scope: spécifiez les autorisations déléguées dont vous avez besoin (par exemple). User.Read
  • state: paramètre facultatif pour la maintenance de l’état entre la requête et le rappel.

Pour plus d’informations sur les concepts d’autorisation OAuth, consultez Permissions et consentement dans le Plateforme d'identités Microsoft.

Les agents peuvent également demander l’autorisation à un administrateur Microsoft Entra ID, qui peut accorder le consentement à l’agent pour tous les utilisateurs de leur locataire. Le consentement administrateur peut être requis en fonction des paramètres de consentement configurés dans le locataire.

Pour accorder le consentement administrateur pour l’ensemble du locataire, redirigez un administrateur vers l’URL suivante. Utilisez l’ID d’identité de l’agent dans le client_id paramètre.

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

Une fois que l’administrateur a accordé son consentement, les autorisations s’appliquent à l’ensemble du locataire. Les utilisateurs n’ont pas besoin de consentir à nouveau.

Note

Configurez un URI de redirection sur votre blueprint et incluez un state paramètre dans la demande de consentement. Lorsque le consentement est accordé, l’utilisateur est envoyé à l’URI de redirection où vous pouvez afficher la confirmation. Votre point de terminaison peut utiliser le state paramètre pour suivre cette autorisation. Pour les agents monolocataires, vous pouvez également relancer les requêtes de jeton jusqu’à ce que le consentement soit accordé, car l’ID du locataire est déjà connu.

Authentifier l’utilisateur et demander un jeton

Une fois le consentement accordé, l’application cliente (par exemple, une application frontale ou mobile) lance une demande de code d’autorisation OAuth 2.0 pour obtenir un jeton où l’audience est le blueprint d’identité de l’agent. Dans cette étape, client_id désigne l’identifiant d’application enregistré propre à l’application cliente, et non l’identité de l’agent ni le modèle d’identité de l’agent.

Note

Le redirect_uri dans cette demande appartient à l’inscription de l’application cliente, et non à l’URI de redirection du blueprint configurée lors de l’étape précédente de consentement.

  1. Redirigez l’utilisateur vers le point de terminaison d’autorisation Microsoft Entra ID avec les paramètres suivants :

    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. Une fois l’utilisateur connecté, votre application reçoit un code d’autorisation à l’URI de redirection. Échangez le code d’autorisation contre un jeton d’accès :

    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>

    Incluez le client_secret paramètre uniquement si vous utilisez un client confidentiel.

    La réponse JSON contient un jeton d’accès qui peut être utilisé pour accéder à l’API de l’agent.

Valider le jeton d’accès

L’API web doit valider le jeton d’accès entrant avant que l’agent puisse agir. Utilisez toujours une bibliothèque approuvée pour valider les jetons. N’écrivez pas votre propre code de validation de jeton.

  1. Installez le package NuGet Microsoft.Identity.Web :

    dotnet add package Microsoft.Identity.Web

  2. Dans votre projet d’API web ASP.NET Core, implémentez l’authentification Microsoft Entra ID :

    // 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. Configurez les informations d’identification d’authentification dans le appsettings.json fichier :

    Avertissement

    Les secrets client ne doivent pas être utilisés comme informations d’identification client dans des environnements de production pour les blueprints d’identité de l’agent en raison des risques de sécurité. Utilisez plutôt des méthodes d’authentification plus sécurisées telles que les informations d’identification d’identité fédérée (FIC) avec des identités managées ou des certificats clients. Ces méthodes offrent une sécurité renforcée en éliminant la nécessité de stocker des secrets sensibles directement dans la configuration de votre application.

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

Pour plus d’informations sur Microsoft. Identity.Web, consultez Microsoft. Documentation Identity.Web.

Valider les revendications utilisateur

Après la validation du jeton d’accès, l’agent peut identifier l’utilisateur et effectuer des vérifications d’autorisation. L’exemple d’itinéraire d’API suivant extrait les revendications utilisateur du jeton d’accès et les retourne dans la réponse de l’API :

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

Acquérir des jetons pour les API en aval

Une fois qu’un agent interactif valide le jeton de l’utilisateur, il peut demander des jetons d’accès pour appeler des API en aval pour le compte de l’utilisateur. Le flux On-Behalf-Of (OBO) permet à l’agent de :

  • Recevez un jeton d’accès d’un client.
  • Échangez-le pour un nouveau jeton d'accès destiné à une API en aval, comme Microsoft Graph.
  • Utilisez ce nouveau jeton pour accéder aux ressources protégées pour le compte de l’utilisateur d’origine.

La bibliothèque Microsoft.Identity.Web simplifie l'implémentation OBO en gérant automatiquement l'échange de jetons. Vous n'avez donc pas besoin d'implémenter manuellement le flux en suivant le protocole.

  1. Installez les packages NuGet requis :

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

  2. Dans votre projet d’API web ASP.NET Core, mettez à jour l’implémentation de l’authentification Microsoft Entra ID :

    // 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. Dans l’API de l’agent, échangez le jeton d’accès utilisateur entrant pour un nouveau jeton d’accès pour l’identité de l’agent. Microsoft.Identity.Web valide le jeton d’accès entrant et gère l’échange de jetons au nom d’un utilisateur.

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

Sous le capot, le flux OBO implique deux échanges de jetons : tout d’abord, le blueprint d’identité de l’agent obtient un jeton d’échange à l’aide de ses informations d’identification client, puis l’identité de l’agent échange ce jeton avec le jeton d’accès de l’utilisateur pour un jeton d’API en aval. Pour obtenir la procédure pas à pas complète du protocole, y compris les formats de requête HTTP et les détails de validation de jeton, consultez Flux On-Behalf-Of dans les agents.

Contenu connexe

En savoir plus sur les jetons d’agent et les API associées :

  • Last updated on