references/sdk-sidecar.md
Microsoft Entra SDK for AgentID: Polyglot Agent Authentication
Containerized companion service that handles token management for AI agents over HTTP — any language, any framework.
Image: mcr.microsoft.com/entra-sdk/auth-sidecar:1.0.0-azurelinux3.0-distroless. See GitHub releases for tags.
For code patterns, deployment manifests, security hardening, and troubleshooting, see sdk-sidecar-deployment.md.
Architecture
Client App → Your Agent (Python/Node/Go/Java)
→ Microsoft Entra SDK for AgentID (localhost:5000)
→ Microsoft Entra ID
↓
Downstream APIs
The SDK runs as a companion container in the same pod or Docker network. Your agent calls it over HTTP — no SDK embedding required.
Agent Integration (3P and Custom Agents)
Third-party and custom agents authenticate using the Blueprint → BlueprintPrincipal → Agent Identity hierarchy. The SDK acquires tokens on their behalf:
GET /AuthorizationHeaderUnauthenticated/graph
?AgentIdentity={agent-app-id}
┌──────────────────┐ ┌─────────────────────────────┐
│ Agent │ ─────────▶ │ Microsoft Entra SDK for │
│ (any language) │ ◀───────── │ AgentID (:5000) │
│ │ { authorizationHeader: "Bearer eyJ..." }│
└────────┬─────────┘ └──────────────┬──────────────┘
│ Authorization: Bearer <JWT> │ OAuth 2.0
▼ ▼
┌──────────────────────┐ ┌──────────────────────────┐
│ Downstream APIs │ │ Microsoft Entra ID │
│ · Microsoft Graph │ │ · Blueprint │
│ · Custom APIs │ │ · AgentIdentity │
│ · Azure Services │ │ │
└──────────────────────┘ └──────────────────────────┘
SDK Configuration
Core Settings
env:
- name: AzureAd__Instance
value: "https://login.microsoftonline.com/"
- name: AzureAd__TenantId
value: "<your-tenant-id>"
- name: AzureAd__ClientId
value: "<blueprint-app-id>"
Client Credentials
Client secrets are for development only. Production deployments must use Federated Identity Credentials (FIC) via Workload Identity (
SignedAssertionFilePath) or Managed Identity.
# Dev ONLY — Client Secret
- name: AzureAd__ClientCredentials__0__SourceType
value: "ClientSecret"
- name: AzureAd__ClientCredentials__0__ClientSecret
value: "<secret>"
# Prod (AKS) — Federated Identity Credentials via Workload Identity (RECOMMENDED)
- name: AzureAd__ClientCredentials__0__SourceType
value: "SignedAssertionFilePath"
# Prod (VM / App Service) — Managed Identity
- name: AzureAd__ClientCredentials__0__SourceType
value: "SignedAssertionFromManagedIdentity"
- name: AzureAd__ClientCredentials__0__ManagedIdentityClientId
value: "<managed-identity-client-id>"
Downstream API
- name: DownstreamApis__Graph__BaseUrl
value: "https://graph.microsoft.com/v1.0/"
- name: DownstreamApis__Graph__Scopes__0
value: "https://graph.microsoft.com/.default"
- name: DownstreamApis__Graph__RequestAppToken
value: "true"
Agent Identity Query Parameters
| Parameter | Purpose | Example |
|-----------|---------|---------|
| AgentIdentity | Agent app (client) ID — autonomous mode | ?AgentIdentity=<agent-client-id> |
| AgentIdentity + AgentUsername | Interactive mode by UPN | ?AgentIdentity=<id>&[email protected] |
| AgentIdentity + AgentUserId | Interactive mode by Object ID | ?AgentIdentity=<id>&AgentUserId=<oid> |
Rules:
AgentUsername/AgentUserIdrequireAgentIdentityAgentUsernameandAgentUserIdare mutually exclusiveAgentIdentityalone = autonomous agentAgentIdentity+ inbound bearer = interactive (OBO) agent
Endpoint Reference
| Endpoint | Method | Auth Required | Purpose |
|----------|--------|---------------|---------|
| /Validate | GET | Yes | Validate inbound bearer, return claims |
| /AuthorizationHeader/{name} | GET | Yes | Validate inbound token + acquire downstream token (OBO) |
| /AuthorizationHeaderUnauthenticated/{name} | GET | No | Acquire app/agent token without inbound user token |
| /DownstreamApi/{name} | ANY | Yes | Validate + call downstream API with auto token |
| /DownstreamApiUnauthenticated/{name} | ANY | No | Call downstream API with app/agent token |
| /healthz | GET | No | Health probe |
External Links
| Resource | URL | |----------|-----| | SDK Overview | https://learn.microsoft.com/en-us/entra/msidweb/agent-id-sdk/overview | | Installation | https://learn.microsoft.com/en-us/entra/msidweb/agent-id-sdk/installation | | Configuration | https://learn.microsoft.com/en-us/entra/msidweb/agent-id-sdk/configuration | | Endpoints | https://learn.microsoft.com/en-us/entra/msidweb/agent-id-sdk/endpoints | | Agent Identities | https://learn.microsoft.com/en-us/entra/msidweb/agent-id-sdk/agent-identities | | Security | https://learn.microsoft.com/en-us/entra/msidweb/agent-id-sdk/security | | OpenAPI Spec | https://github.com/AzureAD/microsoft-identity-web/blob/master/src/Microsoft.Identity.Web.Sidecar/OpenAPI/Microsoft.Identity.Web.AgentID.json |