Modifica

Condividi tramite

Call a Microsoft Graph API from an agent using .NET

This article explains how to call a Microsoft Graph API from an agent using agent identities or agent user.

To call an API from an agent, you need to obtain an access token that the agent can use to authenticate itself to the API. We recommend using the Microsoft.Identity.Web SDK for .NET to call your web APIs. This SDK simplifies the process of acquiring and validating tokens. For other languages, use the Microsoft Entra agent SDK for agent ID.

Prerequisites

  • An agent identity with appropriate permissions to call the target API. You need a user for the on-behalf-of flow.
  • An agent user with appropriate permissions to call the target API.

Call a Microsoft Graph API

  1. Install the Microsoft.Identity.Web.GraphServiceClient that handles authentication for the Graph SDK and the Microsoft.Identity.Web.AgentIdentities package to add support for agent identities.

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

  2. Add the support for Microsoft Graph and agent identities in your service collection.

    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. Configure Graph and agent identity options in appsettings.json.

    Warning

    Client secrets shouldn't be used as client credentials in production environments for agent identity blueprints due to security risks. Instead, use more secure authentication methods such as federated identity credentials (FIC) with managed identities or client certificates. These methods provide enhanced security by eliminating the need to store sensitive secrets directly within your application configuration.

    {
  "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. You can now get the GraphServiceClient injecting it in your service or from the service provider and call Microsoft Graph.

  • For agent identities, you can acquire either an app only token (autonomous agents) or an on-behalf of user token (interactive agents) by using the WithAgentIdentity method. For app only tokens, set the RequestAppToken property to true. For delegated on-behalf of user tokens, don't set the RequestAppToken property or explicitly set it to 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
    }));

    • For agent user identities, you can specify either User Principal Name (UPN) or Object Identity (OID) to identify the agent user by using the WithAgentUserIdentity method.

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

string agentIdentity = "agent-identity-guid";

// Call Microsoft Graph APIs with the agent user 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)));

Related content

  • Last updated on