Condividi tramite

Chiamare un'API Microsoft Graph da un agente usando .NET

Questo articolo illustra come chiamare un'API Microsoft Graph da un agente usando le identità dell'agente o l'account utente di un agente.

Per chiamare un'API da un agente, è necessario ottenere un token di accesso che l'agente può usare per autenticarsi all'API. È consigliabile usare Microsoft.Identity.Web SDK per .NET per chiamare le API Web. Questo SDK semplifica il processo di acquisizione e convalida dei token. Per altre lingue, usare Microsoft Entra agent SDK per l'ID agente.

Prerequisiti

  • Identità dell'agente con autorizzazioni appropriate per chiamare l'API di destinazione. È necessario un utente per il flusso on-behalf-of.
  • Account utente di un agente con autorizzazioni appropriate per chiamare l'API di destinazione.

Chiamare un'API Microsoft Graph

  1. Installare Microsoft.Identity.Web.GraphServiceClient che gestisce l'autenticazione per Graph SDK e il pacchetto Microsoft.Identity.Web.AgentIdentities per aggiungere il supporto per le identità dell'agente.

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

  2. Aggiungi il supporto per Microsoft Graph e le identità degli agenti nella raccolta di servizi.

    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. Configurare le opzioni di identità di Graph e agente in appsettings.json.

    Avviso

    I segreti client non devono essere usati come credenziali client negli ambienti di produzione per i progetti di identità agente a causa di rischi per la sicurezza. Usare invece metodi di autenticazione più sicuri, ad esempio le credenziali di identità federate (FIC) con identità gestite o certificati client. Questi metodi offrono una sicurezza avanzata eliminando la necessità di archiviare segreti sensibili direttamente all'interno della configurazione dell'applicazione.

    {
  "AzureAd": {
    "Instance": "https://login.microsoftonline.com/",
    "TenantId": "<my-test-tenant>",
    "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"]
    }
  }
}

  4. Ora puoi ottenere la funzionalità GraphServiceClient iniettandola nel tuo servizio o tramite il provider di servizi e chiamare Microsoft Graph.

  • Per le identità degli agenti, è possibile acquisire un token solo per l'app (agenti autonomi) o un token per conto dell'utente (agenti interattivi) usando il metodo WithAgentIdentity. Per i token per sole app, impostare la proprietà RequestAppToken su true. Per i token "delegati per conto dell'utente," non impostare la proprietà RequestAppToken o impostarla esplicitamente su false.

    // 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 applications = await graphServiceClient.Applications
    .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 applications = await graphServiceClient.Applications
    .GetAsync(r => r.Options.WithAuthenticationOptions(options =>
    {
        options.WithAgentIdentity(agentIdentity);
        options.RequestAppToken = false; // False to show it's on-behalf of user
    }));

    • Per le identità dell'account utente dell'agente, è possibile specificare il User Principal Name (UPN) o l'Object Identity (OID) per identificare l'account utente dell'agente usando il metodo WithAgentUserIdentity.

      // 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 me = await graphServiceClient.Me
    .GetAsync(r => r.Options.WithAuthenticationOptions(options =>
        options.WithAgentUserIdentity(agentIdentity, userOid)));

Contenuti correlati

  • Last updated on