Microsoft Entra ID
AuthenticationAuthentication with Microsoft Entra ID Auth SDK (sidecar)
In brief
The documentation now consistently uses “Microsoft Entra ID Auth SDK (sidecar)” and expands “SPA” to “single-page application.” The described authentication flows and responsibilities are otherwise unchanged in the supplied diff.
What Entra admins need to know
Improves clarity and searchability for administrators and architects; no administrative action is indicated.
This editorial summary was generated by AI from the documentation changes. Verify important details in the full Microsoft Learn article.
Documentation change
View on Microsoft LearnThe comparison below shows only the changed extract. Use the full-page view for complete context.
Authentication with Microsoft Entra ID Auth SDK (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 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 auth sidecar?(sidecar)?
AI agents need credentials to call downstream APIs, but the common approaches to agent authentication fall short:
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 auth sidecar(sidecar) works
The Microsoft Entra ID Auth SDK (sidecar) runs as a container that exposes HTTP endpoints on the pod-local network. It handles the following responsibilities:
- Exchanges client credentials with
login.microsoftonline.com. - Acquires tokens through client credentials or federated identity credentials (FIC) for the agent identity in autonomous flows.
The following table summarizes the flow of auth actions between your agent and the sidecar:
| Agent (your code) | |
|---|---|
| Decide when to call the API | Acquire and cache the right token |
| Build the HTTP request | Perform client-credentials and OBO exchange |
| --- | --- |
| Blueprint application | Template that creates and issues agent identities. Holds the client credential (secret or federated). |
| Agent identity | The individual AI agent. Has a unique app ID, permission grants, and audit trail. |
| Client |
Web UI that signs the user in and exchanges the user's token for an agent token on their behalf. |
| Sidecar container | Runs client-credentials and OBO flows. Holds the blueprint credential. |
| Agent container | Your application code. Requests authorization headers from the sidecar. |
- 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) toSignedAssertionFromManagedIdentity(Azure deployments) without changing agent code.
@@ -1,21 +1,21 @@ ----title: Authentication with Microsoft Entra Auth SDK (sidecar)+title: Authentication with Microsoft Entra ID Auth SDK (sidecar) titleSuffix: Microsoft Entra Agent ID-description: Learn how Microsoft Entra Auth SDK (sidecar) manages credentials and tokens for AI agents so that secrets never enter agent code.+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 ai-usage: ai-assisted -#customer intent: As a developer or architect building AI agents, I want to understand how Microsoft Entra 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 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. --- -# Authentication with Microsoft Entra Auth SDK (sidecar)+# Authentication with Microsoft Entra ID Auth SDK (sidecar) -The [Microsoft Entra 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 Auth SDK (sidecar) design pattern, how it works, and the identity objects involved. +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 SDK auth sidecar?+## 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: @@ -24,9 +24,9 @@ AI agents need credentials to call downstream APIs, but the common approaches to 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 SDK auth sidecar works+## How the Microsoft Entra ID Auth SDK (sidecar) works -The [Microsoft Entra SDK auth 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:+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: - Exchanges client credentials with `login.microsoftonline.com`. - Acquires tokens through client credentials or federated identity credentials (FIC) for the agent identity in autonomous flows.@@ -36,7 +36,7 @@ The [Microsoft Entra SDK auth sidecar](https://mcr.microsoft.com/en-us/product/e The following table summarizes the flow of auth actions between your agent and the sidecar: -| Agent (your code) | Sidecar (Microsoft Entra SDK) |+| 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 |@@ -53,7 +53,7 @@ The following table describes the Microsoft Entra objects in the sidecar pattern |---|---|---| | **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 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 |+| **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 | @@ -71,7 +71,7 @@ The [Microsoft Entra Agent ID sidecar samples](https://github.com/microsoft/entr - 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 SDK mint an agent-on-behalf-of-user token via OBO.+- 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.