Appeler une API Microsoft Graph à partir d’un agent avec .NET

Cet article explique comment appeler un API Graph Microsoft à partir d'un agent à l'aide d'identités d'agent ou du compte d'utilisateur d'un agent.

Pour appeler une API à partir d’un agent, vous devez obtenir un jeton d’accès que l’agent peut utiliser pour s’authentifier auprès de l’API. Nous vous recommandons d’utiliser le Microsoft.Identity.Web SDK pour .NET pour appeler vos API web. Ce SDK simplifie le processus d’acquisition et de validation de jetons. Pour les autres langages de programmation, utilisez le Microsoft Entra ID Auth SDK (sidecar).

Prerequisites

  • Identité d’agent disposant des autorisations appropriées pour appeler l’API cible. Vous avez besoin d’un utilisateur pour le flux de délégation de droits.
  • Compte d’utilisateur d’un agent disposant des autorisations appropriées pour appeler l’API cible.

Appeler une API Microsoft Graph

  1. Installez le Microsoft. Identity.Web.GraphServiceClient qui gère l’authentification pour le SDK Graph et le Microsoft. Package Identity.Web.AgentIdentities pour ajouter la prise en charge des identités d’agent.

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

  2. Ajoutez la prise en charge de Microsoft Graph et d’identités d’agent dans votre collection de services.

    using Microsoft.AspNetCore.Authentication.OpenIdConnect;
using Microsoft.Identity.Web;

var builder = WebApplication.CreateBuilder(args);

// Add authentication (web app or web API)
builder.Services.AddAuthentication(OpenIdConnectDefaults.AuthenticationScheme)
    .AddMicrosoftIdentityWebApp(builder.Configuration.GetSection("AzureAd"))
    .EnableTokenAcquisitionToCallDownstreamApi()
    .AddInMemoryTokenCaches();

// Add Microsoft Graph support
builder.Services.AddMicrosoftGraph();

// Add Agent Identities support
builder.Services.AddAgentIdentities();

var app = builder.Build();
app.UseAuthentication();
app.UseAuthorization();
app.Run();

  3. Configurer les options d’identité graph et d’agent dans appsettings.json.

    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": "<your-tenant-id>",
    "ClientId": "<agent-blueprint-client-id>",
    "ClientCredentials": [
      {
        "SourceType": "ClientSecret",
        "ClientSecret": "your-client-secret"
      }
    ]
  },
  "DownstreamApis": {
    "MicrosoftGraph": {
      "BaseUrl": "https://graph.microsoft.com/v1.0",
      "Scopes": ["User.Read", "User.ReadBasic.All"]
    }
  }
}

    Note

    Configurez uniquement les autorisations Microsoft Graph dont votre agent a besoin, et assurez-vous que les Scopes que vous définissez correspondent aux ressources Graph appelées par votre code. Ces exemples utilisent User.Read et User.ReadBasic.All; l’appel d’autres ressources nécessite leurs autorisations correspondantes.

  4. Vous pouvez maintenant obtenir le GraphServiceClient soit en l’injectant dans votre service, soit à partir du fournisseur de services, puis appeler Microsoft Graph.

  • Pour les identités d’agent, vous pouvez acquérir un jeton d’application uniquement (agents autonomes) ou un jeton d’utilisateur (agents interactifs) en utilisant la WithAgentIdentity méthode. Pour les jetons d’application uniquement, définissez la RequestAppToken propriété sur true. Pour les jetons d’utilisateur délégués au nom de quelqu'un d'autre, ne définissez pas la propriété RequestAppToken ou définissez-la explicitement sur false.

    using Microsoft.Graph;
using Microsoft.Identity.Web;

// Get the GraphServiceClient
GraphServiceClient graphServiceClient = serviceProvider.GetRequiredService<GraphServiceClient>();

string agentIdentity = "agent-identity-guid";

// Call Microsoft Graph APIs with the agent identity for app only scenario
var usersAppOnly = await graphServiceClient.Users
    .GetAsync(r => r.Options.WithAuthenticationOptions(options =>
    {
        options.WithAgentIdentity(agentIdentity);
        options.RequestAppToken = true; // Set to true for app only
    }));

// Call Microsoft Graph APIs with the agent identity for on-behalf of user scenario
var usersOnBehalfOfUser = await graphServiceClient.Users
    .GetAsync(r => r.Options.WithAuthenticationOptions(options =>
    {
        options.WithAgentIdentity(agentIdentity);
        options.RequestAppToken = false; // False to show it's on-behalf of user
    }));

    • Pour les identités de compte d’utilisateur de l’agent, vous pouvez spécifier le nom d’utilisateur principal (UPN) ou l’identité d’objet (OID) pour identifier le compte d’utilisateur de l’agent à l’aide de la WithAgentUserIdentity méthode.

      using Microsoft.Graph;
using Microsoft.Identity.Web;

// Get the GraphServiceClient
GraphServiceClient graphServiceClient = serviceProvider.GetRequiredService<GraphServiceClient>();

string agentIdentity = "agent-identity-guid";

// Call Microsoft Graph APIs with the agent's user account identity using UPN
string userUpn = "user-upn";
var me = await graphServiceClient.Me
    .GetAsync(r => r.Options.WithAuthenticationOptions(options =>
        options.WithAgentUserIdentity(agentIdentity, userUpn)));

// Or using OID
string userOid = "user-object-id";
var meByOid = await graphServiceClient.Me
    .GetAsync(r => r.Options.WithAuthenticationOptions(options =>
        options.WithAgentUserIdentity(agentIdentity, userOid)));

Contenu connexe

  • Last updated on