Microsoft Entra ID
Authentication

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's client_secret. Any compromise, log leak, or forgotten .env file 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 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.

The following table summarizes the flow of auth actions between your agent and the sidecar:

Agent (your code)Microsoft Entra ID Auth SDK (sidecar)
Decide when to call the APIAcquire and cache the right token
Build the HTTP requestPerform client-credentials and OBO exchange
Pass through user token for OBOValidate and forward user assertion
Handle business logicCommunicate with login.microsoftonline.com

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:

ObjectRoleLocation
Blueprint applicationTemplate that creates and issues agent identities. Holds the client credential (secret or federated).Your Microsoft Entra tenant
Agent identityThe 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 containerRuns client-credentials and OBO flows. Holds the blueprint credential.Next to your agent
Agent containerYour application code. Requests authorization headers from the sidecar.Your pod, compose service, or App Service

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 forwards a signed-in user's through 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 from ClientSecret (development) to SignedAssertionFromManagedIdentity (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

ComponentResponsibility
Upstream clientSigns in a user and sends an access token to the agent when user context is required.
AgentApplies business logic and requests an authorization header or downstream call.
SidecarValidates inbound tokens, authenticates with the configured shared client ID and blueprint credential, and caches tokens.
Protected APIValidates 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

  1. Configure the Auth SDK sidecar.
  2. Run the sidecar locally.
  3. Call a custom API as the agent.

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…