Microsoft Entra Agent ID
Authentication

Autonomous Agent Authentication Authorization Flow

In brief

The documentation page describing Entra ID authentication, token acquisition, application permissions, and optional agent user accounts for autonomous agents was deleted.

What Entra admins need to know

Administrators may no longer find this setup and admin-consent guidance at the documented page. No action or deadline is specified.

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.

deleted file mode 100644

title: Authenticate and acquire tokens for autonomous agents description: Learn how to authenticate autonomous agents with Microsoft Entra ID, grant application permissions, and optionally create and authenticate as an agent's user account. titleSuffix: Microsoft Entra Agent ID ms.topic: how-to ms.date: 06/15/2026 ms.reviewer: jomondi, dastrock

#customer-intent: As a developer building autonomous agents, I want to authenticate my agent, grant it application permissions, and optionally create an agent's user account, so that my agent can operate independently and access Microsoft Graph and other resources. ai-usage: ai-assisted ms.custom: msecd-doc-authoring-1013

Authenticate and acquire tokens for autonomous agents

Autonomous agents perform operations using their own identity rather than acting as a delegate of a user. To operate securely, an autonomous agent must authenticate with Microsoft Entra ID, obtain access tokens, and be granted the appropriate permissions. This article walks you through the end-to-end flow:

  1. Configure client credentials.
  2. Request a token for the agent identity blueprint.
  3. Request an agent identity token.
  4. Grant application permissions (admin consent).
  5. (Optional) Create and authenticate as an agent's user account for resources that require a user identity.

Prerequisites

Before implementing agent token authentication, ensure you have:

For admin authorization, you also need:

  • Administrator privileges in your Microsoft Entra ID tenant.
  • Understanding of the specific permissions your agent requires.

For agent's user account authentication, you also need:

Configure your client credentials

Get your client credential details. This could be your client secret, a certificate, or a managed identity that you're using as a federated identity credential.

[!INCLUDE Dont use secrets]

Microsoft Graph API

Gather the credential you configured on your agent identity blueprint. You need one of the following:

  • Managed identity (recommended): The managed identity client ID and a token from the Azure Instance Metadata Service (IMDS).
  • Certificate: The certificate thumbprint or PFX file.
  • Client secret (development only): The secret value.

Microsoft.Identity.Web

Configure Microsoft.Identity.Web to authenticate your agent identity blueprint using a federated identity credential. For production, use a managed identity as the federated identity credential:

{
  "AzureAd": {
    "Instance": "https://login.microsoftonline.com/",
    "TenantId": "<your-tenant-id>",
    "ClientId": "<agent-blueprint-client-id>",
    "ClientCredentials": [
      {
        "SourceType": "SignedAssertionFromManagedIdentity",
        "ManagedIdentityClientId": "<managed-identity-client-id>"
      }
    ]
  }
}

For local development and testing only, you can use a client secret instead:

{
  "AzureAd": {
    "Instance": "https://login.microsoftonline.com/",
    "TenantId": "<your-tenant-id>",
    "ClientId": "<agent-blueprint-client-id>",
    "ClientCredentials": [
      {
        "SourceType": "ClientSecret",
        "ClientSecret": "your-client-secret"
      }
    ]
  }
}

Request a token for the agent identity blueprint

When requesting the token for the agent identity blueprint, provide the agent identity's client ID in the fmi_path (Federated Managed Identity path) parameter. This parameter tells Microsoft Entra ID which agent identity the blueprint is acting on behalf of.

When using a client secret during local development, provide the client_secret parameter. For certificates and managed identities, use client_assertion and client_assertion_type instead.

Microsoft Graph API

Use the following token request to obtain a token for the agent identity blueprint:

POST https://login.microsoftonline.com/<your-tenant-id>/oauth2/v2.0/token
Content-Type: application/x-www-form-urlencoded

client_id=<agent-blueprint-client-id>
&scope=api://AzureADTokenExchange/.default
&grant_type=client_credentials
&client_secret=<client-secret>
&fmi_path=<agent-identity-client-id>

Microsoft.Identity.Web

With Microsoft.Identity.Web, you don't need to explicitly request a token for the agent identity blueprint. Microsoft.Identity.Web does it for you.

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

Request an agent identity token

Microsoft Graph API

Once you have the agent identity blueprint token (T1), use it to request the agent identity token.

POST https://login.microsoftonline.com/<your-tenant-id>/oauth2/v2.0/token
Content-Type: application/x-www-form-urlencoded

client_id=<agent-identity-client-id>
&scope=https://graph.microsoft.com/.default
&grant_type=client_credentials
&client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer
&client_assertion=<agent-blueprint-token-T1>

Microsoft.Identity.Web

Microsoft.Identity.Web handles the details of token acquisition protocol for you, provided you use the new services.AddAgentIdentities() in your service collection at the initialization of the application.

Initialize the application:

// Program.cs
using Microsoft.AspNetCore.Authorization;
using Microsoft.Identity.Abstractions;
using Microsoft.Identity.Web;
using Microsoft.Identity.Web.Resource;
using Microsoft.Identity.Web.TokenCacheProviders.InMemory;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddMicrosoftIdentityWebApiAuthentication(builder.Configuration);
builder.Services.AddAgentIdentities();
builder.Services.AddInMemoryTokenCaches();

Use the .WithAgentIdentity() pattern to request access tokens:

// In an API endpoint or service method where HttpContext is available
app.MapGet("/call-api", async (HttpContext httpContext) =>
{
    IAuthorizationHeaderProvider authorizationHeaderProvider =
        httpContext.RequestServices.GetRequiredService<IAuthorizationHeaderProvider>();

    AuthorizationHeaderProviderOptions options =
        new AuthorizationHeaderProviderOptions().WithAgentIdentity("<agent-identity-client-id>");

    // Request agent identity tokens
    string authorizationHeader = await authorizationHeaderProvider
        .CreateAuthorizationHeaderForAppAsync("https://graph.microsoft.com/.default", options);

    // The authHeader contains "Bearer " + the access token
    return Results.Ok(authorizationHeader);
});

Grant application permissions

Agents often need to take actions in Microsoft Graph and other web services that require a Microsoft Entra ID application permission (represented as app roles). Autonomous agents need to request these permissions from a Microsoft Entra ID administrator.

There are two ways to grant application permissions to an autonomous agent:

  • An admin can create an appRoleAssignment by using Microsoft Graph APIs or PowerShell.
  • The agent can direct the admin to a consent page using an admin consent URL.

Create an app role assignment via APIs

Use the following steps to get an app role assignment.

  1. Request an agent identity token with the application permissions Application.Read.All and AppRoleAssignment.ReadWrite.All.

  2. Get the object ID of the resource service principal that you're trying to access. For example, to find the Microsoft Graph service principal object ID:

    1. Go to the Microsoft Entra admin center.
    2. Navigate to Entra ID --> Enterprise Applications
    3. Filter by Application type == Microsoft Applications
    4. Search for Microsoft Graph.
  3. Get the unique ID of the app role you want to assign from the Microsoft Graph permissions reference.

  4. Create the app role assignment:

    Microsoft Graph API

    POST https://graph.microsoft.com/v1.0/servicePrincipals/<agent-identity-id>/appRoleAssignments
    Authorization: Bearer <token>
    Content-Type: application/json
    
    {
      "principalId": "<agent-identity-id>",
      "resourceId": "<microsoft-graph-sp-object-id>",
      "appRoleId": "<app-role-id>"
    }
    

    Microsoft Graph PowerShell

    Connect-MgGraph -Scopes "Application.Read.All AppRoleAssignment.ReadWrite.All" -TenantId <your-tenant-id>
    
    # Get the service principal for Microsoft Graph (well-known app ID)
    $graphSp = Get-MgServicePrincipal -Filter "appId eq '00000003-0000-0000-c000-000000000000'"
    
    # Get your application's service principal (replace with your app's client ID)
    $agentId = "<agent-identity-id>"
    
    # Find the App Role ID for "User.ReadBasic.All"
    $userReadBasicRole = $graphSp.AppRoles | Where-Object {
        $_.Value -eq "User.ReadBasic.All" -and $_.AllowedMemberTypes -contains "Application"
    }
    
    # Assign the app role
    New-MgServicePrincipalAppRoleAssignment -ServicePrincipalId $agentId `
        -PrincipalId $agentId `
        -ResourceId $graphSp.Id `
        -AppRoleId $userReadBasicRole.Id
    

Request authorization from a tenant administrator

To grant application permissions, construct the authorization URL that is used to prompt the administrator. The role parameter is used to specify the requested application permissions.

Be sure to use the agent identity client ID in the following request.

https://login.microsoftonline.com/contoso.onmicrosoft.com/v2.0/adminconsent
?client_id=<agent-identity-client-id>
&role=https://graph.microsoft.com/User.Read.All
&redirect_uri=https://entra.microsoft.com/TokenAuthorize
&state=xyz123

Agent implementations might redirect the admin to this URL in various ways, such as including it in a message sent to the admin in a chat window. When the admin is redirected to this URL, they're asked to sign in and grant consent to the permissions specified in the scope parameter. At the moment you must use the redirect URI listed, which directs the admin to a blank page after granting consent.

After you grant your agent identity blueprint the required permissions, request a new agent access token for the permissions to take effect.

Authenticate as an agent's user account

In addition to operating with app-only tokens, autonomous agents can authenticate as an agent's user account. Agents' user accounts are a special type of user account in Microsoft Entra purpose-built for use by agents. They're most commonly used when an agent needs to connect to systems that require the existence of a user account, for instance, a mailbox, Teams channel, or other user-specific resources.

Each agent identity can only have a single associated agent's user account, and each agent's user account can only be associated with a single agent identity.

Get authorization to create agents' user accounts

To create agents' user accounts, your agent identity blueprint must be granted the application permission AgentIdUser.ReadWrite.IdentityParentedBy in the tenant. You can obtain authorization in one of two ways:

If you wish to use a different client, not the agent identity blueprint, to create agents' user accounts, that client needs to obtain the AgentIdUser.ReadWrite.All delegated or application permission instead.

Create an agent's user account

Create an agent's user account using your agent identity blueprint or other approved client. The recommended way to create an agent's user account is using your agent identity blueprint. You need to get an access token using the agent identity blueprint to create an agent's user account.

REST

Once you have an access token with the necessary permission, make the following request:

POST https://graph.microsoft.com/beta/users
OData-Version: 4.0
Content-Type: application/json
Authorization: Bearer <token>

{
  "@odata.type": "microsoft.graph.agentUser",
  "displayName": "New Agent User",
  "userPrincipalName": "[email protected]",
  "identityParentId": "{agent-identity-id}",
  "mailNickname": "agentuserupn",
  "accountEnabled": true
}

Microsoft.Identity.Web

To use Microsoft.Identity.Web to create an agent's user account, follow these steps:

  1. Add the following to your config file:

    {
      "AzureAd": {
        "Instance": "https://login.microsoftonline.com/",
        "TenantId": "<your-tenant-id>",
        "ClientId": "<my-agent-blueprint-id>",
        "Scopes": "access_agent",
        "ClientCredentials": [
          {
            "SourceType": "SignedAssertionFromManagedIdentity",
            "ManagedIdentityClientId": "managed-identity-client-id"  // Omit for system-assigned
          }
        ]
      },
    
      "DownstreamApis": {
        "agent-identity": {
          "BaseUrl": "https://graph.microsoft.com",
          "RelativePath": "/v1.0/users",
          "Scopes": ["00000003-0000-0000-c000-000000000000/.default"],
          "RequestAppToken": true
        }
      }
    }
    
  2. Add required packages

    dotnet add package Microsoft.Identity.Web
    dotnet add package Microsoft.Identity.Web.AgentIdentities
    
  3. Configure services.

    using Microsoft.Identity.Abstractions;
    using Microsoft.Identity.Web;
    using Microsoft.Identity.Web.Resource;
    using Microsoft.IdentityModel.S2S.Extensions.AspNetCore;
    
    var builder = WebApplication.CreateBuilder(args);
    
    // Add services to the container.
    builder.Services.AddMicrosoftIdentityWebApiAuthentication(builder.Configuration)
        .EnableTokenAcquisitionToCallDownstreamApi();
    builder.Services.AddAgentIdentities();
    builder.Services.AddInMemoryTokenCaches();
    
    var app = builder.Build();
    app.UseHttpsRedirection();
    app.UseAuthentication();
    app.UseAuthorization();
    app.Run();
    
  4. Create the agent's user account creation endpoint.

    app.MapPost("/create-agent-id-user", async (HttpContext httpContext) =>
    {
        try
        {
            // Get the service to call the downstream API (preconfigured in the appsettings.json file)
            IDownstreamApi downstreamApi = httpContext.RequestServices.GetRequiredService<IDownstreamApi>();
    
            var requestBody = new AgentIdUser
            {
                displayName = "my-agent-name",
                mailNickname = "my-agent-alias",
                userPrincipalName = "my-agent-email-address",
                accountEnabled = true,
                identityParentId = "<associated-agent-identity-id>"
            };
    
            // Call the downstream API (Graph) with a POST request to create an agent's user account
            var jsonResult = await downstreamApi.PostForAppAsync<AgentIdUser, AgentIdUser>(
                "agent-identity",
                requestBody
            );
    
            return Results.Json(jsonResult);
        }
        catch (Exception ex)
        {
            return ex.Message;
        }
    })
    

Once you have your agent's user account created, you don't need to configure anything else. These accounts don't have any credentials and can only be authenticated using the protocol described in the next sections.

Grant consent to agent identity

Agents' user accounts behave like any other user account. Before you can request tokens using your agent's user account, you need to authorize the agent identity to act on its behalf. You can authorize the agent identity by requesting authorization from a tenant administrator or manually create an oAuth2PermissionGrant using Microsoft Graph or Microsoft Graph PowerShell.

For Microsoft Graph, your request is as shown in the following snippet:

POST https://graph.microsoft.com/v1.0/oauth2PermissionGrants
Authorization: Bearer {token}
Content-Type: application/json

{
  "clientId": "{agent-identity-id}",
  "consentType": "Principal",
  "principalId": "{agent-id-user-object-id}",
  "resourceId": "{ms-graph-service-principal-object-id}",
  "scope": "Mail.Read"
}

For Microsoft Graph PowerShell, use the following script:

Connect-MgGraph -Scopes "DelegatedPermissionGrant.ReadWrite.All" -TenantId <your-tenant-id>

# Get the service principal for Microsoft Graph
$graphSp = Get-MgServicePrincipal -Filter "appId eq '00000003-0000-0000-c000-000000000000'"

# Get the service principal for your client app
$clientSp = Get-MgServicePrincipal -Filter "appId eq '{agent-identity-id}'"

# Create the delegated permission grant
New-MgOauth2PermissionGrant -BodyParameter @{
    clientId    = $clientSp.Id
    consentType = "Principal"
    principalId = "{agent-id-user-object-id}"
    resourceId  = $graphSp.Id
    scope       = "Mail.Read"
}

Request an agent's user account token

To authenticate an agent's user account, you need to follow a three-step process:

  1. Get a token as the agent identity blueprint.
  2. Use that token to get another token as the agent identity.
  3. Use both previous tokens to get another token as the agent's user account.

REST

First, request a token as the agent identity blueprint, as described in Request a token for the agent identity blueprint. Once you have the agent identity blueprint token, use the agent identity blueprint token to request a Federated Identity Credential (FIC) for your agent identity:

POST https://login.microsoftonline.com/<your-tenant-id>/oauth2/v2.0/token
Content-Type: application/x-www-form-urlencoded

client_id=<agent-identity-id>
&scope=api://AzureADTokenExchange/.default
&grant_type=client_credentials
&client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer
&client_assertion=<agent-blueprint-token>

This returns an exchange token (T2) for the agent identity. Use it in the next request to obtain a delegated token for the agent's user account:

POST https://login.microsoftonline.com/<your-tenant-id>/oauth2/v2.0/token
Content-Type: application/x-www-form-urlencoded

client_id=<agent-identity-id>
&scope=https://graph.microsoft.com/.default
&grant_type=user_fic
&client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer
&client_assertion=<agent-blueprint-token>
&user_id=<agent-user-object-id>
&user_federated_identity_credential=<agent-identity-token>

This gives you a delegated access token you can use to call Microsoft Graph as your agent's user account. You can use user_id=<user-object-id> instead of username=<UPN> for the user identifier.

Microsoft.Identity.Web

Microsoft.Identity.Web handles the token acquisition for you. Use the .WithAgentUserIdentity() pattern to request access tokens.

// In an API endpoint or service method where HttpContext is available
app.MapGet("/agent-user-token", async (HttpContext httpContext) =>
{
    IAuthorizationHeaderProvider authorizationHeaderProvider =
        httpContext.RequestServices.GetRequiredService<IAuthorizationHeaderProvider>();

    // Configure options for the agent's user account identity
    string agentIdentity = "agent-identity-id";
    string userId = "<user-object-id>";
    var options = new AuthorizationHeaderProviderOptions()
        .WithAgentUserIdentity(agentIdentity, userId);

    // Create a ClaimsPrincipal to enable token caching
    ClaimsPrincipal user = new ClaimsPrincipal();

    // Acquire a user token
    string authHeader = await authorizationHeaderProvider
        .CreateAuthorizationHeaderForUserAsync(
            scopes: ["https://graph.microsoft.com/.default"],
            options: options,
            user: user);

    return Results.Ok(authHeader);
});

You can also use the agent's user account principal name instead of the object ID.


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…