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:
localhost in a shared network namespace. Use the | ||
|
Prerequisites
This sample works on macOS, Linux, and Windows 10/11.
| |||
| |
You also need a Microsoft Entra tenant with these objects:
An agent identity blueprint with a client secret. Record the values forBLUEPRINT_APP_IDandBLUEPRINT_CLIENT_SECRET.An agent identity created from that blueprint. Record theAGENT_CLIENT_ID.(OBO flow only) A SPA app registration. Record theCLIENT_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:
You openhttp://localhost:3003in your browser and send a query.The agent (llm-agent-dev) receives the query and decides to call theget_weathertool.The tool asks the sidecar for an authorization header atGET /AuthorizationHeader...?AgentIdentity={agentId}.The sidecar (agent-id-sidecar-dev) performs an OAuth 2.0 exchange with Microsoft Entra ID and receives a token (TR).The sidecar returns theAuthorization: Bearer TRheader to the agent.The agent calls the weather API (weather-api-dev) with that header.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":::
The user sends a query through the chat UI.- OAuth on-behalf-of flow. The agent
(or LangGraph ReAct agent) decides to call theget_weathertool. The tool requestscan request an authorization headerfromor have the sidecaratGET /AuthorizationHeaderUnauthenticated/graph-app?AgentIdentity={agentAppId}.proxy the downstream API call.The sidecar performs a client credentials exchange with Microsoft Entra ID and receives TR (app-only,idtyp=app).The tool calls the weather API withAuthorization: Bearer TR.The weather API validates TR (signature, issuer, expiry, audience) and returns weather data.
Test API access
Test these operations separately:
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":::
The user signs in through MSAL.js in the browser and receives Tc (user access token, audience =api://{BlueprintAppId}).The user sends a query. The agent receives Tc with the request.The tool requestsnamed API without anauthorization header from the sidecar atGET /AuthorizationHeader/graph, passingAuthorization: Bearer Tcand?AgentIdentity={agentAppId}.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 usesassertion=Tc,client_assertion=T1, andgrant_type=jwt-bearer.The tool calls the weather API withAuthorization: Bearer TR.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:
| |
| |
| |
| AgentIdentity query |
| agent. The Verify that app-only |
| Move to |
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 developmentonly. 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:
Openhttp://localhost:3003in your browser.In the header bar, verify that yourTenant IDandAgent IDappear.Use the two toggles to select your demo configuration:Execution Mode: SelectDirectto skip the LLM and call the weather API directly, or selectOllamato use a LangChain ReAct agent.Identity Flow: SelectAutonomousfor an app-only token, orOBOto act on behalf of a signed-in user. For OBO, chooseSign into authenticate through an MSAL.js popup.
Send the prepopulated query "Weather in Dallas?" and review the result.In the right panel, expandIdentity Traceto inspect each step of the token flow:The token request to the sidecar, including theAgentIdentityparameter.Decoded JWT claims for each token (Tc,T1,TRfor OBO;T1andTRfor autonomous).Downstream API validation results, including signature (JWKS, RS256), issuer, expiry, and audience checks.
Troubleshoot common issues
| | |
| | |
| | |
| ||
| | |
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
@@ -1,274 +1,71 @@ ----title: Run the Microsoft Entra ID Auth SDK (sidecar) for local development+title: Run the Microsoft Entra ID Auth SDK sidecar locally+description: Run the Auth SDK sidecar and sample agent locally before deploying them to a hosted environment. titleSuffix: Microsoft Entra Agent ID-description: Run the Microsoft Entra ID Auth SDK (sidecar) on your laptop with Docker Compose and Ollama to see autonomous and on-behalf-of agent authentication working end-to-end. ms.topic: how-to-ms.date: 06/15/2026-ms.custom: msecd-doc-authoring-1013+ms.date: 11/06/2026 ai-usage: ai-assisted+ms.reviewer: dastrock -#customer intent: As a developer building AI agents, I want to run the Microsoft Entra ID Auth SDK (sidecar) locally so that I can see agent authentication working end-to-end before deploying to production.-+#customer-intent: As an agent developer, I want to run the Auth SDK sidecar locally so that I can test app-only and user-delegated Agent ID flows. --- -# Run the sidecar for local development--This article shows how to run the [Microsoft Entra ID Auth SDK (sidecar)](https://mcr.microsoft.com/en-us/product/entra-sdk/auth-sidecar/about) in your local environment by using Docker Compose. You start a four-container stack - chat agent, sidecar, downstream weather API, and a local large language model (LLM) such as ([Ollama](https://ollama.com)). Then you send a query through the chat UI and observe the full token flow from agent to API. Before you begin, review the [Prerequisites](#prerequisites) for required tools, Microsoft Entra tenant objects, and local environment setup.--The sample demonstrates two execution modes and two identity flows:+# Run the Auth SDK sidecar for local development -| | **Autonomous** (app-only) | **OBO** (on behalf of user) |-|---|---|---|-| **Direct** (no LLM) | Agent fetches a token and calls the weather API directly. | Same, but the sidecar exchanges the signed-in user's token. |-| **Ollama + LangChain** | LangGraph ReAct agent decides when to call the `get_weather` tool. | Same, but the agent passes the user token through. |+Use the official sidecar sample to test Agent ID authentication without placing Microsoft Entra credentials in the agent process. The sample includes an agent, the Auth SDK sidecar, and a protected weather API. ## Prerequisites -This sample works on macOS, Linux, and Windows 10/11.--| Requirement | macOS | Linux | Windows |-|---|---|---|---|-| Docker | Docker Desktop | Docker Engine + Compose v2 | Docker Desktop (WSL 2 backend recommended) |-| PowerShell 7+ | `brew install --cask powershell` | [Install PowerShell on Linux](/powershell/scripting/install/installing-powershell-on-linux) | Built-in (or install PowerShell 7+) |-| Azure CLI | `brew install azure-cli` | [Install the Azure CLI](/cli/azure/install-azure-cli-linux) | `winget 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](https://github.com/microsoft/entra-agentid-samples). 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+- Docker Desktop or another Docker Compose environment.+- A Microsoft Entra tenant.+- Completion of [Create an identity for your agent](create-single-instance-agent.md), including tenant enablement, administrator approvals, and the recorded client and object IDs.+- A development credential on the blueprint. -Run the following commands to download the sample project and change into the sidecar directory, which contains the Docker Compose configuration and agent source code for this walkthrough:+Use a client secret only for local testing. Use managed identity federation for hosted deployments. -```bash-git clone https://github.com/microsoft/entra-agentid-samples.git-cd entra-agentid-samples/sidecar/dev-```+## Get the sample -<a name="architecture"></a>-## Sidecar local development architecture+Clone the [Microsoft Entra Agent ID samples](https://github.com/microsoft/entra-agentid-samples) repository and open the `sidecar/dev` directory. -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; the sidecar and weather API are reachable only from within the Docker network.+Use the sample's container layout with the [cloud-agent sidecar configuration](microsoft-entra-sdk-for-agent-identities.md). 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 file or client secret. -:::image type="content" source="media/sidecar-local-development/sidecar-request-flow.png" alt-text="Diagram showing 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 weather API with Bearer TR, which validates the token and returns data." lightbox="media/sidecar-local-development/sidecar-request-flow.png":::+## Start the sample -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.+Start the containers by following the [`sidecar/dev` sample instructions](https://github.com/microsoft/entra-agentid-samples/tree/dev/sidecar/dev). -The request path works like this:+The agent must call the sidecar through `localhost` in a shared network namespace. Use the [Docker Compose configuration](microsoft-entra-sdk-for-agent-identities.md#add-the-sidecar-container), not separate containers communicating through a `sidecar` DNS name. Don't expose the sidecar port publicly. -1. You open `http://localhost:3003` in your browser and send a query.-1. The agent (`llm-agent-dev`) receives the query and decides to call the `get_weather` tool.-1. The tool asks the sidecar for an authorization header at `GET /AuthorizationHeader...?AgentIdentity={agentId}`.-1. The sidecar (`agent-id-sidecar-dev`) performs an OAuth 2.0 exchange with Microsoft Entra ID and receives a token (TR).-1. The sidecar returns the `Authorization: Bearer TR` header to the agent.-1. The agent calls the weather API (`weather-api-dev`) with that header.-1. 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`.+Before testing, verify the sidecar with the [health check](microsoft-entra-sdk-for-agent-identities.md#verify-the-sidecar). It confirms the sidecar is accepting requests, not that credentials, consent, or API access are configured correctly. ## Understand the token flow -The autonomous flow uses two tokens: **T1** (blueprint app token from client credentials) and **TR** (agent token for the downstream API). The OBO flow adds a third: **Tc** (user access token from MSAL.js browser sign-in). The sidecar handles all token acquisition and caching so your agent code never manages credentials directly.--<a name="autonomous-flow"></a>-### 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.-1. The agent (or LangGraph ReAct agent) decides to call the `get_weather` tool.-1. The tool requests an authorization header from the sidecar at `GET /AuthorizationHeaderUnauthenticated/graph-app?AgentIdentity={agentAppId}`.-1. The sidecar performs a client credentials exchange with Microsoft Entra ID and receives TR (app-only, `idtyp=app`).-1. The tool calls the weather API with `Authorization: Bearer TR`.-1. The weather API validates TR (signature, issuer, expiry, audience) and returns weather data.--<a name="obo-flow"></a>-### Understand the on-behalf-of (OBO) token flow--The agent acts on behalf of 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}`).-1. The user sends a query. The agent receives Tc with the request.-1. The tool requests an authorization header from the sidecar at `GET /AuthorizationHeader/graph`, passing `Authorization: Bearer Tc` and `?AgentIdentity={agentAppId}`.-1. 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`.-1. The tool calls the weather API with `Authorization: Bearer TR`.-1. The weather API validates TR and returns weather data. TR acts on behalf of the signed-in user.--## Configure environment variables--> [!TIP]-> If you already have a `.env` file from a previous run with `TENANT_ID`, `BLUEPRINT_APP_ID`, `BLUEPRINT_CLIENT_SECRET`, and `AGENT_CLIENT_ID` populated, skip to [Start the stack](#start-the-stack). The Microsoft Entra objects survive container restarts and `docker compose down`.--Copy the example environment file and add your Microsoft Entra values:--### [Bash](#tab/bash)--Create a local environment file from the sample template so you can fill in your tenant and app registration values:--```bash-cp .env.example .env-```--### [PowerShell](#tab/powershell)--Copy the example environment file to `.env` so you can populate it with your tenant and app registration values:--```powershell-Copy-Item .env.example .env-```-------Open `.env` in your editor and set the following values:--| Variable | Description |-|---|---|-| `TENANT_ID` | Your Microsoft Entra tenant ID. |-| `BLUEPRINT_APP_ID` | The blueprint app registration client ID. The sidecar authenticates as this app. |-| `BLUEPRINT_CLIENT_SECRET` | The blueprint client secret. Used for local development only. |-| `AGENT_CLIENT_ID` | Your agent identity client ID. Passed as the `AgentIdentity` query parameter to the sidecar. |-| `CLIENT_SPA_APP_ID` | The SPA app registration client ID. Required only for the OBO flow. |-| `OLLAMA_MODEL` | The Ollama model to use. Defaults to `qwen2.5:1.5b`. |--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`:--- **`ClientSecret`:** Local development only. This type is the default for this sample.-- **`SignedAssertionFromManagedIdentity`:** Deployed on Azure. Zero secrets, recommended for production.-- **`KeyVault`:** Certificate from Azure Key Vault.-- **`StoreWithThumbprint`:** Certificate from local machine store.--## Set up OBO sign-in (optional)--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:--### [Bash](#tab/bash)--```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](#tab/powershell)--```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:--```bash-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](#tab/bash)--```bash-curl http://localhost:3003/api/status-```--### [PowerShell](#tab/powershell)--Query the sample app's status endpoint to confirm that the local environment is healthy and all services are running:--```powershell-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.--1. In the header bar, verify that your **Tenant ID** and **Agent ID** appear.--1. 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.--1. Send the prepopulated query "Weather in Dallas?" and review the result.--1. 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.+For app-only calls, the sidecar uses the configured Agent ID and API profile to acquire a token for the downstream resource. For delegated calls, the agent sends the signed-in user's access token to the sidecar, which exchanges it for a downstream token by using the OAuth on-behalf-of flow. The agent can request an authorization header or have the sidecar proxy the downstream API call. -## Troubleshoot common issues+## Test API access -| Symptom | Likely cause | Fix |-|---|---|---|-| `/api/status` returns `ollama_available: false` | Model is still downloading. | Wait about 30 seconds. Check logs by using `docker logs ollama-dev`. |-| Weather API returns `401 Unauthorized` | Token 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 tool | The `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 blocked | Browser popup blocker is active. | Allow popups for `localhost:3003`. |-| `4xx` error from sidecar during OBO | `CLIENT_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. |+Test these operations separately: -To diagnose startup, authentication, or downstream API issues, display the logs from each container by running the following commands:+- **App-only:** The agent calls `AuthorizationHeaderUnauthenticated` for a named API without an `AgentIdentity` query parameter.+- **User-delegated:** The sample client signs in a user and passes the access token to the agent. The 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. -```bash-docker logs llm-agent-dev-docker logs agent-id-sidecar-dev-docker logs weather-api-dev-```+Verify that app-only tokens have application permissions and delegated tokens contain the expected user and scope claims. -## Clean up resources+## Move to a hosted environment -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:+Before deployment: -```bash-# Stop containers, keep volumes and images-docker compose down+- Replace the development secret with a managed identity federated credential.+- Keep sidecar traffic on loopback in the shared network namespace.+- Configure production redirect URIs and API audiences.+- Remove development-only ports and sample credentials. -# Stop containers and remove the Ollama model cache-docker compose down -v+## Next step -# Remove containers, volumes, and images-docker compose down -v --rmi all-```+[Call a custom API as the agent](sidecar-call-custom-api-as-agent.md). ## Related content -- [Authentication with Auth SDK (sidecar)](authentication-with-auth-sdk-sidecar.md)-- [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)-- [Validate agent identity tokens in a downstream API](how-to-validate-agent-tokens-downstream-api.md)-- [Microsoft Entra Agent ID samples repository](https://github.com/microsoft/entra-agentid-samples)+- [Official sidecar samples](https://github.com/microsoft/entra-agentid-samples/tree/dev/sidecar)+- [Configure the Auth SDK sidecar](microsoft-entra-sdk-for-agent-identities.md)+- [Build a platform that hosts an agent fleet](sidecar-fleet-provision-agent-identities.md) 