Microsoft Entra Agent ID
Standards

Use an agent's user account with Microsoft 365

In brief

The page now recommends using agent identities with application permissions by default, creating an agent user account only for workloads requiring a user object, such as Teams membership, Exchange mailboxes, SharePoint sharing, or user-based licensing. It also outlines provisioning and access-assignment steps.

What Entra admins need to know

Administrators can avoid unnecessary agent accounts and licenses while ensuring required workload access and delegated permissions are assigned when an account is needed.

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.

Agent's user account impersonation protocol

Agent's user account impersonation enables agent identities to operate with user context through an agent's user account, combining user permissions with autonomous operation. In this scenario, an agent identity blueprint (actor 1) impersonates an agent identity (actor 2) that impersonatesUse an agent's user account (subject) using FIC. Accesswith Microsoft 365

Most autonomous agents should call APIs with their agent identity and application permissions. Create an agent's user account only when a Microsoft 365 workload requires a user object.

An agent's user account is scoped to delegationsa dedicated user identity for the agent. It isn't the signed-in user of an interactive agent. Each account has a one-to-one relationship with an agent identity.

Determine whether the agent needs a user object

ScenarioIs an agent's user account required?Guidance
Call an API that supports application permissionsNoUse the agent identity and app-only access.
Add the agent as a member of a Microsoft Teams teamYesTeam membership is assigned to directory users. See add members to a team.
Give the agent its own Exchange Online mailboxYesA mailbox is provisioned for a user object. See create user mailboxes in Exchange Online.
Share a SharePoint or OneDrive item directly with the agent as a personYesUse the agent's user account as the sharing recipient. See sharing files and folders.
Use a Microsoft 365 service that is licensed per userYesAssign only the licenses required by the service. See assign licenses to users.

Don't create an agent's user account only because the agent runs without a person present. If the target service supports application permissions or workload-specific application access controls, use the agent identity instead.

Provision access

  1. Create an agent's user account and associate it with the agent identity.
  2. Assign the account only the Microsoft 365 licenses it needs.
  3. Add the account to the required team, provision its mailbox, or share the required SharePoint resources by following the service documentation in the preceding table.
  4. Grant the agent identity delegated permissions for the Microsoft 365 scopes the workload requires, such as Mail.ReadWrite or Files.ReadWrite. The agent identity uses these delegated permissions when it authenticates as the agent's user account.

Creating the user object doesn't grant access to a team, mailbox, site, file, or API. Complete the workload-specific assignment separately.

Authenticate as the agent's user account

The agent's user account can be impersonated only byflow doesn't involve a singlesigned-in user. Use WithAgentUserIdentity to identify the dedicated user account. Microsoft.Identity.Web.AgentIdentities performs the Agent ID token exchange.

This example uses blueprint-to-child token exchange. Reuse the package installation and runtime configuration, including Microsoft.Identity.Web.AgentIdentities, AddAgentIdentities(), token acquisition, an HTTP client, and a token cache. Configure the blueprint's client ID and credential in the runtime; pass the child agent identity.

[!INCLUDE Use Microsoft SDKs]

[!INCLUDE Managed identities support]

Protocol steps

Then following are the protocol steps.

:::image type="content" source="media/agent-user-oauth-flow/agent-user-flow.png" alt-text="Diagram showing the illustration of agentidentity's client ID and its associated user account token acquisition flow for agents.":::to WithAgentUserIdentity. Don't substitute the single-instance app-only setup, which omits this Agent ID exchange registration.

  1. The agent identity blueprint requestsfollowing code is an exchange token (T1) that it uses for agent identity impersonation. The agent identity blueprint presents client credentials that could beendpoint fragment, not a secret, a certificate, or a managed identity token used as an FIC.

    [!INCLUDE Dont use secrets]

    complete host. Merge its POST /oauth2/v2.0/token
    Content-Type: application/x-www-form-urlencoded
    
    client_id=AgentBlueprint
    &scope=api://AzureADTokenExchange/.default
    &fmi_path=AgentIdentity
    &client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer
    &client_assertion=TUAMI
    &grant_type=client_credentials
    using

    Where TUAMI is directives at the MSI token for user assigned managed identity (UAMI)top of Program.cs and place its mapping before app.Run(). This returns token T1.

  2. The agent identity requests a token (T2) that it uses for agent's user account impersonation. The agent identity presents T1 as its client assertion. Microsoft Entra ID returns T2 toConfigure the inbound AgentUser authorization policy before exposing the mailbox endpoint. Resolve the agent identity after validating that T1 (aud) == Agent identity parent app == Agent identity blueprint.​and account from trusted application configuration, not caller-supplied values.

    POST /oauth2/v2.0/token
    Content-Type: application/x-www-form-urlencoded
    
    client_id=AgentIdentity
    &scope=api://AzureADTokenExchange/.default
    &client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer
    &client_assertion={T1}
    &grant_type=client_credentials
    

    This returns token T2.

  3. The agent identity then sends an OBO token exchange request to Microsoft Entra ID, including both T1 and T2. Microsoft Entra ID validates that T2 (aud) == agent identity.

    POST /oauth2/v2.0/token
    Content-Type: application/x-www-form-urlencoded
    
    client_id=AgentIdentity
    &scope=https://resource.example.com/scope1
    &client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer
    &client_assertion={T1}
    &user_federated_identity_credential={T2}
    &[email protected]
    &grant_type=user_fic
    &requested_token_use=on_behalf_of
    
  4. Microsoft Entra ID then issues the resource token.

Sequence diagram

The following sequence diagram showsIdentify the agent's user account impersonation flowby UPN:

:::image type=

using System.Net.Http.Headers;
using System.Security.Claims;
using Microsoft.Identity.Abstractions;
using Microsoft.Identity.Web;

app.MapGet("content/mailbox" source=, async (
    IAuthorizationHeaderProvider authorizationHeaderProvider,
    IHttpClientFactory httpClientFactory) =>
{
    var options = new AuthorizationHeaderProviderOptions()
        .WithAgentUserIdentity("media/<agent-identity-client-id>", "<agent-user-oauth-flow/upn>");

    string authorizationHeader = await authorizationHeaderProvider
        .CreateAuthorizationHeaderForUserAsync(
            ["https://graph.microsoft.com/.default"],
            options,
            new ClaimsPrincipal());

    HttpClient client = httpClientFactory.CreateClient();
    client.DefaultRequestHeaders.Authorization =
        AuthenticationHeaderValue.Parse(authorizationHeader);

    using HttpResponseMessage response =
        await client.GetAsync("https://graph.microsoft.com/v1.0/me/messages");
    response.EnsureSuccessStatusCode();

    return Results.Content(
        await response.Content.ReadAsStringAsync(),
        "application/json");
})
.RequireAuthorization("AgentUser");

Or identify the account by object ID:

var options = new AuthorizationHeaderProviderOptions()
    .WithAgentUserIdentity("<agent-identity-client-id>", Guid.Parse("<agent-user-flow-token-sequence.pngobject-id>" alt-text="Diagram showing));

Pass new ClaimsPrincipal() because no user is signed in. The user identity comes from WithAgentUserIdentity, not from the token sequence ofrequest context. Grant the agent's user account token acquisition flow for agents.":::

Agent's user account impersonation requires credential chaining that followsonly the pattern agent identity blueprint → Agent identity → Agentdelegated permissions the workload requires. Don's user account. Each step in this chain usest implement the token fromexchange directly.

For the previousprotocol model and security constraints, see OAuth protocols in Microsoft Entra Agent ID. For the full API reference, see Microsoft.Identity.Web on GitHub.

For an authorized inbound caller, a successful /mailbox call returns the configured agent user's messages, not the caller's mailbox. An empty message collection can be valid. If the call fails, check the identity-to-account association, delegated grant, and Exchange mailbox provisioning separately. The sample throws on a downstream non-success status rather than forwarding that status to the inbound caller.

For test-only resources, follow Delete an agent's user account after removing any workload-specific access you created. Don't delete a shared mailbox or account.

Next step as a credential, creating a secure delegation pathway. The same client ID must be used for both phases to prevent privilege escalation attacks.

Manage the agent's user account

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…