Konfigurationsreferenz: Microsoft Entra ID Auth SDK-Einstellungen (Sidecar)

Dieses Handbuch enthält Konfigurationsoptionen für das Microsoft Entra ID Auth SDK (Sidecar), einen containerisierten Authentifizierungsdienst, der die Tokenerfassung und -verwaltung für Anwendungen in containerisierten Umgebungen verarbeitet. Das SDK vereinfacht die Identitätsintegration, indem Microsoft Entra ID Authentifizierung, OBO-Tokenflüsse und nachgeschaltete API-Aufrufe verwaltet werden, ohne dass Anwendungen Authentifizierungsbibliotheken direkt einbetten müssen.

Während sich dieses Handbuch auf Kubernetes-Bereitstellungsmuster konzentriert, kann das SDK in jeder containerisierten Umgebung bereitgestellt werden, einschließlich Docker, Azure Container Instances und anderen Container-Orchestrierungsplattformen.

Wenn Sie in Azure Kubernetes Service (AKS) bereitstellen, Entwicklungsumgebungen einrichten oder Produktionsworkloads konfigurieren, umfasst diese Referenz Konfigurationsmuster, Anmeldeinformationstypen und Umgebungsvariablen, die erforderlich sind, um Ihre Anwendungen mit Microsoft Entra ID zu sichern.

Übersicht über die Konfiguration

Das Microsoft Entra ID Auth SDK (Sidecar) wird mithilfe von Konfigurationsquellen konfiguriert, die ASP.NET Core Konventionen folgen. Konfigurationswerte können über mehrere Methoden bereitgestellt werden, darunter:

• Umgebungsvariablen (empfohlen für Kubernetes)
• Entra ID Konfiguration – appsettings.json Datei, die an den Container angefügt oder in die Yaml-Datei eingebettet ist.
• Befehlszeilenargumente
• Azure App Configuration oder Key Vault (für erweiterte Szenarien)

Kerneinstellungen für Entra ID

Microsoft Entra ID Auth SDK-Bereitstellungen (Sidecar) erfordern kernige Entra ID Einstellungen zum Authentifizieren eingehender Token und zum Abrufen von Token für downstream-APIs. Verwenden Sie die entsprechenden Clientanmeldeinformationen im folgenden YAML-Format, in der Regel als Umgebungsvariablen, um die sichere Authentifizierung sicherzustellen.

Erforderliche Konfiguration

Konfigurieren Sie zunächst die wichtigsten Entra ID Einstellungen für das SDK, um eingehende Token zu authentifizieren und Token für downstream-APIs zu erwerben.

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

Konfiguration von Clientanmeldeinformationen

Das Microsoft Entra ID Auth SDK (Sidecar) unterstützt mehrere Clientanmeldeinformationstypen für die Authentifizierung mit Microsoft Entra ID beim Abrufen von Token für downstream-APIs. Wählen Sie den Anmeldeinformationstyp aus, der ihrer Bereitstellungsumgebung und den Sicherheitsanforderungen am besten entspricht, und stellen Sie sicher, dass die ausgewählte Konfiguration für Ihr Szenario geeignet ist.

Jeder Anmeldeinformationstyp dient verschiedenen Szenarien:

• Geheimer Clientschlüssel: Einfaches Setup für Entwicklung und Tests (nicht für die Produktion empfohlen)
• Key Vault Certificate: Produktionsumgebungen mit zentralisierter Zertifikatverwaltung
• Dateizertifikat: Wenn Zertifikate als Dateien bereitgestellt werden (z. B. über Kubernetes geheime Schlüssel)
• Certificate Store: Windows Umgebungen mit Zertifikatspeichern
• Workload Identity for Containers: Recommended for AKS, using Microsoft Entra Workload ID with file-based token projection
• Managed Identity for VMs/App Services: Azure Virtual Machines und App Services mit system- oder vom Benutzer zugewiesenen verwalteten Identitäten (nicht für Container)

Konfigurieren Sie eine oder mehrere Anmeldeinformationsquellen im folgenden YAML-Format:

Auswählen einer Anmeldeinformation nach Umgebung

Wählen Sie die Anmeldeinformationen basierend auf dem Ort aus, an dem das Sidecar ausgeführt wird. SignedAssertionFromManagedIdentity Sowohl als auch SignedAssertionFilePath Verbundidentitätsanmeldeinformationen (FIC). Sie unterscheiden sich darin, wie das Sidecar die signierte Assertion erhält.

Wichtig: SignedAssertionFromManagedIdentity ist keine allgemeine Kubernetes-Anmeldeinformationen, und es ist kein Fallback für SignedAssertionFilePath. Es verwendet Azure managed Identity und Prüfpunkte Azure Hostingumgebungen wie Service Fabric, App Service und IMDS. Auf einem Nicht-Azure-Host findet er keine dieser Elemente, und die Anforderung löscht schließlich im IMDS.On a non-Azure host, it finds none of these, and the request times out against IMDS. Wenn Ihr Sidecar unerwartet IMDS erreicht, haben Sie diesen Quelltyp ausgewählt. Verwenden Sie stattdessen SignedAssertionFilePath.

Geheimer Clientschlüssel

Diese Konfiguration richtet Entra ID Authentifizierung mithilfe eines geheimen Clientschlüssels für die Dienst-zu-Dienst-Authentifizierung ein.

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

Zertifikat von Key Vault

Diese Konfiguration richtet Entra ID Authentifizierung mithilfe eines zertifikats ein, das in Azure Key Vault gespeichert ist.

- 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>"

Zertifikat aus Datei

Diese Konfiguration richtet Entra ID Authentifizierung mithilfe eines Zertifikats ein, das als Datei gespeichert ist.

- 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>"

Zertifikat aus Speicher

Diese Konfiguration richtet Entra ID Authentifizierung mithilfe eines Zertifikats aus dem lokalen Zertifikatspeicher ein.

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

Workload Identity on AKS (empfohlen für AKS)

Diese Konfiguration richtet Entra ID Authentifizierung mithilfe von Microsoft Entra Workload ID auf AKS ein. Dies ist der empfohlene Ansatz für AKS, da die Azure Workload Identity-Webhook-Projekte und das Token für Sie drehen.

- name: AzureAd__ClientCredentials__0__SourceType
  value: "SignedAssertionFilePath"

Hinweis: Auf AKS wird der Tokendateipfad /var/run/secrets/azure/tokens/azure-identity-token oder eine Umgebungsvariable automatisch vom Azure Workload Identity-Webhook projiziert, wenn Ihr Pod ordnungsgemäß mit der Dienstkontoanmerkung und der Pod-Bezeichnung konfiguriert ist. Vollständige Einrichtungsanweisungen finden Sie unter Verwenden der verwalteten Identität .

Workload Identity for non-Azure or on-premises Kubernetes

Der Agent-Identitätsfluss ist nicht auf AKS beschränkt. Jede Kubernetes-Plattform, einschließlich lokaler und anderer Clouds, kann mit workload identity federation verwendet werden SignedAssertionFilePath . Da kein Azure Workload Identity-Webhook außerhalb von AKS vorhanden ist, zeigen Sie das Sidecar auf das projizierte Dienstkontotoken, das Ihre Plattform bereitstellt.

- name: AzureAd__ClientCredentials__0__SourceType
  value: "SignedAssertionFilePath"
- name: AzureAd__ClientCredentials__0__SignedAssertionFileDiskPath
  value: "/var/run/secrets/tokens/sa-token"

Das Sidecar liest die Datei in jeder Tokenanforderung neu, sodass die plattformgesteuerte Drehung der projizierten Assertion automatisch unterstützt wird.

Um diese Anmeldeinformationen für Nicht-Azure Kubernetes zu verwenden, muss Ihre Umgebung die folgenden Voraussetzungen erfüllen:

• Ihre Kubernetes-Plattform projiziert ein Dienstkontotoken in den Sidecar-Pod, z. B. über ein projiziertes serviceAccountToken Volume.
• Der Cluster macht einen öffentlich erreichbaren OIDC-Aussteller und JWKS-Endpunkt verfügbar, sodass Microsoft Entra die Assertion überprüfen können.
• Für die Blueprint-Anwendung wird eine Verbundidentitäts-Anmeldeinformation (FIC) mit dem Aussteller und dem Betreff konfiguriert, der dem projizierten Token entspricht.

Wenn Ihre Plattform kein projiziertes OIDC-Token oder einen öffentlichen Aussteller bereitstellen kann, verwenden Sie stattdessen eine Zertifikatanmeldeinformationen wie Zertifikat aus Key Vault oder Zertifikat aus Datei.

Verwaltete Identität für VMs und App-Dienste

Verwenden Sie für klassische Azure Szenarien mit verwalteter Identität in Virtual Machines oder App Services (keine Container) SignedAssertionFromManagedIdentity:

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

Wichtig: Verwenden SignedAssertionFromManagedIdentity Sie nicht in nicht Azure oder lokalen Umgebungen. Sie verwendet Azure verwaltete Identität über IMDS und funktioniert nur auf Azure Berechnung, die verwaltete Identität bereitstellt. Auf einem Nicht-Azure-Host wird Azure Hostingendpunkte geprüft und dann ein Zeitüberschreitung für IMDS durchgeführt, das wie das SDK, das mit IMDS hartcodiert wird, aussehen kann. Verwenden Sie SignedAssertionFilePathfür Kubernetes überall, einschließlich AKS. Ausführliche Informationen finden Sie unter https://aka.ms/idweb/client-credentials

Weitere Ressourcen

Ausführliche Informationen zu allen Konfigurationsoptionen für Anmeldeinformationen und deren Verwendung finden Sie in der Spezifikation "CredentialDescription " im Repository "microsoft-identity-abstractions-for-dotnet".

Priorität der Anmeldeinformationen

Konfigurieren mehrerer Anmeldeinformationen mit prioritätsbasierter Auswahl:

# 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

Das Microsoft Entra ID Auth SDK (Sidecar) wertet Anmeldeinformationen in numerischer Reihenfolge (0, 1, 2 usw.) aus und verwendet die ersten Anmeldeinformationen, die sich erfolgreich authentifizieren.

Konfiguration nachgeschalteter APIs

Konfigurieren Sie downstream-APIs, die Ihre Anwendung mithilfe von OBO-Tokenflüssen aufrufen muss. Das Microsoft Entra ID Auth SDK (Sidecar) verwaltet den Tokenerwerb und stellt Authentifizierungsheader für diese API-Aufrufe bereit. Jede downstream-API erfordert einen eindeutigen Konfigurationsnamen und spezifische Parameter für die Tokenerfassung und die HTTP-Anforderungsverarbeitung.

Definieren Sie jede downstream-API mit ihrer Basis-URL, erforderlichen Bereichen und optionalen Parametern. Das SDK verarbeitet automatisch den Tokenerwerb mithilfe des eingehenden Benutzertokens und stellt die entsprechenden Autorisierungsheader für die API-Aufrufe Ihrer Anwendung bereit.

- 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"

Tokenakquisitionsoptionen

Optimieren des Tokenakquisitionsverhaltens:

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

- name: DownstreamApis__Graph__AcquireTokenOptions__AuthenticationScheme
  value: "Bearer"

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

Konfiguration der signierten HTTP-Anforderung (SHR)

Signierte HTTP-Anforderungen für erhöhte Sicherheit aktivieren:

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

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

Protokollierungskonfiguration

Protokollierungsebenen konfigurieren:

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

ASP.NET Core-Einstellungen

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

Per-Request-Konfigurationsüberschreibungen

Alle Tokenerfassungsendpunkte akzeptieren Abfrageparameter, um die Konfiguration außer Kraft zu setzen:

# 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>

Außerkraftsetzungen der Agentidentität

Angeben der Agentidentität zur Anforderungszeit:

# 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>

Wichtige Regeln:

• AgentUsername und AgentUserId erfordern AgentIdentity
• AgentUsername und AgentUserId schließen sich gegenseitig aus

Ausführliche Semantik finden Sie unter Agentidentitäten .

Vollständiges Konfigurationsbeispiel

Im Folgenden finden Sie ein produktionsbereites Beispiel, das zeigt, wie das SDK mit der richtigen Trennung von Konfiguration und geheimen Schlüsseln bereitgestellt wird. In diesem Beispiel wird das Konfigurieren mehrerer downstreamer APIs veranschaulicht, die Kubernetes ConfigMaps für nicht vertrauliche Einstellungen verwenden, Anmeldeinformationen sicher in geheimen Schlüsseln speichern und umgebungsspezifische Konfigurationen für die sichere Bereitstellung anwenden.

Dieses Muster folgt kubernetes bewährten Methoden, indem Konfigurationsdaten von vertraulichen Anmeldeinformationen getrennt werden, wodurch eine effektive Verwaltung verschiedener Umgebungen und gleichzeitig die Sicherheit ermöglicht wird.

Kubernetes ConfigMap

Die ConfigMap speichert nicht vertrauliche Konfigurationseinstellungen für das SDK, einschließlich Entra ID Einstellungen, downstream-APIs und Protokollierungsebenen.

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 Geheimnis

Der geheime Schlüssel speichert vertrauliche Anmeldeinformationen, z. B. geheime Clientschlüssel, getrennt von der ConfigMap.

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

Bereitstellung mit ConfigMap und geheimen Schlüsseln

Die Bereitstellung stellt sowohl die ConfigMap als auch den geheimen Schlüssel im SDK-Container bereit, um sicherzustellen, dass Konfiguration und Anmeldeinformationen ordnungsgemäß getrennt sind.

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

Umgebungsspezifische Konfiguration

Konfigurieren Sie umgebungsspezifische Einstellungen, um Die Sicherheit, Protokollierung und Mandantenisolation für Ihre Bereitstellungsumgebungen anzupassen. Jede Umgebung erfordert unterschiedliche Konfigurationsansätze, um entwicklungseffizienz, Stagingüberprüfung und Produktionssicherheitsanforderungen auszugleichen.

Entwicklung

- 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>"

Produktion

- 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

Das Microsoft Entra ID Auth SDK (Sidecar) überprüft die Konfiguration beim Start und protokolliert Fehler für:

• Fehlende erforderliche Einstellungen (TenantId, ClientId)
• Ungültige Konfigurationen für Anmeldeinformationen
• Falsch formatierte nachgeschaltete API-Definitionen
• Ungültige URLs oder Bereichsformate

Überprüfen sie Containerprotokolle auf Überprüfungsmeldungen:

kubectl logs <pod-name> -c sidecar

Problembehandlung bei Anmeldeinformationen

Anforderungen erreichen unerwartet IMDS oder Timeouts

Symptom: Das Sidecar hängt oder übergibt das Abrufen eines downstream-Tokens, und Protokolle zeigen Anforderungen an den IMDS-Endpunkt (169.254.169.254), auch auf einem Nicht-Azure-Host.

Ursache: Die Anmeldeinformationen werden als SignedAssertionFromManagedIdentitykonfiguriert. Dieser Quelltyp testet absichtlich Azure Hostingumgebungen und IMDS, die außerhalb Azure nicht vorhanden sind. Dies ist eine Konfiguration, keine Ausweichmöglichkeit von SignedAssertionFilePath.

Lösung:

1. Vergewissern Sie sich, dass die Effektive SourceTypeSignedAssertionFilePathnicht SignedAssertionFromManagedIdentity.
2. Überprüfen Sie, ob keine Umgebungsvariable oder ConfigMap-Außerkraftsetzung erneut eingeführt wird SignedAssertionFromManagedIdentity.
3. Stellen Sie sicher, dass SignedAssertionFileDiskPath auf das projizierte Token verweist, das im Sidecar-Container bereitgestellt wird.
4. Vergewissern Sie sich bei nicht-Azure Kubernetes, dass der OIDC-Aussteller des Clusters und JWKS öffentlich erreichbar sind und dass ein übereinstimmender FIC in der Blueprint-Anwendung vorhanden ist.

Wenn Sie ein dauerhaftes Problem melden, erfassen Sie die Sidecar-Version, die effektive Laufzeitkonfiguration und die Containerprotokolle aus einer fehlerhaften Anforderung.

Bewährte Methoden

1. Use Secrets for Credentials: Speichern geheimer Clientschlüssel und Zertifikate in Kubernetes Secrets oder Azure Key Vault. Siehe auch https://aka.ms/msidweb/client-credentials
2. Separate Konfiguration pro Umgebung: Verwenden von ConfigMaps zum Verwalten von umgebungsspezifischen Einstellungen
3. Aktivieren der geeigneten Protokollierung: Verwenden der Debugprotokollierung in der Entwicklung, Information/Warnung in der Produktion
4. Konfigurieren von Integritätsprüfungen: Sicherstellen, dass Endpunkte für die Integritätsprüfung ordnungsgemäß konfiguriert sind
5. Verwenden der Workloadidentität für Container: Für containerisierte Bereitstellungen (AKS) bevorzugen Sie Microsoft Entra Workload ID mit SignedAssertionFilePath über geheimen Clientschlüsseln für erhöhte Sicherheit.
6. Use Managed Identity for VMs/App Services: For Azure VMs and App Services, use system or user-assigned managed identity
7. Überprüfen zur Bereitstellungszeit: Testen der Konfiguration im Staging vor der Produktionsbereitstellung

Verwandte Inhalte

• Agentidentitäten
• Endpunktreferenz
• Bewährte Methoden für Sicherheit
• Problembehandlung