Configuration reference: Microsoft Entra SDK for AgentID settings

This guide provides configuration options for the Microsoft Entra SDK for AgentID, a containerized authentication service that handles token acquisition and management for applications in containerized environments. The SDK simplifies identity integration by managing Microsoft Entra ID authentication, on-behalf-of (OBO) token flows, and downstream API calls without requiring applications to embed authentication libraries directly.

While this guide focuses on Kubernetes deployment patterns, the SDK can be deployed in any containerized environment including Docker, Azure Container Instances, and other container orchestration platforms.

If you're deploying to Azure Kubernetes Service (AKS), setting up development environments, or configuring production workloads, this reference covers configuration patterns, credential types, and environment variables needed to secure your applications with Microsoft Entra ID.

Configuration overview

The Microsoft Entra SDK for AgentID is configured using configuration sources following ASP.NET Core conventions. Configuration values can be provided via multiple methods, including:

• Environment variables (recommended for Kubernetes)
• Entra ID configuration - appsettings.json file attached to the container, or embedded in the yaml file.
• Command-line arguments
• Azure App Configuration or Key Vault (for advanced scenarios)

Core Entra ID settings

Microsoft Entra SDK for AgentID deployments require core Entra ID settings to authenticate incoming tokens and acquire tokens for downstream APIs. Use the appropriate client credentials in the following YAML format, typically as environment variables, to ensure secure authentication.

Required configuration

First, configure the core Entra ID settings for the SDK to authenticate incoming tokens and acquire tokens for downstream APIs.

env:
- name: AzureAd__Instance
  value: "https://login.microsoftonline.com/"
- name: AzureAd__TenantId
  value: "<your-tenant-id>"
- name: AzureAd__ClientId
  value: "<your-client-id>"

Client credentials configuration

The Microsoft Entra SDK for AgentID supports multiple client credential types for authenticating with Microsoft Entra ID when acquiring tokens for downstream APIs. Choose the credential type that best fits your deployment environment and security requirements, and ensure that the configuration you choose is appropriate for your scenario.

Each credential type serves different scenarios:

• Client Secret: Simple setup for development and testing (not recommended for production)
• Key Vault Certificate: Production environments with centralized certificate management
• File Certificate: When certificates are mounted as files (e.g., via Kubernetes secrets)
• Certificate Store: Windows environments with certificate stores
• Workload Identity for Containers: Recommended for AKS, using Azure AD Workload Identity with file-based token projection
• Managed Identity for VMs/App Services: Azure Virtual Machines and App Services with system or user-assigned managed identities (not for containers)

Configure one or more credential sources in the following YAML format:

Client Secret

This configuration sets up Entra ID authentication using a client secret for service-to-service authentication.

- name: AzureAd__ClientCredentials__0__SourceType
  value: "ClientSecret"
- name: AzureAd__ClientCredentials__0__ClientSecret
  value: "<your-client-secret>"

Certificate from Key Vault

This configuration sets up Entra ID authentication using a certificate stored in Azure Key Vault.

- name: AzureAd__ClientCredentials__0__SourceType
  value: "KeyVault"
- name: AzureAd__ClientCredentials__0__KeyVaultUrl
  value: "https://<your-keyvault>.vault.azure.net"
- name: AzureAd__ClientCredentials__0__KeyVaultCertificateName
  value: "<certificate-name>"

Certificate from file

This configuration sets up Entra ID authentication using a certificate stored as a file.

- name: AzureAd__ClientCredentials__0__SourceType
  value: "Path"
- name: AzureAd__ClientCredentials__0__CertificateDiskPath
  value: "/path/to/certificate.pfx"
- name: AzureAd__ClientCredentials__0__CertificatePassword
  value: "<certificate-password>"

Certificate from store

This configuration sets up Entra ID authentication using a certificate from the local certificate store.

- name: AzureAd__ClientCredentials__0__SourceType
  value: "StoreWithThumbprint"
- name: AzureAd__ClientCredentials__0__CertificateStorePath
  value: "CurrentUser/My"
- name: AzureAd__ClientCredentials__0__CertificateThumbprint
  value: "<thumbprint>"

Workload Identity for containers (recommended for AKS)

This configuration sets up Entra ID authentication using Azure AD Workload Identity for containerized deployments (AKS). This is the recommended approach for container-based scenarios as it uses file-based token projection.

- name: AzureAd__ClientCredentials__0__SourceType
  value: "SignedAssertionFilePath"

Note: The token file path /var/run/secrets/azure/tokens/azure-identity-token or an environment variable is automatically projected by the Azure Workload Identity webhook when your pod is properly configured with the service account annotation and pod label. See Using Managed Identity for complete setup instructions.

Managed Identity for VMs and App Services

For classic Azure Managed Identity scenarios on Virtual Machines or App Services (not containers), use SignedAssertionFromManagedIdentity:

- name: AzureAd__ClientCredentials__0__SourceType
  value: "SignedAssertionFromManagedIdentity"
- name: AzureAd__ClientCredentials__0__ManagedIdentityClientId
  value: "<managed-identity-client-id>"

Important: Do not use SignedAssertionFromManagedIdentity for containerized environments (Kubernetes, AKS, Docker). For AKS, use SignedAssertionFilePath as shown above. For Kubernetes and Docker, use client certificates. For details see https://aka.ms/idweb/client-credentials

Additional Resources

For complete details on all credential configuration options and their usage, see the CredentialDescription specification in the microsoft-identity-abstractions-for-dotnet repository.

Credentials priority

Configure multiple credentials with priority-based selection:

# First priority - Key Vault certificate
- name: AzureAd__ClientCredentials__0__SourceType
  value: "KeyVault"
- name: AzureAd__ClientCredentials__0__KeyVaultUrl
  value: "https://prod-keyvault.vault.azure.net"
- name: AzureAd__ClientCredentials__0__KeyVaultCertificateName
  value: "prod-cert"

# Second priority - Client secret (fallback)
- name: AzureAd__ClientCredentials__1__SourceType
  value: "ClientSecret"
- name: AzureAd__ClientCredentials__1__ClientSecret
  valueFrom:
    secretKeyRef:
      name: app-secrets
      key: client-secret

The Microsoft Entra SDK for AgentID evaluates credentials in numerical order (0, 1, 2, etc.) and uses the first credential that successfully authenticates.

Downstream APIs configuration

Configure downstream APIs that your application needs to call using on-behalf-of (OBO) token flows. The Microsoft Entra SDK for AgentID manages token acquisition and provides authentication headers for these API calls. Each downstream API requires a unique configuration name and specific parameters for token acquisition and HTTP request handling.

Define each downstream API with its base URL, required scopes, and optional parameters. The SDK will automatically handle token acquisition using the incoming user token and provide the appropriate authorization headers for your application's API calls.

- name: DownstreamApis__Graph__BaseUrl
  value: "https://graph.microsoft.com/v1.0"
- name: DownstreamApis__Graph__Scopes
  value: "User.Read Mail.Read"
- name: DownstreamApis__Graph__RelativePath
  value: "/me"

- name: DownstreamApis__MyApi__BaseUrl
  value: "https://api.contoso.com"
- name: DownstreamApis__MyApi__Scopes
  value: "api://myapi/.default"

Token acquisition options

Fine-tune token acquisition behavior:

- name: DownstreamApis__Graph__AcquireTokenOptions__Tenant
  value: "<specific-tenant-id>"

- name: DownstreamApis__Graph__AcquireTokenOptions__AuthenticationScheme
  value: "Bearer"

- name: DownstreamApis__Graph__AcquireTokenOptions__CorrelationId
  value: "<correlation-id>"

Signed HTTP Request (SHR) configuration

Enable Signed HTTP Requests for enhanced security:

- name: DownstreamApis__SecureApi__AcquireTokenOptions__PopPublicKey
  value: "<base64-encoded-public-key>"

- name: DownstreamApis__SecureApi__AcquireTokenOptions__PopClaims
  value: '{"custom_claim": "value"}'

Logging configuration

Configure logging levels:

- name: Logging__LogLevel__Default
  value: "Information"
- name: Logging__LogLevel__Microsoft.Identity.Web
  value: "Debug"
- name: Logging__LogLevel__Microsoft.AspNetCore
  value: "Warning"

ASP.NET Core settings

- name: ASPNETCORE_ENVIRONMENT
  value: "Production"
- name: ASPNETCORE_URLS
  value: "http://+:5000"

Per-Request configuration overrides

All token acquisition endpoints accept query parameters to override configuration:

# Override scopes
GET /AuthorizationHeader/Graph?optionsOverride.Scopes=User.Read&optionsOverride.Scopes=Mail.Read

# Request app token instead of OBO
GET /AuthorizationHeader/Graph?optionsOverride.RequestAppToken=true

GET /AuthorizationHeaderUnauthenticated/Graph?optionsOverride.RequestAppToken=true

# Override tenant
GET /AuthorizationHeader/Graph?optionsOverride.AcquireTokenOptions.Tenant=<tenant-id>

# Override relative path
GET /DownstreamApi/Graph?optionsOverride.RelativePath=me/messages

# Enable SHR for this request
GET /AuthorizationHeader/Graph?optionsOverride.AcquireTokenOptions.PopPublicKey=<base64-key>

Agent Identity Overrides

Specify agent identity at request time:

# Autonomous agent
GET /AuthorizationHeader/Graph?AgentIdentity=<agent-client-id>

# Autonomous agent with specific agent user identity (by username)
GET /AuthorizationHeader/Graph?AgentIdentity=<agent-client-id>&AgentUsername=user@contoso.com

# Autonomous agent with specific agent user identity (by object ID)
GET /AuthorizationHeader/Graph?AgentIdentity=<agent-client-id>&AgentUserId=<user-object-id>

Important Rules:

• AgentUsername and AgentUserId require AgentIdentity
• AgentUsername and AgentUserId are mutually exclusive

See Agent Identities for detailed semantics.

Complete configuration example

The following provides a production-ready example showing how to deploy the SDK with proper separation of configuration and secrets. This example demonstrates configuring multiple downstream APIs, using Kubernetes ConfigMaps for non-sensitive settings, storing credentials securely in Secrets, and applying environment-specific configurations for secure deployment.

This pattern follows Kubernetes best practices by separating configuration data from sensitive credentials, enabling effective management of different environments while maintaining security.

Kubernetes ConfigMap

The ConfigMap stores non-sensitive configuration settings for the SDK, including Entra ID settings, downstream APIs, and logging levels.

apiVersion: v1
kind: ConfigMap
metadata:
  name: sidecar-config
data:
  ASPNETCORE_ENVIRONMENT: "Production"
  ASPNETCORE_URLS: "http://+:5000"
  
  AzureAd__Instance: "https://login.microsoftonline.com/"
  AzureAd__TenantId: "common"
  AzureAd__ClientId: "your-app-client-id"
  AzureAd__Scopes: "access_as_user"
  
  DownstreamApis__Graph__BaseUrl: "https://graph.microsoft.com/v1.0"
  DownstreamApis__Graph__Scopes: "User.Read Mail.Read"
  
  DownstreamApis__MyApi__BaseUrl: "https://api.contoso.com"
  DownstreamApis__MyApi__Scopes: "api://myapi/.default"
  
  Logging__LogLevel__Default: "Information"
  Logging__LogLevel__Microsoft.Identity.Web: "Debug"

Kubernetes secret

The Secret stores sensitive credentials, such as client secrets, separately from the ConfigMap.

apiVersion: v1
kind: Secret
metadata:
  name: sidecar-secrets
type: Opaque
stringData:
  AzureAd__ClientCredentials__0__ClientSecret: "your-client-secret"

Deployment with ConfigMap and secret

The Deployment mounts both the ConfigMap and Secret into the SDK container, ensuring that configuration and credentials are properly separated.

apiVersion: apps/v1
kind: Deployment
metadata:
  name: myapp
spec:
  template:
    spec:
      containers:
      - name: sidecar
        image: mcr.microsoft.com/entra-sdk/auth-sidecar:1.0.0
        envFrom:
        - configMapRef:
            name: sidecar-config
        - secretRef:
            name: sidecar-secrets

Environment-specific configuration

Configure environment-specific settings to tailor security, logging, and tenant isolation for your deployment environments. Each environment requires different configuration approaches to balance development efficiency, staging validation, and production security requirements.

Development

- name: ASPNETCORE_ENVIRONMENT
  value: "Development"
- name: Logging__LogLevel__Default
  value: "Debug"
- name: AzureAd__TenantId
  value: "<dev-tenant-id>"

Staging

- name: ASPNETCORE_ENVIRONMENT
  value: "Staging"
- name: Logging__LogLevel__Default
  value: "Information"
- name: AzureAd__TenantId
  value: "<staging-tenant-id>"

Production

- name: ASPNETCORE_ENVIRONMENT
  value: "Production"
- name: Logging__LogLevel__Default
  value: "Warning"
- name: Logging__LogLevel__Microsoft.Identity.Web
  value: "Information"
- name: AzureAd__TenantId
  value: "<prod-tenant-id>"
- name: ApplicationInsights__ConnectionString
  value: "<app-insights-connection>"

Validation

The Microsoft Entra SDK for AgentID validates configuration at startup and logs errors for:

• Missing required settings (TenantId, ClientId)
• Invalid credential configurations
• Malformed downstream API definitions
• Invalid URLs or scope formats

Check container logs for validation messages:

kubectl logs <pod-name> -c sidecar

Best practices

1. Use Secrets for Credentials: Store client secrets and certificates in Kubernetes Secrets or Azure Key Vault. See also https://aka.ms/msidweb/client-credentials
2. Separate Configuration per Environment: Use ConfigMaps to manage environment-specific settings
3. Enable Appropriate Logging: Use Debug logging in development, Information/Warning in production
4. Configure Health Checks: Ensure health check endpoints are properly configured
5. Use Workload Identity for Containers: For containerized deployments (AKS), prefer Azure AD Workload Identity with SignedAssertionFilePath over client secrets for enhanced security
6. Use Managed Identity for VMs/App Services: For Azure VMs and App Services, use system or user-assigned managed identities
7. Validate at Deploy Time: Test configuration in staging before production deployment

See Also

• Agent Identities
• Endpoints Reference
• Security Best Practices
• Troubleshooting