Authentifier les utilisateurs auprès d’une API d’agent ASP.NET Core

Un client en amont connecte l’utilisateur et envoie un jeton d’accès à votre API d’agent. Cet article configure l’API de l’agent ASP.NET Core pour valider ce jeton et affiche un client de test local qui connecte un utilisateur et appelle /whoami.

L’authentification établit l’identité de l’appelant. Le contrôle de l’accès des utilisateurs aux agents détermine séparément si cette identité peut appeler l’agent.

Prerequisites

  • Achèvement de la création d’une identité pour votre agent, y compris l’activation du locataire et le transfert d’administrateur. Enregistrez l’ID client partagé et l’ID d’objet de l’identité de l’agent.
  • Kit de développement logiciel (SDK) .NET 10. Les exemples utilisent Microsoft.Identity.Web 4.17.0.
  • Application cliente en amont qui peut connecter des utilisateurs et demander un jeton d’accès pour l’API de l’agent ou l’autorisation d’inscrire le client de test local.
  • Pour l’étape de consentement en préversion, utilisez le client de gestion avec le consentement de l’administrateur pour l’autorisation Graph déléguée supplémentaire DelegatedPermissionGrant.ReadWrite.All. Utilisez un administrateur autorisé à consentir à ces autorisations déléguées. Choisissez le rôle le moins privilégié pris en charge à partir d’Accorder le consentement administrateur à l’échelle du locataire et confirmez les exigences de consentement supplémentaires en préversion avec votre représentant Microsoft.
  • Certificat de développement HTTPS local de confiance pour les tests locaux. Exécutez dotnet dev-certs https --trust et approuvez l’invite d’approbation sur votre ordinateur de développement. Ne désactivez pas la vérification du certificat.

Inscrire un client de test local

Ignorez cette section si vous disposez déjà d’un client qui connecte des utilisateurs et appelle votre agent. Ce client de test est une inscription d’application distincte et ordinaire, et non une autre identité d’agent.

  1. Enregistrer une application monolocataire nommée Agent API test client dans le locataire de l’agent.
  2. Sous Authentification, ajoutez la plateforme d’applications mobiles et de bureau avec l’URI http://localhostde redirection. Aucune clé secrète client n’est nécessaire.
  3. Enregistrez son ID d’application (client). Sous Applications d’entreprise, recherchez l’application correspondante et enregistrez son ID d’objet. Les demandes de jeton utilisent l’ID client ; les octrois de consentement utilisent l’ID d’objet de l’application d’entreprise.

Le client utilise un navigateur et le protocole PKCE. La redirection de bouclage reçoit la réponse d’autorisation localement ; Les appels d’API utilisent toujours HTTPS.

Configurer l’autorisation déléguée

Le client en amont a besoin d’une autorisation déléguée pour appeler l’API de l’agent pour l’utilisateur connecté.

  1. Sur le blueprint, exposez un URI d’identificateur et une portée déléguée. Utilisez access_agent comme valeur de portée pour cette procédure pas à pas. Conservez les portées existantes et définissez 2 sur api.requestedAccessTokenVersion.
  2. Déclarez cette portée dans le requiredResourceAccess du client en amont. Utilisez l’ID client de l’agent partagé comme resourceAppId et le GUID de l’étendue exposée avec "type": "Scope".
  3. Accordez l’accès au client en amont pour l’utilisateur de test, comme décrit dans la section suivante. Pendant la préversion, le consentement du navigateur ne prend pas en charge une identité d’agent comme ressource.

Pour plus d’informations, consultez Configurer une application cliente pour accéder à une API webet des autorisations et le consentement dans le Plateforme d'identités Microsoft.

Configurez le client en amont en suivant le flux d’authentification de ce type de client. Par exemple, consultez le flux de code d’autorisation OAuth 2.0. Demandez le scope complet de l’API de l’agent :

api://<agent-client-id>/access_agent

Utilisez une bibliothèque d’authentification dans le client source. N’envoyez pas de jetons d’ID ou de codes d’autorisation à l’API de l’agent.

Accorder au client en amont l’accès

Utilisez le client de gestion pour ces requêtes Microsoft Graph, et non les informations d'identification d'exécution de l'agent. Cet octroi autorise le client en amont à appeler l’agent ; il n’accorde pas à l’agent l’accès aux API en aval.

Avant d'exécuter les requêtes, ouvrez l'inscription de l'application de gestion dans le centre d’administration Microsoft Entra. Sous Autorisations d’API, sélectionnez Ajouter une autorisation>Microsoft Graph>Delegated permissions, add DelegatedPermissionGrant.ReadWrite.All, and have an authorized administrator grant consent. Conservez les deux autorisations de gestion du provisionnement. N’ajoutez pas ces autorisations à l’agent ou au client de test.

Reconnectez-vous avec les trois portées consenties :

Disconnect-MgGraph
Connect-MgGraph -ClientId "<management-app-client-id>" `
    -TenantId "<tenant-id>" `
    -Scopes "AgentIdentityBlueprint.ReadWrite.All", "AgentIdentity.ReadWrite.All", "DelegatedPermissionGrant.ReadWrite.All" `
    -ContextScope Process

Utilisez Invoke-MgGraphRequest comme indiqué dans Configurer le client de gestion.

  1. Recherchez une subvention applicable existante :

    GET https://graph.microsoft.com/v1.0/oauth2PermissionGrants?$filter=clientId eq '<upstream-client-service-principal-object-id>' and resourceId eq '<agent-identity-object-id>'
    

    Respectez la pagination. Une autorisation applicable à l’échelle du locataire ou une autorisation pour l’utilisateur de test peut déjà inclure access_agent.

  2. S’il n’existe aucune autorisation applicable, accordez l’accès au seul utilisateur qui se connectera :

    POST https://graph.microsoft.com/v1.0/oauth2PermissionGrants
    Content-Type: application/json
    
    {
      "clientId": "<upstream-client-service-principal-object-id>",
      "resourceId": "<agent-identity-object-id>",
      "consentType": "Principal",
      "principalId": "<user-object-id>",
      "scope": "access_agent"
    }
    

    clientId et resourceId sont des ID d’objet de principal de service, et non des ID client OAuth. Si un octroi existe déjà pour cet utilisateur, mais qu’il ne contient pas l’étendue requise, mettez à jour l’étendue de l’octroi d’autorisation OAuth2 avec l’union des étendues existantes et requises. Ne créez pas de portées en double et ne supprimez pas de portées non liées.

  3. Enregistrez le id de l’autorisation pour le nettoyage. Connectez-vous en tant qu’utilisateur lorsque vous exécutez le client de test. Ne forcez pas une nouvelle demande de consentement pour la ressource de l’agent.

Configurer la validation des jetons

Créez le projet d’API de l’agent si vous n’en avez pas déjà :

dotnet new webapi --framework net10.0 --name AgentApi
cd AgentApi

Installez Microsoft.Identity.Web depuis le répertoire du projet :

dotnet add package Microsoft.Identity.Web --version 4.17.0

Configurez l’API de l’agent dans appsettings.json:

{
  "AzureAd": {
    "Instance": "https://login.microsoftonline.com/",
    "TenantId": "<tenant-id>",
    "ClientId": "<agent-client-id>"
  }
}

Remplacez le Program.cs du projet par le code suivant. Elle nécessite la portée access_agent avant de retourner l’identité validée de l’appelant :

using System.Security.Claims;
using Microsoft.Identity.Web;
using Microsoft.Identity.Web.Resource;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddMicrosoftIdentityWebApiAuthentication(
    builder.Configuration);
builder.Services.AddAuthorization();

var app = builder.Build();

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

app.MapGet("/whoami", (HttpContext context) =>
{
    context.VerifyUserHasAnyAcceptedScope("access_agent");

    ClaimsPrincipal user = context.User;
    string? objectId = user.GetObjectId();
    string? tenantId = user.GetTenantId();

    return Results.Ok(new { objectId, tenantId });
})
.RequireAuthorization();

app.Run();

AddMicrosoftIdentityWebApiAuthentication valide la signature de jeton, l’émetteur, l’audience et la durée de vie. Les politiques d’autorisation peuvent ensuite évaluer les scopes, les rôles d’application et d’autres revendications.

VerifyUserHasAnyAcceptedScope rejette un jeton valide qui ne contient pas l’autorisation access_agent déléguée.

Utilisez GetObjectId() et GetTenantId() pour lire l’identité stable. Ces fonctions utilitaires gèrent à la fois les noms de claims JWT d’origine et les noms de claim mappés par l’intergiciel d’authentification.

Comprendre le chemin de la demande

  1. Le client en amont authentifie l’utilisateur.
  2. Le client obtient un jeton d’accès pour access_agent.
  3. Le client envoie Authorization: Bearer <token> à l’API de l’agent.
  4. Le middleware d’authentification ASP.NET Core valide le jeton.
  5. L’API de l’agent applique sa stratégie d’autorisation.

Exécuter le client de test

Démarrez l’API de l’agent :

dotnet run --urls https://localhost:5001

Dans un autre terminal, créez un projet de console en dehors du répertoire d’API de l’agent :

dotnet new console --framework net10.0 --name AgentTestClient
cd AgentTestClient
dotnet add package Microsoft.Identity.Client

Remplacez Program.cs du projet de console par ce code. Remplacez l’ID du locataire, l’ID client du client de test et l’ID client partagé de l’agent :

using System.Net.Http.Headers;
using Microsoft.Identity.Client;

var client = PublicClientApplicationBuilder.Create("<upstream-client-id>")
    .WithAuthority("https://login.microsoftonline.com/<tenant-id>")
    .WithRedirectUri("http://localhost")
    .Build();

var result = await client
    .AcquireTokenInteractive(["api://<agent-client-id>/access_agent"])
    .ExecuteAsync();

using var http = new HttpClient();
http.DefaultRequestHeaders.Authorization =
    new AuthenticationHeaderValue("Bearer", result.AccessToken);
using var response = await http.GetAsync("https://localhost:5001/whoami");
Console.WriteLine($"HTTP {(int)response.StatusCode}");
response.EnsureSuccessStatusCode();
Console.WriteLine(await response.Content.ReadAsStringAsync());

Exécutez dotnet run et connectez-vous en tant que l’utilisateur nommé dans l’octroi de consentement. Attendez HTTP 200 ainsi que l’ID d’objet de cet utilisateur et l’ID de locataire. Une requête à /whoami sans jeton doit renvoyer 401. Ne connectez pas le jeton ou n’utilisez pas de jeton d’ID à sa place.

Si votre API expose une autre étendue déléguée et que votre client de test a son consentement, demandez également un jeton pour cette étendue seule et appelez /whoami. Vérifiez que le jeton a l’audience de l’API de l’agent, mais qu’il manque access_agent, et que la demande est rejetée. Ce test négatif facultatif de scope nécessite un deuxième scope ; la configuration locale minimale définit uniquement access_agent. Un jeton pour une audience différente teste la validation de l’audience, et non l’autorisation d’étendue.

Si la connexion échoue, vérifiez l’URI de redirection du client de test et l’octroi par utilisateur avant de modifier la configuration de l’agent. Si HTTPS échoue, corrigez la confiance accordée au certificat de développement plutôt que de contourner la validation.

Nettoyer le test local

Arrêtez les deux projets une fois que vous avez terminé. Conservez le client de test et l’inscription de l’agent si vous passez à la tâche suivante. Lorsque vous n’avez plus besoin d’une autorisation de test, supprimez-la DELETE https://graph.microsoft.com/v1.0/oauth2PermissionGrants/<grant-id> par le biais du client de gestion avant de supprimer l’enregistrement de l’application cliente. Ne supprimez pas les clients partagés ni les subventions utilisées par d’autres utilisateurs.

Étape suivante

Appelez une API personnalisée en tant qu’utilisateur connecté. Pour restreindre les utilisateurs qui peuvent appeler l’agent, consultez Contrôler l’accès utilisateur aux agents.