Authentication with Microsoft Entra ID Auth SDK sidecar
In brief
The page now explains when to use the sidecar, its authentication responsibilities, supported token flows, and communication through localhost in a shared network namespace. ASP.NET Core agents are directed to Microsoft.Identity.Web guidance.
What Entra admins need to know
Review the updated deployment guidance, especially the instruction not to expose the sidecar endpoint publicly.
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 with Microsoft Entra ID Auth SDK (sidecar)sidecar
The Microsoft Entra ID Auth SDK (sidecar) handles authentication and token operations for your AI agent. It runs as a second container next to your agent that handles client-credentials exchange, on-behalf-of flows, and token lifecycle management. This article explainsUse the Microsoft Entra ID Auth SDK (sidecar) design pattern, how it works,sidecar when your cloud agent isn't built with ASP.NET Core and Microsoft.Identity.Web. The sidecar runs next to the identity objects involved. agent, holds the blueprint credential, acquires and caches tokens, and returns authorization headers or calls downstream APIs.
The agent communicates with the sidecar through localhost in a shared network namespace. Don't expose the sidecar endpoint publicly.
Why useChoose this integration
Use the Microsoft Entra ID Auth SDK (sidecar)?
AI agents need credentials to call downstream APIs, butsidecar when the common approaches to agent authentication fall short:needs to:
Hard-coded secrets in agent code:Every agent image holds a copy of your app'sclient_secret. Any compromise, log leak, or forgotten.envfile committed to Git exposes the full tenant.Call an API as its Agent ID.Delegated user tokens for everything:The agent can only act when a human is present. You also lose individual auditability because every call looks like the same service principal.
Microsoft Entra Agent ID gives each agent its own identity. The sidecar pattern makes that identity easy to use by keeping all credential handling outside your agent code.
How the Microsoft Entra ID Auth SDK (sidecar) works
The Microsoft Entra ID Auth SDK (sidecar) runsCall an API as a container that exposes HTTP endpoints on the pod-local network. It handles the following responsibilities:
Exchanges client credentials withlogin.microsoftonline.com.Acquires tokens through client credentials or federated identity credentials (FIC) for the agent identity in autonomous flows.Handles on-behalf-of (OBO) flows for user-context calls.Caches tokens and manages refresh and expiry.Abstracts the credential source - usesClientSecretfor development andSignedAssertionFromManagedIdentityfor Azure deployments through the same API.
The following table summarizes the flow of auth actions between your agent and the sidecar:
|
The security boundary is explicit: the sidecar has no host port. Only services inside the same network, such as your agent container, can request tokens.
Identity objects in the sidecar pattern
The following table describes the Microsoft Entra objects in the sidecar pattern:
For more information about blueprints and agent identities, see Agent identity blueprints and Agent identities.
Credential source abstraction
The sidecar abstracts the credential source from your agent code. During development, you can use a ClientSecret for convenience. In production Azure deployments, you can switch to SignedAssertionFromManagedIdentity, a federated identity credential backed by managed identity, without changing your agent code.
The sidecar's configuration determines which credential source to use. Your agent continues to call the same /AuthorizationHeader endpoint regardless of the authentication mechanism.
Sidecar sample scenarios
The Microsoft Entra Agent ID sidecar samples demonstrate the following concepts:
How a blueprint differs from an agent identity and why agents need their own identity.How the sidecar exposes/AuthorizationHeader(get token) and/DownstreamApi(token + proxied call) endpoints.How the sidecar forwardsa signed-in user'sthrough On-Behalf-Of (OBO).- Validate an incoming user token and
has the Microsoft Entra ID Auth SDK (sidecar) mint an agent-on-behalf-of-user token via OBO.read its claims. How the downstream API validates agent tokens including the signature, issuer,xms_par_app_azp, and audience.How to swap fromClientSecret(development) toSignedAssertionFromManagedIdentity(Azure deployments)Change credential sources without changing agent code.
For ASP.NET Core agents, use the integrated Microsoft.Identity.Web guidance in this documentation instead.
How the sidecar works
| Component | Responsibility |
|---|---|
| Upstream client | Signs in a user and sends an access token to the agent when user context is required. |
| Agent | Applies business logic and requests an authorization header or downstream call. |
| Sidecar | Validates inbound tokens, authenticates with the configured shared client ID and blueprint credential, and caches tokens. |
| Protected API | Validates the resulting access token and authorizes the request. |
For a cloud agent, the sidecar supports two token acquisition patterns:
- App-only Agent ID: The agent requests a token without an inbound user token.
- Agent acting for a signed-in user: The agent forwards the inbound user token and the sidecar performs OBO.
If you're building a platform that hosts separate agents for teams or customers, or your scenario needs an agent's dedicated user account, follow the agent fleet tutorial.
The following diagram shows an agent and sidecar running in the same private environment. The agent requests an authorization header from the sidecar, which gets an access token from Microsoft Entra.
:::image type="content" source="media/configure-third-party-agents/sidecar-pattern-architecture.png" alt-text="Diagram that shows an agent requesting an authorization header from a sidecar, which obtains an access token from Microsoft Entra ID." lightbox="media/configure-third-party-agents/sidecar-pattern-architecture.png" border="false":::
Security boundary
Run the sidecar in the same network namespace as the agent, such as the same pod or container app. Production builds restrict callers to loopback; separate containers on a private bridge aren't sufficient. For Docker Compose, follow the shared-network configuration. Only trusted agent code should be able to call it. Use a managed identity and federated identity credential for hosted deployments. Use client secrets only for local development.
Next steps
Related content
Microsoft Entra ID Auth SDK (sidecar) documentationMicrosoft Entra ID Auth SDK sidecar source codeAcquire tokens and call downstream APIs with Microsoft Entra ID Auth SDK (sidecar)Official Agent ID sidecar samplesMicrosoft Entra Agent ID design patternsMicrosoft Entra ID Auth SDK sidecar endpoint referenceAgent identity blueprintsAutonomous agent app OAuth flowOn-behalf-of OAuth flowChoose an authentication protocol for an agent
@@ -1,85 +1,65 @@ ----title: Authentication with Microsoft Entra ID Auth SDK (sidecar)+title: Authentication with Microsoft Entra ID Auth SDK sidecar+description: Understand when and how to use the Microsoft Entra ID Auth SDK sidecar with agents built in frameworks other than ASP.NET Core. titleSuffix: Microsoft Entra Agent ID-description: Learn how Microsoft Entra ID Auth SDK (sidecar) manages credentials and tokens for AI agents so that secrets never enter agent code. ms.topic: concept-article-ms.date: 04/28/2026-ms.custom: agent-id, msecd-doc-authoring-1012+ms.date: 11/05/2026 ai-usage: ai-assisted+ms.reviewer: dastrock -#customer intent: As a developer or architect building AI agents, I want to understand how Microsoft Entra ID Auth SDK (sidecar) handles authentication so that I can keep credentials out of agent code while giving each agent its own auditable identity.-+#customer-intent: As an agent developer, I want to understand the Auth SDK sidecar so that my agent can use Microsoft Entra authentication without handling credentials or tokens directly. --- -# Authentication with Microsoft Entra ID Auth SDK (sidecar)--The [Microsoft Entra ID Auth SDK (sidecar)](https://mcr.microsoft.com/en-us/product/entra-sdk/auth-sidecar/about) handles authentication and token operations for your AI agent. It runs as a second container next to your agent that handles client-credentials exchange, on-behalf-of flows, and token lifecycle management. This article explains the Microsoft Entra ID Auth SDK (sidecar) design pattern, how it works, and the identity objects involved. --## Why use the Microsoft Entra ID Auth SDK (sidecar)?--AI agents need credentials to call downstream APIs, but the common approaches to agent authentication fall short:--- **Hard-coded secrets in agent code:** Every agent image holds a copy of your app's `client_secret`. Any compromise, log leak, or forgotten `.env` file committed to Git exposes the full tenant.-- **Delegated user tokens for everything:** The agent can only act when a human is present. You also lose individual auditability because every call looks like the same service principal.+# Authentication with Microsoft Entra ID Auth SDK sidecar -Microsoft Entra Agent ID gives each agent its own identity. The sidecar pattern makes that identity easy to use by keeping all credential handling outside your agent code.+Use the Microsoft Entra ID Auth SDK sidecar when your cloud agent isn't built with ASP.NET Core and Microsoft.Identity.Web. The sidecar runs next to the agent, holds the blueprint credential, acquires and caches tokens, and returns authorization headers or calls downstream APIs. -## How the Microsoft Entra ID Auth SDK (sidecar) works+The agent communicates with the sidecar through `localhost` in a shared network namespace. Don't expose the sidecar endpoint publicly. -The [Microsoft Entra ID Auth SDK (sidecar)](https://mcr.microsoft.com/en-us/product/entra-sdk/auth-sidecar/about) runs as a container that exposes HTTP endpoints on the pod-local network. It handles the following responsibilities:+## Choose this integration -- Exchanges client credentials with `login.microsoftonline.com`.-- Acquires tokens through client credentials or federated identity credentials (FIC) for the agent identity in autonomous flows.-- Handles on-behalf-of (OBO) flows for user-context calls.-- Caches tokens and manages refresh and expiry.-- Abstracts the credential source - uses `ClientSecret` for development and `SignedAssertionFromManagedIdentity` for Azure deployments through the same API.+Use the sidecar when the agent needs to: -The following table summarizes the flow of auth actions between your agent and the sidecar:+- Call an API as its Agent ID.+- Call an API as a signed-in user through On-Behalf-Of (OBO).+- Validate an incoming user token and read its claims.+- Change credential sources without changing agent code. -| Agent (your code) | Microsoft Entra ID Auth SDK (sidecar) |-|---|---|-| Decide when to call the API | Acquire and cache the right token |-| Build the HTTP request | Perform client-credentials and OBO exchange |-| Pass through user token for OBO | Validate and forward user assertion |-| Handle business logic | Communicate with `login.microsoftonline.com` |+For ASP.NET Core agents, use the integrated Microsoft.Identity.Web guidance in this documentation instead. -The security boundary is explicit: the sidecar has no host port. Only services inside the same network, such as your agent container, can request tokens.+## How the sidecar works -## Identity objects in the sidecar pattern+| Component | Responsibility |+| --- | --- |+| Upstream client | Signs in a user and sends an access token to the agent when user context is required. |+| Agent | Applies business logic and requests an authorization header or downstream call. |+| Sidecar | Validates inbound tokens, authenticates with the configured shared client ID and blueprint credential, and caches tokens. |+| Protected API | Validates the resulting access token and authorizes the request. | -The following table describes the Microsoft Entra objects in the sidecar pattern:+For a cloud agent, the sidecar supports two token acquisition patterns: -| Object | Role | Location |-|---|---|---|-| **Blueprint application** | Template that creates and issues agent identities. Holds the client credential (secret or federated). | Your Microsoft Entra tenant |-| **Agent identity** | The individual AI agent. Has a unique app ID, permission grants, and audit trail. | Your Microsoft Entra tenant |-| **Client single-page application (SPA)** (OBO only) | Web UI that signs the user in and exchanges the user's token for an agent token on their behalf. | Your Microsoft Entra tenant |-| **Sidecar container** | Runs client-credentials and OBO flows. Holds the blueprint credential. | Next to your agent |-| **Agent container** | Your application code. Requests authorization headers from the sidecar. | Your pod, compose service, or App Service |+- **App-only Agent ID:** The agent requests a token without an inbound user token.+- **Agent acting for a signed-in user:** The agent forwards the inbound user token and the sidecar performs OBO. -For more information about blueprints and agent identities, see [Agent identity blueprints](agent-blueprint.md) and [Agent identities](what-are-agent-identities.md).+If you're building a platform that hosts separate agents for teams or customers, or your scenario needs an agent's dedicated user account, follow the [agent fleet tutorial](sidecar-fleet-provision-agent-identities.md). -## Credential source abstraction+The following diagram shows an agent and sidecar running in the same private environment. The agent requests an authorization header from the sidecar, which gets an access token from Microsoft Entra. -The sidecar abstracts the credential source from your agent code. During development, you can use a `ClientSecret` for convenience. In production Azure deployments, you can switch to `SignedAssertionFromManagedIdentity`, a federated identity credential backed by managed identity, without changing your agent code.+:::image type="content" source="media/configure-third-party-agents/sidecar-pattern-architecture.png" alt-text="Diagram that shows an agent requesting an authorization header from a sidecar, which obtains an access token from Microsoft Entra ID." lightbox="media/configure-third-party-agents/sidecar-pattern-architecture.png" border="false"::: -The sidecar's configuration determines which credential source to use. Your agent continues to call the same `/AuthorizationHeader` endpoint regardless of the authentication mechanism.+## Security boundary -## Sidecar sample scenarios+Run the sidecar in the same network namespace as the agent, such as the same pod or container app. Production builds restrict callers to loopback; separate containers on a private bridge aren't sufficient. For Docker Compose, follow the [shared-network configuration](microsoft-entra-sdk-for-agent-identities.md#add-the-sidecar-container). Only trusted agent code should be able to call it. Use a managed identity and federated identity credential for hosted deployments. Use client secrets only for local development. -The [Microsoft Entra Agent ID sidecar samples](https://github.com/microsoft/entra-agentid-samples/tree/dev/sidecar) demonstrate the following concepts:+## Next steps -- How a blueprint differs from an agent identity and why agents need their own identity.-- How the sidecar exposes `/AuthorizationHeader` (get token) and `/DownstreamApi` (token + proxied call) endpoints.-- How the sidecar forwards a signed-in user's token and has the Microsoft Entra ID Auth SDK (sidecar) mint an agent-on-behalf-of-user token via OBO.-- How the downstream API validates agent tokens including the signature, issuer, `xms_par_app_azp`, and audience.-- How to swap from `ClientSecret` (development) to `SignedAssertionFromManagedIdentity` (Azure deployments) without changing agent code.+1. [Configure the Auth SDK sidecar](microsoft-entra-sdk-for-agent-identities.md).+1. [Run the sidecar locally](sidecar-local-development.md).+1. [Call a custom API as the agent](sidecar-call-custom-api-as-agent.md). ## Related content -- [Microsoft Entra ID Auth SDK (sidecar) documentation](/entra/msidweb/agent-id-sdk/overview)-- [Acquire tokens and call downstream APIs with Microsoft Entra ID Auth SDK (sidecar)](microsoft-entra-sdk-for-agent-identities.md)-- [Microsoft Entra Agent ID design patterns](concept-agent-id-design-patterns.md)-- [Agent identity blueprints](agent-blueprint.md)-- [Autonomous agent app OAuth flow](agent-autonomous-app-oauth-flow.md)-- [On-behalf-of OAuth flow](agent-on-behalf-of-oauth-flow.md)+- [Microsoft Entra ID Auth SDK sidecar source code](https://github.com/AzureAD/microsoft-identity-web/tree/master/src/Microsoft.Identity.Web.Sidecar)+- [Official Agent ID sidecar samples](https://github.com/microsoft/entra-agentid-samples/tree/dev/sidecar)+- [Microsoft Entra ID Auth SDK sidecar endpoint reference](/entra/msidweb/agent-id-sdk/endpoints)+- [Choose an authentication protocol for an agent](agent-oauth-protocols.md) 