Choose an authentication protocol for an agent
In brief
The article now maps local, hosted, delegated, and autonomous agents to recommended OAuth flows, including authorization code with PKCE, OBO, client credentials, and agent user-account impersonation. It also adds guidance on client types, instance modes, MSAL, and CIMD.
What Entra admins need to know
Use the updated guidance to select the correct token acquisition path and configure local agents as public clients in single-instance mode.
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.
Authentication protocols in agentsChoose an authentication protocol for an agent
Agents use OAuth 2.0 protocols with specialized token exchange patterns enabled by Federated Identity Credentials (FIC). All agent auth flows involve multi-stage token exchangesThe right authentication protocol depends on where the agent runs and whose identity blueprint impersonatesit uses to access a resource. Start with these questions:
- Does the agent
identity to perform operations. This article explainsrun on a user's device or in a hosted service? - Does the agent act for a signed-in user, as itself, or as a dedicated agent user account?
- If it acts for a signed-in user, does the agent initiate sign-in or receive a user access token from another application?
Use Microsoft Authentication Library (MSAL) or another supported authentication protocols and token flows used by agents. It covers delegation scenarios, autonomous operations, and federated identity credential patterns. Microsoft recommends that you use our SDKs like Microsoft Entra ID Auth SDK (sidecar) since implementing theselibrary instead of constructing protocol steps isn't easy.
All agent entities are confidential clients that can also serve as APIs for On-Behalf-Of scenarios. Interactive flows aren't supported for any agent entity type, ensuring that all authentication occurs through programmatic token exchanges rather than user interaction flows.requests directly.
[!INCLUDE Use Microsoft SDKs]
PrerequisitesChoose a protocol
| Use case | Recommended protocol | Access type | Client type |
|---|---|---|---|
| A local agent runs on an endpoint device and signs in the user | Authorization code flow with Proof Key for Code Exchange (PKCE) | Delegated | Public |
| A hosted agent receives a user access token from a client application and calls another service for that user | On-Behalf-Of (OBO) flow | Delegated | Confidential |
| A hosted agent runs without a user and accesses resources as itself | Client credentials flow; blueprint impersonation for multi-instance Agent IDs | Application | Confidential |
| An autonomous agent needs a mailbox or another resource available only to a user | Agent's user account impersonation | Delegated permissions assigned to the agent's user account | Confidential |
If more than one row applies, use a separate token acquisition path for each operating mode. For example, a hosted agent might use OBO for requests initiated by a user and app-only access for scheduled work that doesn't have user context.
The blueprint's instance mode also affects token acquisition. A single-instance Agent ID (preview) uses the shared blueprint client ID directly for authorization code, refresh, client credentials, and OBO requests. It doesn't acquire an intermediate blueprint impersonation token. Single-instance mode isn't limited to local or public clients. For an overview and links to the consent and SDK walkthroughs, see Authentication for a single-instance agent identity. To start with a platform-specific walkthrough, see Choose an integration path for an agent.
Local agent that signs in a user
If you aren't familiar already, go throughChoose the following protocol docs.authorization code flow with PKCE when the agent:
Microsoft identity platform and OAuth 2.0 On-Behalf-Of flowRuns on a desktop, mobile device, or other endpoint.Microsoft identity platform and the OAuth 2.0 client credentials flowCan open a browser for interactive sign-in.- Accesses protected services for the signed-in user.
- Can't securely store a client secret, certificate, or federated identity credential.
The local agent is a public client. It sends the user to the Microsoft identity platform /authorize endpoint, receives an authorization code at its registered redirect URI, and redeems the code by using a PKCE verifier. It doesn't present a client credential.
A registered public-client Agent ID must use single-instance mode. Every installation uses the same client ID; don't create an Agent ID for each device. A local agent can alternatively use a Client ID Metadata Document (CIMD) URL as its client ID.
Don't use this flow for a hosted agent that receives a user access token from another application. Use OBO instead.
For implementation and protocol details, see:
- Authenticate a local agent with Microsoft Entra ID
- OAuth 2.0 authorization code grant
- Microsoft identity platform and OAuth 2.0 authorization code flow
- Public client and confidential client applications
Supported grant types
The following are the supported grant types forHosted agent applications.
Agent identity blueprint
Agent identity blueprints support client_credentials enabling secure token acquisition for impersonation scenarios. The jwt-bearer grant type facilitates token exchanges in On-Behalf Of scenarios, allowing for delegation patterns. refresh_token grants enable background operations with user context, supporting long-running processes that maintain user authorization.
Agent identity
Agent identities use client_credentials for app-only autonomous operations, enabling independent functionality without user context, and impersonationacts for a signed-in user
Choose the OBO flow when:
- A client application signs in the user.
- The client calls the hosted agent or its API with a user
agent identity. Thejwt-bearergrant type supports both client credential flow and On-Behalf Of (OBO) flow providing flexibility in delegation patterns.refresh_tokengrants facilitate background user-delegated operations, allowing agent identities to maintain user context across extended operations.Unsupported flows- access token.
- The agent
application model explicitly excludes certain authentication patternsmust call a downstream API with the user's identity and delegated permissions.
The hosted agent is a confidential client. It doesn't start another interactive sign-in. Instead, it exchanges the incoming user access token for a token to maintain security boundaries. Agents arenthe downstream resource. The incoming token must be intended for the agent's blueprint; don't supportedrelay a token issued for interactive (/authorize) flows, ensuring all authentication occurs programmatically.
For a multi-instance Agent ID, configure the required delegated permissions as confidential clients.
response_type=noneDon't use OBO when no signed-in user initiated the operation. Use app-only access for autonomous work.
For implementation and protocol details, see:
- Agent OAuth flows: On behalf of flow
- Microsoft identity platform and OAuth 2.0 On-Behalf-Of flow
- Configure inheritable permissions for agent identity blueprints
Core protocol patternsHosted agent that acts as itself
Agents can operate in three primary modes:Choose the client credentials flow with Agent ID impersonation when the agent:
Agents operatingRuns in a hosted service that can protect a credential.- Performs scheduled, event-driven, or other autonomous work.
- Accesses a resource as the Agent ID rather than as a user.
For a multi-instance Agent ID, the blueprint first authenticates and obtains a token-exchange token for its child Agent ID. The Agent ID then uses that token as a client assertion in the client credentials flow. A single-instance Agent ID instead authenticates directly with the shared client ID and a credential on behalf of regular users in Microsoft Entrathe blueprint. The resource token contains application permissions granted by an administrator and identifies the Agent ID (interactive agents). This isas the actor.
Use a regular on-behalf-of flow.
[!INCLUDE Managed identities support]
[!INCLUDE Dont use secrets]
Oauth protocols
There are three agent oauth flows:Don't use application permissions when the resource should apply a signed-in user's permissions or consent. Use authorization code with PKCE or OBO instead.
:::image type="content" source="media/agent-oauth-protocols/agent-flows.png" alt-text="Diagram showing the illustration of oauth flow for agents." lightbox="media/agent-oauth-protocols/agent-flows.png":::For implementation and protocol details, see:
Agent on-behalf of flow: Agents operatingAgent autonomous app OAuth flow- Microsoft identity platform and the OAuth 2.0 client credentials flow
- Workload identity federation
Autonomous agent that acts as a dedicated user
Choose agent's user account impersonation only when an autonomous agent needs capabilities that are available to a user but not to an application identity. For example, an agent might need its own mailbox.
An agent's user account is a dedicated user identity for the agent, not the account of the person using the agent. The Agent ID impersonates this account through an agent-specific token exchange. Access is limited by the permissions assigned to the Agent ID and the agent's user account.
Don't create an agent's user account only to run unattended work. If the resource supports application permissions, prefer app-only access so the workload doesn't depend on behalf of regular users (interactive agents)a user identity.
For implementation details, see:
Related authentication concepts
The following settings affect authentication but don't replace the protocol choice:
- Public or confidential client describes whether the agent can securely hold a credential. For more information, see Public client and confidential client applications.
Autonomous app flow: App-only operations enable agentManaged identity, certificate, secret, or federated identity credential describes how a confidential client proves its identity. Prefer managed identitiesto act autonomouslyand federated identity credentials when possible.- CIMD or registered client ID describes how a public client is identified. Both options can use authorization code flow with PKCE.
- Refresh token lets a client obtain new access tokens without
user context. Agent's user account flow: Agentsrepeating the original authorization. It continues an existing delegated session; it isn't a separate operatingon their own behalf using user principals created specifically for agents.model.
Related content
- Request consent for delegated permissions
- admin-focused guidance on consent, manual authorization, and other authorization systems. - Agent identity token claims
- claims reference for tokens issued to agents. - OAuth 2.0 and OpenID Connect protocols on the Microsoft identity platform
@@ -1,70 +1,130 @@ ----title: Authentication protocols in agents-description: Learn about OAuth 2.0 protocols and token exchange patterns for agents in Microsoft Entra ID.+title: Choose an authentication protocol for an agent+description: Choose an OAuth protocol for a local, hosted, delegated, or autonomous agent in Microsoft Entra Agent ID. titleSuffix: Microsoft Entra Agent ID ms.topic: concept-article-ms.date: 11/04/2025+ms.date: 11/03/2026 ms.reviewer: jmprieur- -#customer-intent: As a developer or identity architect, I want to understand the OAuth 2.0 authentication protocols and token flows for agents, so that I can implement secure authentication patterns for Agent identity blueprints and Agent Identities in my applications.+ai-usage: ai-assisted++#customer-intent: As a developer or identity architect, I want to choose the right authentication protocol for my agent's hosting model and access requirements. ---- -# Authentication protocols in agents- -Agents use OAuth 2.0 protocols with specialized token exchange patterns enabled by Federated Identity Credentials (FIC). All agent auth flows involve multi-stage token exchanges where the agent identity blueprint impersonates the agent identity to perform operations. This article explains the authentication protocols and token flows used by agents. It covers delegation scenarios, autonomous operations, and federated identity credential patterns. Microsoft recommends that you use our SDKs like [Microsoft Entra ID Auth SDK (sidecar)](https://aka.ms/entra/sdk/agentid) since implementing these protocol steps isn't easy.- -All agent entities are confidential clients that can also serve as APIs for On-Behalf-Of scenarios. Interactive flows aren't supported for any agent entity type, ensuring that all authentication occurs through programmatic token exchanges rather than user interaction flows.- ++# Choose an authentication protocol for an agent++The right authentication protocol depends on where the agent runs and whose identity it uses to access a resource. Start with these questions:++1. Does the agent run on a user's device or in a hosted service?+1. Does the agent act for a signed-in user, as itself, or as a dedicated agent user account?+1. If it acts for a signed-in user, does the agent initiate sign-in or receive a user access token from another application?++Use Microsoft Authentication Library (MSAL) or another supported authentication library instead of constructing protocol requests directly.+ [!INCLUDE [Use Microsoft SDKs](./includes/use-microsoft-libraries.md)]- -## Prerequisites- -If you aren't familiar already, go through the following protocol docs.- ++## Choose a protocol++| Use case | Recommended protocol | Access type | Client type |+| --- | --- | --- | --- |+| A local agent runs on an endpoint device and signs in the user | Authorization code flow with Proof Key for Code Exchange (PKCE) | Delegated | Public |+| A hosted agent receives a user access token from a client application and calls another service for that user | On-Behalf-Of (OBO) flow | Delegated | Confidential |+| A hosted agent runs without a user and accesses resources as itself | Client credentials flow; blueprint impersonation for multi-instance Agent IDs | Application | Confidential |+| An autonomous agent needs a mailbox or another resource available only to a user | Agent's user account impersonation | Delegated permissions assigned to the agent's user account | Confidential |++If more than one row applies, use a separate token acquisition path for each operating mode. For example, a hosted agent might use OBO for requests initiated by a user and app-only access for scheduled work that doesn't have user context.++The blueprint's [instance mode](agent-blueprint.md#instance-modes-preview) also affects token acquisition. A single-instance Agent ID (preview) uses the shared blueprint client ID directly for authorization code, refresh, client credentials, and OBO requests. It doesn't acquire an intermediate blueprint impersonation token. Single-instance mode isn't limited to local or public clients. For an overview and links to the consent and SDK walkthroughs, see [Authentication for a single-instance agent identity](authenticate-single-instance-agent.md). To start with a platform-specific walkthrough, see [Choose an integration path for an agent](choose-agent-integration-path.md).++## Local agent that signs in a user++Choose the authorization code flow with PKCE when the agent:++- Runs on a desktop, mobile device, or other endpoint.+- Can open a browser for interactive sign-in.+- Accesses protected services for the signed-in user.+- Can't securely store a client secret, certificate, or federated identity credential.++The local agent is a public client. It sends the user to the Microsoft identity platform `/authorize` endpoint, receives an authorization code at its registered redirect URI, and redeems the code by using a PKCE verifier. It doesn't present a client credential.++A registered public-client Agent ID must use [single-instance mode](agent-blueprint.md#instance-modes-preview). Every installation uses the same client ID; don't create an Agent ID for each device. A local agent can alternatively use a [Client ID Metadata Document (CIMD)](client-id-metadata-documents.md) URL as its client ID.++Don't use this flow for a hosted agent that receives a user access token from another application. Use OBO instead.++For implementation and protocol details, see:++- [Authenticate a local agent with Microsoft Entra ID](authenticate-local-agent.md)+- [OAuth 2.0 authorization code grant](agent-authorization-code-oauth-flow.md)+- [Microsoft identity platform and OAuth 2.0 authorization code flow](/entra/identity-platform/v2-oauth2-auth-code-flow)+- [Public client and confidential client applications](/entra/identity-platform/msal-client-applications)++## Hosted agent that acts for a signed-in user++Choose the OBO flow when:++- A client application signs in the user.+- The client calls the hosted agent or its API with a user access token.+- The agent must call a downstream API with the user's identity and delegated permissions.++The hosted agent is a confidential client. It doesn't start another interactive sign-in. Instead, it exchanges the incoming user access token for a token to the downstream resource. The incoming token must be intended for the agent's blueprint; don't relay a token issued for another resource.++For a multi-instance Agent ID, configure the required delegated permissions as inheritable permissions on the blueprint and obtain administrator consent.++Don't use OBO when no signed-in user initiated the operation. Use app-only access for autonomous work.++For implementation and protocol details, see:++- [Agent OAuth flows: On behalf of flow](agent-on-behalf-of-oauth-flow.md) - [Microsoft identity platform and OAuth 2.0 On-Behalf-Of flow](/entra/identity-platform/v2-oauth2-on-behalf-of-flow)-- [Microsoft identity platform and the OAuth 2.0 client credentials flow](/entra/identity-platform/v2-oauth2-client-creds-grant-flow)- -## Supported grant types- -The following are the supported grant types for agent applications.- -### Agent identity blueprint- -Agent identity blueprints support `client_credentials` enabling secure token acquisition for impersonation scenarios. The `jwt-bearer` grant type facilitates token exchanges in [On-Behalf Of scenarios](/entra/identity-platform/v2-oauth2-on-behalf-of-flow), allowing for delegation patterns. `refresh_token` grants enable background operations with user context, supporting long-running processes that maintain user authorization.- -### Agent identity- -Agent identities use `client_credentials` for app-only autonomous operations, enabling independent functionality without user context, and impersonation for a user agent identity. The `jwt-bearer` grant type supports both [client credential flow](/entra/identity-platform/v2-oauth2-client-creds-grant-flow) and [On-Behalf Of (OBO) flow](/entra/identity-platform/v2-oauth2-on-behalf-of-flow) providing flexibility in delegation patterns.`refresh_token` grants facilitate background user-delegated operations, allowing agent identities to maintain user context across extended operations.- -### Unsupported flows--- The agent application model explicitly excludes certain authentication patterns to maintain security boundaries. Agents aren't supported for interactive (`/authorize`) flows, ensuring all authentication occurs programmatically.-- Public client capabilities aren't available, requiring all agents to operate as confidential clients.-- A web redirect URI can be configured on a blueprint for consent flows only (`response_type=none`), but can't be used for interactive token acquisition. Full redirect URI functionality is configured on the client application.--## Core protocol patterns- -Agents can operate in three primary modes:- -- Agents operating on behalf of regular users in Microsoft Entra ID (interactive agents). This is a regular on-behalf-of flow.-- Agents operating on their own behalf using service principals created for agents (autonomous).-- Agents operating on their own behalf using user principals created specifically for that agent (for instance agents having their own mailbox).+- [Configure inheritable permissions for agent identity blueprints](configure-inheritable-permissions-blueprints.md)++## Hosted agent that acts as itself++Choose the client credentials flow with Agent ID impersonation when the agent:++- Runs in a hosted service that can protect a credential.+- Performs scheduled, event-driven, or other autonomous work.+- Accesses a resource as the Agent ID rather than as a user.++For a multi-instance Agent ID, the blueprint first authenticates and obtains a token-exchange token for its child Agent ID. The Agent ID then uses that token as a client assertion in the client credentials flow. A single-instance Agent ID instead authenticates directly with the shared client ID and a credential on the blueprint. The resource token contains application permissions granted by an administrator and identifies the Agent ID as the actor.++Use a managed identity and federated identity credential when the hosting environment supports them. Avoid client secrets. [!INCLUDE [Managed identities support](./includes/managed-identities-preferred.md)] [!INCLUDE [Dont use secrets](./includes/do-not-use-secrets.md)]- -## Oauth protocols- -There are three agent oauth flows:- -:::image type="content" source="media/agent-oauth-protocols/agent-flows.png" alt-text="Diagram showing the illustration of oauth flow for agents." lightbox="media/agent-oauth-protocols/agent-flows.png":::- -- [Agent on-behalf of flow](./agent-on-behalf-of-oauth-flow.md): Agents operating on behalf of regular users (interactive agents).-- [Autonomous app flow](./agent-autonomous-app-oauth-flow.md): App-only operations enable agent identities to act autonomously without user context.-- [Agent's user account flow](./agent-user-oauth-flow.md): Agents operating on their own behalf using user principals created specifically for agents.++Don't use application permissions when the resource should apply a signed-in user's permissions or consent. Use authorization code with PKCE or OBO instead.++For implementation and protocol details, see:++- [Agent autonomous app OAuth flow](agent-autonomous-app-oauth-flow.md)+- [Microsoft identity platform and the OAuth 2.0 client credentials flow](/entra/identity-platform/v2-oauth2-client-creds-grant-flow)+- [Workload identity federation](/entra/workload-id/workload-identity-federation)++## Autonomous agent that acts as a dedicated user++Choose agent's user account impersonation only when an autonomous agent needs capabilities that are available to a user but not to an application identity. For example, an agent might need its own mailbox.++An [agent's user account](agent-users.md) is a dedicated user identity for the agent, not the account of the person using the agent. The Agent ID impersonates this account through an agent-specific token exchange. Access is limited by the permissions assigned to the Agent ID and the agent's user account.++Don't create an agent's user account only to run unattended work. If the resource supports application permissions, prefer app-only access so the workload doesn't depend on a user identity.++For implementation details, see:++- [Agent's user account impersonation protocol](agent-user-oauth-flow.md)+- [Agent's user accounts](agent-users.md)++## Related authentication concepts++The following settings affect authentication but don't replace the protocol choice:++- **Public or confidential client** describes whether the agent can securely hold a credential. For more information, see [Public client and confidential client applications](/entra/identity-platform/msal-client-applications).+- **Managed identity, certificate, secret, or federated identity credential** describes how a confidential client proves its identity. Prefer managed identities and federated identity credentials when possible.+- **CIMD or registered client ID** describes how a public client is identified. Both options can use authorization code flow with PKCE.+- **Refresh token** lets a client obtain new access tokens without repeating the original authorization. It continues an existing delegated session; it isn't a separate operating model. ## Related content -- [Grant agents access to Microsoft 365 resources](grant-agent-access-microsoft-365.md) - admin-focused guidance on consent, manual authorization, and other authorization systems.-- [Agent identity token claims](agent-token-claims.md) - claims reference for tokens issued to agents.+- [Request consent for delegated permissions](grant-agent-access-microsoft-365.md)+- [Agent identity token claims](agent-token-claims.md)+- [OAuth 2.0 and OpenID Connect protocols on the Microsoft identity platform](/entra/identity-platform/v2-protocols) 