Microsoft Entra ID
Developer

Configure the Microsoft Entra ID Auth SDK sidecar

In brief

The article now covers sidecar configuration, prerequisites, shared network requirements, local and Azure host credentials, managed identity settings, and Docker Compose deployment examples.

What Entra admins need to know

Administrators configuring the sidecar should use the updated prerequisites and deployment settings, including loopback access and managed identity configuration for Azure hosts.

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.

Acquire tokens and call downstream APIs withConfigure the Microsoft Entra ID Auth SDK (sidecar)sidecar

The Microsoft Entra ID Auth SDK (sidecar)sidecar is a containerized webcompanion service that handles authentication and token acquisition, validation, and downstream API callsacquisition for agents. This SDK communicates with your application through HTTP APIs, providing consistent integration patterns regardless ofagent. It lets your technology stack. Instead of embedding identity logic directly in your application code, the Microsoft Entra ID Auth SDK (sidecar) manages token acquisition, validation, and API calls through standard HTTP requests.

Prerequisites

Before you begin, ensure you have:

Deploy your containerized service

Deploy the Microsoft Entra ID Auth SDK (sidecar)call APIs as a containerized service in your environment. Follow the instructions in the Set up the Microsoft Entra ID Auth SDK (sidecar) guide to configure the service with your agent identity details.

Configure your Microsoft Entra ID Auth SDK (sidecar) settings

Follow these steps to configure your Microsoft Entra ID Auth SDK (sidecar) settings:

[!INCLUDE Dont use secrets]

  1. Set up the necessary components in Microsoft Entra ID. Ensure you register your application in the Microsoft Entra ID tenant.

  2. Configure your client credentials. This credential can be a client secret, a certificate, or a managed identity that you're using as a federated identity credential.

  3. If you're calling a downstream API, ensure that the necessary permissions are granted. Calling a custom web API requires you to provide the API registration details in the SDK configuration.

For more information, see Configure your Microsoft Entra ID Auth SDK (sidecar) settings.

Acquire tokens using the Microsoft Entra ID Auth SDK (sidecar)

These are the steps to acquire tokens using the Microsoft Entra ID Auth SDK (sidecar):

  1. Acquire token using the Microsoft Entra ID Auth SDK (sidecar). This varies based on whether the agent is operating autonomouslyitself or on behalf of signed-in users.

    In this article, you configure the sidecar container, its blueprint credential, and downstream API access.

    Prerequisites

    • Completion of Create an identity for your agent, including tenant enablement, administrator approvals, and the recorded client and object IDs.
    • A credential configured on the blueprint.
    • Permissions granted to the Agent ID for each downstream API.
    • A shared network namespace for the agent and sidecar, such as containers in the same pod.

    Add the sidecar container

    Run the agent and sidecar in the same network namespace and call the sidecar through localhost. Production sidecar builds restrict callers to loopback; a user. There are three scenarios to consider:private Docker bridge and a sidecar DNS name aren't sufficient. Containers in the same Kubernetes pod or Azure Container Apps app share this boundary. In Docker Compose, use network_mode: "service:sidecar" on the agent. Don't publish the sidecar port.

    Use the credential configuration for where you run the container:

    • Autonomous agents: Agents operatingLocal workstation: Follow Run the sidecar for local development for the sample container startup and development credential. Apply the network boundary above and the API profiles and override settings below.
    • Azure host: Use the following configuration after assigning the managed identity to the host and configuring its federated credential on their own behalf using service principals createdthe blueprint. It doesn't provide a workstation credential.

    The Docker Compose fragment illustrates the shared network layout and uses a user-assigned managed identity as the credential:

    Set AzureAd:ClientCredentials:0:SourceType to SignedAssertionFromManagedIdentity and AzureAd:ClientCredentials:0:ManagedIdentityClientId to the user-assigned managed identity's client ID. This is a different value from the shared agent client ID in AzureAd:ClientId. Container environment variables use __ in place of : in these configuration paths.

    Record the tenant, blueprint, Agent ID, and API identifiers for agents (autonomous).

  2. Autonomousyour scenario in the scenario identifier worksheet before configuring these values.

    services:
      sidecar:
        image: mcr.microsoft.com/entra-sdk/auth-sidecar:1.1.3-azurelinux3.0-distroless
        environment:
          AzureAd__Instance: https://login.microsoftonline.com/
          AzureAd__TenantId: <tenant-id>
          AzureAd__ClientId: <agent-client-id>
          AzureAd__ClientCredentials__0__SourceType: SignedAssertionFromManagedIdentity
          AzureAd__ClientCredentials__0__ManagedIdentityClientId: <managed-identity-client-id>
          ASPNETCORE_URLS: http://localhost:5000
    
      agent:
        image: <agent-image>
        network_mode: "service:sidecar"
        environment:
          SIDECAR_URL: http://localhost:5000
    

    Replace <agent-image> with your agent's user account: Agents operating on their own behalf using user principals created specificallyimage. This example pins the Linux sidecar to 1.1.3-azurelinux3.0-distroless. For Windows, use the matching Windows tag from Auth SDK sidecar container image tags.

    Use SignedAssertionFilePath instead when the container receives a workload identity token from its orchestrator. Use ClientSecret only for agents (for instance agents having their own mailbox)local development. Don't place the blueprint credential in the agent container.

    For other credential sources, see Microsoft.Identity.Web credential descriptions.

  3. Interactive agents: Agents operating on behalf of human users.
  4. Specify the

    Configure a downstream API

    Give each downstream API a short name. Configure its base URL, scopes, and token type. For example, this profile requests app-only tokens for Microsoft Graph:

    {
      "DownstreamApis": {
        "graph-app": {
          "BaseUrl": "https://graph.microsoft.com/v1.0/",
          "Scopes": [
            "https://graph.microsoft.com/.default"
          ],
          "RequestAppToken": true
        }
      }
    }
    

    The name becomes the {apiName} route value. This example uses graph-app, so the agent requests /AuthorizationHeaderUnauthenticated/graph-app.

    The resource-specific articles provide the configuration for each API. To configure the container with environment variables, replace each : in the JSON path with __. For example:

    environment:
      DownstreamApis__graph-app__BaseUrl: https://graph.microsoft.com/v1.0/
      DownstreamApis__graph-app__Scopes__0: https://graph.microsoft.com/.default
      DownstreamApis__graph-app__RequestAppToken: "true"
    

    Keep identity overrides disabled

    Use the client ID recorded during setup directly. Don't pass AgentIdentity, AgentUserId, or AgentUsername: these select a different identity flow, not the cloud-agent setup in this article.

    Keep overrides disabled on the endpoints used by includingthe agent:

    {
      "Sidecar": {
        "AllowOverrides": {
          "GetAuthorizationHeader": false,
          "GetAuthorizationHeaderUnauthenticated": false,
          "CallDownstreamApi": false,
          "CallDownstreamApiUnauthenticated": false
        }
      }
    }
    

    Keep the sidecar accessible only through the shared loopback boundary even when overrides are disabled. The unauthenticated endpoints can acquire app-only tokens with the configured credential.

    Verify the sidecar

    From the agent container in the shared network namespace, request http://localhost:5000/healthz:

    GET /healthz
    

    The endpoint reports whether the sidecar is accepting requests. It doesn't verify the credential, consent, or downstream API access. Test token acquisition and a downstream call separately. Don't expose it as a public health endpoint.

    Choose an endpoint

    OperationEndpoint
    Validate an inbound access token and return its claimsGET /Validate
    Get an authorization header using an inbound user tokenGET /AuthorizationHeader/{apiName}
    Get an authorization header without an inbound user tokenGET /AuthorizationHeaderUnauthenticated/{apiName}
    Have the sidecar call a configured downstream APIPOST /DownstreamApi/{apiName}
    Have the sidecar call a configured downstream API without an inbound user tokenPOST /DownstreamApiUnauthenticated/{apiName}

    Use the named downstream API profile without identity query parameters. For example, request /AuthorizationHeaderUnauthenticated/graph-app for app-only access or /AuthorizationHeader/graph with an inbound user token for OBO.

    The authorization-header endpoints return an authorizationHeader value. Treat it as a credential and don't log it.

    The profile name in the request URL based on your Microsoft Entra ID Auth SDK (sidecar) configuration.endpoint must match a name under DownstreamApis. The authorization header endpoint takes the formatconfiguration above defines graph-app, so /AuthorizationHeaderUnauthenticated/graph-app is valid. It doesn't define a graph profile. To use /AuthorizationHeader/{serviceName}graph wherefor OBO, configure a separate delegated serviceNamegraph isprofile as shown in Call Microsoft Graph as a user. The endpoint path selects which identity supplies the token; the profile name ofselects the downstream API configured in the SDK settings.configuration.

  5. To acquire an app-only (client credentials) token for an autonomous agent, you provide the agent identity client ID in the request.

    GET /AuthorizationHeader/Graph?AgentIdentity=<agent-identity-client-id>
    Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGc...
    
  6. To acquire token for an autonomous agent's user account, provide either the user object ID or User Principal Name but not both. This means providing either AgentUsername or AgentUserId. Providing both causes a validation error. You must also provide the AgentIdentity to specify which agent identity to use for token acquisition. If the agent identity parameter is missing, the request fails with a validation error.

    GET /AuthorizationHeader/Graph?AgentIdentity=<agent-identity-client-id>&AgentUserId=<agent-user-object-id>
    Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGc...
    
    GET /AuthorizationHeader/Graph?AgentIdentity=<agent-identity-client-id>&AgentUsername=<agent-user-principal-name>
    Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGc...
    
  7. For interactive agents, usecomplete request and response details, see the on-behalf-of (OBO) flow. The agent first validatesAuth SDK sidecar endpoint reference. An unconfigured profile name returns 400 Bad Request; correct the user token granted to it before acquiringroute name or add the resource token to call the downstream API.

    Agent web API receives user token from the calling application and validates the token via the Microsoft Entra ID Auth SDK (sidecar)matching /ValidateDownstreamApis endpoint Acquire token for downstream APIs by calling /AuthorizationHeader with only the AgentIdentity and the incoming authorization header

    # Step 1: Validate incoming user token
    GET /Validate
    Authorization: Bearer <user-token>
    
    # Step 2: Get authorization header on behalf of the user
    GET /AuthorizationHeader/Graph?AgentIdentity=<agent-identity-client-id>
    Authorization: Bearer <user-token>
    

Call an API

When obtaining the authorization header for calling a downstream API, the Microsoft Entra ID Auth SDK (sidecar) returns the Authorization header value that can be used directly in your API calls.

You can use this header to call the downstream API. The web API should validate the token by calling the /Validate endpoint of the Microsoft Entra ID Auth SDK (sidecar). This endpoint returns token claims for further authorization decisions.entry.

Related contentNext steps

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…