Microsoft Entra Agent ID
Developer

Call Microsoft Graph as an agent with ASP.NET Core

In brief

The article was rewritten to show configuring GraphServiceClient to call Microsoft Graph with an app-only token for an agent identity. Examples for delegated user tokens and agent user-account identities were removed.

What Entra admins need to know

Administrators supporting agent implementations should use the updated guidance and ensure only the required Microsoft Graph application permissions are configured.

This editorial summary was generated by AI from the documentation changes. Verify important details in the full Microsoft Learn article.

Documentation change

The comparison below shows only the changed extract. Use the full-page view for complete context.

Call Microsoft Graph as an agent with ASP.NET Core

List directory users with the agent's application permissions, not the inbound caller's delegated access.

In this article, you configure GraphServiceClient to obtain a Microsoft Graph token for the agent while the agent API from an agent using .NET

This article explains how to call aseparately authorizes the caller.

Prerequisites

Add Microsoft Graph

  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.integration package:

    dotnet add package Microsoft.Identity.Web.GraphServiceClient
    dotnet

    Register GraphServiceClient with the services configured in the parent article. For app-only access, call builder.Services.AddMicrosoftGraph with options.BaseUrl set to https://graph.microsoft.com/v1.0 and options.Scopes set to ["https://graph.microsoft.com/.default"]. Use the configured client ID directly; don't add package Microsoft.Identity.Web.AgentIdentities WithAgentIdentity

  2. .

    AddPlace this registration before builder.Build() in the support for Microsoft Graph and agent identities in your service collection.API's Program.cs.

    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 appoptions = builder.Build();
    app.UseAuthentication();
    app.UseAuthorization();
    app.Run();
    
  3. Configure Graph and agent identity options in appsettings.json.

    [!INCLUDE Dont use secrets]

    >
    {
        "AzureAd": {
        "Instance": "https://login.microsoftonline.com/",
        "TenantId": "<your-tenant-id>",
        "ClientId": "<agent-blueprint-client-id>",
        "ClientCredentials": [
          {
            "SourceType": "ClientSecret",
            "ClientSecret": "your-client-secret"
          }
        ]
      },
      "DownstreamApis": {
        "MicrosoftGraph": {
          "options.BaseUrl": = "https://graph.microsoft.com/v1.0";
        options.Scopes = ["https://graph.microsoft.com/.default"];
    });
    

    Call Microsoft Graph

    Set RequestAppToken to true so GraphServiceClient acquires an app-only token for the agent identity:

    Merge the following using directives with those at the top of Program.cs, and insert the endpoint before its single app.Run(). You can omit the custom API endpoint.

    using Microsoft.Graph;
    using Microsoft.Identity.Web;
    
    app.MapGet("Scopes": ["User.Read/graph-users", async (GraphServiceClient graphClient) =>
    {
        var users = await graphClient.Users.GetAsync(request =>
            request.Options.WithAuthenticationOptions(options =>
            {
                options.RequestAppToken = true;
            }));
    
        return Results.Ok(users?.Value);
    })
    .RequireAuthorization("User.ReadBasic.AllAgentUser"]
        }
      }
    });
    
  1. 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.

    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
        }));
    
    • For agent's user account identities, you can specify either User Principal Name (UPN) or Object Identity (OID) to identify the agent's user account by using the WithAgentUserIdentity method.

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

Related content

  • Call custom APIs

    The client uses the shared client ID and blueprint credential configured in the parent article. Don't add an Agent ID override. The example requires an application permission that can list users, such as User.Read.All. Grant only the permissions required by your calls.

    Verify the Graph call

    Follow the parent journey's API access test, replacing /custom-api with /graph-users. Expect 200 and a JSON collection of users when the agent has the required Graph application permission. This endpoint returns the first response page, not necessarily every user in the directory.

    Without an inbound token, expect 401. With an otherwise valid token missing Agent.User, expect 403 if the tenant issues that token. A downstream Graph failure causes the sample to throw rather than returning that same status from the agent. Verify Graph consent on the agent identity separately from the caller's role assignment.

    Next step

    Authenticate users to the agent API

    Related content

Daily Entra.News

Get daily email updates

Get a concise summary of the latest Microsoft Entra updates delivered straight to your inbox.

Loading the secure signup form…