Microsoft Entra ID
Developer

Run the Microsoft Entra ID Auth SDK sidecar locally

In brief

The article now focuses on the official sample, updated prerequisites, tenant setup, development credentials, and local-versus-hosted credential guidance. Detailed platform requirements, flow tables, and container architecture were removed.

What Entra admins need to know

Developer onboarding should account for tenant enablement, administrator approvals, recorded identity IDs, and a blueprint development credential. Local client secrets should not be used for hosted deployments.

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.

Run the Auth SDK sidecar for local development

This article shows howUse the official sidecar sample to runtest Agent ID authentication without placing Microsoft Entra credentials in the Microsoft Entra ID Auth SDK (sidecar) in your local environment by using Docker Compose. You start a four-container stack - chatagent process. The sample includes an agent, the Auth SDK sidecar, downstream weather API, and a local large language model (LLM) such as (Ollama). Then you send a query through the chat UI and observe the full token flow from agent toprotected weather API. Before you begin, review the Prerequisites for required tools,

Prerequisites

  • Docker Desktop or another Docker Compose environment.
  • A Microsoft Entra tenant.
  • Completion of Create an identity for your agent, including tenant objects,enablement, administrator approvals, and the recorded client and object IDs.
  • A development credential on the blueprint.

Use a client secret only for local testing. Use managed identity federation for hosted deployments.

Get the sample

Clone the Microsoft Entra Agent ID samples repository and open the sidecar/dev directory.

Use the sample's container layout with the cloud-agent sidecar configuration. Set the client ID recorded during setup and the blueprint credential, and keep identity overrides disabled. Don't use sample flows with AgentIdentity or AgentUserId overrides. Don't commit the environment setup.file or client secret.

Start the sample

Start the containers by following the sidecar/dev sample instructions.

The sample demonstrates two execution modes and two identity flows:

Autonomous (app-only)OBO (on behalf of user)
Direct (no LLM)Agent fetches a token and calls the weather API directly.Same, butagent must call the sidecar exchangesthrough localhost in a shared network namespace. Use the signed-in user's token.
Ollama + LangChainLangGraph ReAct agent decides when to call theDocker Compose configuration, not separate containers communicating through a get_weathersidecar tool.Same, but the agent passes the user token through.

Prerequisites

This sample works on macOS, Linux, and Windows 10/11.

RequirementmacOSLinuxWindows
DockerDocker DesktopDocker Engine + Compose v2Docker Desktop (WSL 2 backend recommended)
PowerShell 7+brew install --cask powershellInstall PowerShell on LinuxBuilt-in (or install PowerShell 7+)
Azure CLIbrew install azure-cliInstall the Azure CLIwinget install -e Microsoft.AzureCLI

You also need a Microsoft Entra tenant with these objects:

  • An agent identity blueprint with a client secret. Record the values for BLUEPRINT_APP_ID and BLUEPRINT_CLIENT_SECRET.
  • An agent identity created from that blueprint. Record the AGENT_CLIENT_ID.
  • (OBO flow only) A SPA app registration. Record the CLIENT_SPA_APP_ID.

To create these objects, follow the PowerShell workflow in the Microsoft Entra Agent ID samples repository. The workflow creates the blueprint app, the agent identity, and optionally the SPA app for OBO sign-in.

Ollama is not a prerequisite on your host - it runs inside the compose stack and pulls qwen2.5:1.5b automatically.

Clone the sample repository

Run the following commands to download the sample project and change intoDNS name. Don't expose the sidecar directory, which contains the Docker Compose configuration and agent source code for this walkthrough:port publicly.

git clone https://github.com/microsoft/entra-agentid-samples.git
cd entra-agentid-samples/sidecar/dev

Sidecar local development architecture

The stack runs four containers on an internal Docker network: llm-agent-dev (Flask chat UI, exposed on port 3003), agent-id-sidecar-dev (the Microsoft Entra ID Auth SDK sidecar), weather-api-dev (downstream API that validates agent tokens), and ollama-dev (local LLM). Only the chat UI is exposed to your host;Before testing, verify the sidecar and weather API are reachable only from withinwith the Docker network.

:::image type="content" source="media/sidecar-local-development/sidecar-request-flow.png" alt-text="Diagram showinghealth check. It confirms the sidecar architecture: Microsoft Entra ID issues a TR token to the sidecar, the agent asks the sidecar for an authorization header, then calls the weatheris accepting requests, not that credentials, consent, or API with Bearer TR, which validates the token and returns data." lightbox="media/sidecar-local-development/sidecar-request-flow.png":::

All four containers run on a shared Docker bridge network (agent-network-dev). Only the chat UI (port 3003) is exposed to your host. The sidecar and weather API have no host port, which keeps the token endpoint inside a trust boundary.

The request path works like this:

  1. You open http://localhost:3003 in your browser and send a query.
  2. The agent (llm-agent-dev) receives the query and decides to call the get_weather tool.
  3. The tool asks the sidecar for an authorization header at GET /AuthorizationHeader...?AgentIdentity={agentId}.
  4. The sidecar (agent-id-sidecar-dev) performs an OAuth 2.0 exchange with Microsoft Entra ID and receives a token (TR).
  5. The sidecar returns the Authorization: Bearer TR header to the agent.
  6. The agent calls the weather API (weather-api-dev) with that header.
  7. The weather API validates TR (JSON Web Key Set (JWKS), RS256 signature algorithm, issuer, expiry, audience) and returns weather data.

The agent never contacts Microsoft Entra ID directly and never sees a credential. It asks the sidecar for an Authorization header, receives a Bearer token, and passes that token to the weather API. Only the sidecar communicates with login.microsoftonline.com.access are configured correctly.

Understand the token flow

The autonomous flowFor app-only calls, the sidecar uses two tokens: T1 (blueprint app token from client credentials)the configured Agent ID and TR (agentAPI profile to acquire a token for the downstream API). The OBO flow adds a third: Tc (userresource. For delegated calls, the agent sends the signed-in user's access token from MSAL.js browser sign-in). The sidecar handles allto the sidecar, which exchanges it for a downstream token acquisition and caching so your agent code never manages credentials directly.

Understand the autonomous token flow

No user sign-in is required. The agent authenticates as itself by using the blueprint's client credentials.

:::image type="content" source="media/sidecar-local-development/autonomous-flow-sequence.png" alt-text="Diagram that shows the autonomous flow sequence from agent to sidecar to Microsoft Entra ID to weather API." lightbox="media/sidecar-local-development/autonomous-flow-sequence.png":::

  1. The user sends a query through the chat UI.
  2. OAuth on-behalf-of flow. The agent (or LangGraph ReAct agent) decides to call the get_weather tool.
  3. The tool requestscan request an authorization header fromor have the sidecar at GET /AuthorizationHeaderUnauthenticated/graph-app?AgentIdentity={agentAppId}.
  4. proxy the downstream API call.

    Test API access

    Test these operations separately:

    • The sidecar performs a client credentials exchange with Microsoft Entra ID and receives TR (app-only, idtyp=app).
    • The tool calls the weather API with Authorization: Bearer TR.
    • The weather API validates TR (signature, issuer, expiry, audience) and returns weather data.

Understand the on-behalf-of (OBO) token flow

App-only:The agent acts on behalf ofcalls AuthorizationHeaderUnauthenticated for a signed-in user. The sidecar performs a three-step token exchange.

:::image type="content" source="media/sidecar-local-development/on-behalf-of-flow-sequence.png" alt-text="Diagram that shows the on-behalf-of flow sequence from browser sign-in through sidecar token exchange to weather API." lightbox="media/sidecar-local-development/on-behalf-of-flow-sequence.png":::

  1. The user signs in through MSAL.js in the browser and receives Tc (user access token, audience = api://{BlueprintAppId}).
  2. The user sends a query. The agent receives Tc with the request.
  3. The tool requestsnamed API without an authorization header from the sidecar at GET /AuthorizationHeader/graph, passing Authorization: Bearer Tc and ?AgentIdentity={agentAppId}.
  4. The sidecar validates Tc, performs a client credentials exchange to get T1, then performs an OBO exchange to get TR (delegated, idtyp=user). The OBO exchange uses assertion=Tc, client_assertion=T1, and grant_type=jwt-bearer.
  5. The tool calls the weather API with Authorization: Bearer TR.
  6. The weather API validates TR and returns weather data. TR acts on behalf of the signed-in user.

Configure environment variables

Copy the example environment file and add your Microsoft Entra values:

Bash

Create a local environment file from the sample template so you can fill in your tenant and app registration values:

cp .env.example .env

PowerShell

Copy the example environment file to .env so you can populate it with your tenant and app registration values:

Copy-Item .env.example .env

Open .env in your editor and set the following values:

VariableDescription
TENANT_IDYour Microsoft Entra tenant ID.
BLUEPRINT_APP_IDThe blueprint app registration client ID. The sidecar authenticates as this app.
BLUEPRINT_CLIENT_SECRETThe blueprint client secret. Used for local development only.
AGENT_CLIENT_IDYour agent identity client ID. Passed as the AgentIdentity query parameterparameter.
  • User-delegated: The sample client signs in a user and passes the access token to the sidecar.
  • CLIENT_SPA_APP_IDagent. The SPA app registration client ID. Required agent forwards it to the authenticated sidecar endpoint for OBO.
  • Token validation: The protected API validates the access token's signature, issuer, audience, expiry, and Agent ID claims.
  • Verify that app-only fortokens have application permissions and delegated tokens contain the OBO flow.

    OLLAMA_MODELThe Ollama modelexpected user and scope claims.

    Move to use. Defaults to qwen2.5:1.5b.

    a hosted environment

    The autonomous flow requires TENANT_ID, BLUEPRINT_APP_ID, BLUEPRINT_CLIENT_SECRET, and AGENT_CLIENT_ID. The OBO flow also requires CLIENT_SPA_APP_ID.

    This sidecar sample uses ClientSecret as the credential source type. The sidecar supports the following credential types through the AzureAd__ClientCredentials__0__SourceType setting in docker-compose.yml:Before deployment:

    • ClientSecret: LocalReplace the development only. This type issecret with a managed identity federated credential.
    • Keep sidecar traffic on loopback in the default for this sample.shared network namespace.
    • SignedAssertionFromManagedIdentity: Deployed on Azure. Zero secrets, recommended for production.Configure production redirect URIs and API audiences.
    • KeyVault: Certificate from Azure Key Vault.
    • StoreWithThumbprint: Certificate from local machine store.Remove development-only ports and sample credentials.

    Set up OBO sign-in (optional)Next step

    To test the on-behalf-of flow, create the SPA app and configure OBO consent. Run one of the following script pairs from the repository root:Call a custom API as the agent.

    Bash

    # Create the SPA app registration for MSAL.js browser sign-in
    bash ../../scripts/setup-obo-client-app.sh
    # → prints CLIENT_SPA_APP_ID
    
    # Wire up the OBO scope + admin consent on the Blueprint
    bash ../../scripts/setup-obo-blueprint.sh
    

    PowerShell

    # Create the SPA app registration for MSAL.js browser sign-in
    pwsh ../../scripts/setup-obo-client-app.ps1
    # → prints CLIENT_SPA_APP_ID (and writes it to .env)
    
    # Wire up the OBO scope + admin consent on the Blueprint
    pwsh ../../scripts/setup-obo-blueprint.ps1 `
        -TenantId        '<TENANT_ID>' `
        -BlueprintAppId  '<BLUEPRINT_APP_ID>' `
        -AgentAppId      '<AGENT_CLIENT_ID>' `
        -ClientSpaAppId  '<CLIENT_SPA_APP_ID>'
    

    Add the CLIENT_SPA_APP_ID value to your .env file after running the scripts.

    Start the stack

    Build the container images and start all four services in detached mode by running the following command:

    docker compose up --build -d
    

    The first run takes about 30 seconds while Ollama pulls the qwen2.5:1.5b model. To verify that the local sample stack is running and that components such as the sidecar and Ollama are ready, query the status endpoint:

    Bash

    curl http://localhost:3003/api/status
    

    PowerShell

    Query the sample app's status endpoint to confirm that the local environment is healthy and all services are running:

    Invoke-RestMethod http://localhost:3003/api/status
    

    The response shows ollama_available: true when the stack is ready.

    Send a query through the chat UI

    Perform the following steps to send a test query through the chat UI and observe the token flow:

    1. Open http://localhost:3003 in your browser.

    2. In the header bar, verify that your Tenant ID and Agent ID appear.

    3. Use the two toggles to select your demo configuration:

      • Execution Mode: Select Direct to skip the LLM and call the weather API directly, or select Ollama to use a LangChain ReAct agent.
      • Identity Flow: Select Autonomous for an app-only token, or OBO to act on behalf of a signed-in user. For OBO, choose Sign in to authenticate through an MSAL.js popup.
    4. Send the prepopulated query "Weather in Dallas?" and review the result.

    5. In the right panel, expand Identity Trace to inspect each step of the token flow:

      • The token request to the sidecar, including the AgentIdentity parameter.
      • Decoded JWT claims for each token (Tc, T1, TR for OBO; T1 and TR for autonomous).
      • Downstream API validation results, including signature (JWKS, RS256), issuer, expiry, and audience checks.

    Troubleshoot common issues

    SymptomLikely causeFix
    /api/status returns ollama_available: falseModel is still downloading.Wait about 30 seconds. Check logs by using docker logs ollama-dev.
    Weather API returns 401 UnauthorizedToken tenant mismatch, expired secret, or signature check failed.Verify TENANT_ID matches the blueprint's tenant. Check sidecar logs by using docker logs agent-id-sidecar-dev.
    LLM returns weather without calling the toolThe qwen2.5:1.5b model is too small for reliable tool calling.Change OLLAMA_MODEL to qwen2.5:7b or llama3.1:8b in your .env file.
    OBO sign-in popup is blockedBrowser popup blocker is active.Allow popups for localhost:3003.
    4xx error from sidecar during OBOCLIENT_SPA_APP_ID is missing or the SPA redirect URI doesn't match.Rerun the OBO setup scripts. Verify http://localhost:3003 is listed in the SPA's redirect URIs.

    To diagnose startup, authentication, or downstream API issues, display the logs from each container by running the following commands:

    docker logs llm-agent-dev
    docker logs agent-id-sidecar-dev
    docker logs weather-api-dev
    

    Clean up resources

    Stop the containers when you're done. Choose the cleanup level that fits your needs. The first command stops the demo containers while preserving volumes and images for a faster restart later:

    # Stop containers, keep volumes and images
    docker compose down
    
    # Stop containers and remove the Ollama model cache
    docker compose down -v
    
    # Remove containers, volumes, and images
    docker compose down -v --rmi all
    

    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…