Installationshandbuch: Bereitstellen des Microsoft Entra ID Auth SDK (Sidecar)

Das Microsoft Entra ID Auth SDK (Sidecar) ist ein einsatzbereiter containerisierter Authentifizierungsdienst, der den sicheren Tokenerwerb für Ihre Anwendungen optimiert. Dieses Installationshandbuch enthält schrittweise Anleitungen zum Bereitstellen des SDK-Containers in Kubernetes-, Docker- und Azure-Umgebungen, ohne dass vertrauliche Anmeldeinformationen direkt in Ihren Anwendungscode eingebettet werden müssen.

Voraussetzungen

• Zugriff auf Microsoft Artifact Registry
• Containerlaufzeit (Docker, Kubernetes oder Containerdienst)
• Registrieren Sie eine neue App im Microsoft Entra Admin Center, die nur für Accounts in diesem Organisationsverzeichnis konfiguriert ist. Weitere Informationen finden Sie unter Registrieren einer Anwendung . Notieren Sie die folgenden Werte auf der Anwendungsübersichtsseite für die spätere Verwendung:
  • Anwendungs-ID (Client)
  • Verzeichnis-ID (Mandant)
• Anmeldeinformationen für die Anwendung:
  • Geheimer Clientschlüssel oder Zertifikat, das sicher gespeichert ist (z. B. Azure Key Vault)
• Für Azure Bereitstellungen: Azure CLI oder Zugriff auf Azure Portal

Containerimage

Das Microsoft Entra ID-Authentifizierungs-SDK (Sidecar) wird als Containerimage aus der Artefaktregistrierung verteilt.

mcr.microsoft.com/entra-sdk/auth-sidecar

Bereitstellungsmuster

Das Microsoft Entra ID Auth SDK (Sidecar) ist für die Ausführung als Begleitcontainer zusammen mit Ihrer Anwendung konzipiert. Auf diese Weise kann Ihre Anwendung die Tokenakquisition und -verwaltung über HTTP-Aufrufe in das SDK auslagern und vertrauliche Anmeldeinformationen aus Ihrem Anwendungscode fernhalten. Im Folgenden werden allgemeine Bereitstellungsmuster beschrieben, die an Ihre spezifische Umgebung angepasst werden sollten.

Kubernetes-Muster

Stellen Sie das Microsoft Entra ID Auth SDK (Sidecar) im selben Pod wie Ihr Anwendungscontainer für sichere pod-lokale Kommunikation bereit. Dieses Muster stellt sicher, dass der Authentifizierungsdienst zusammen mit Ihrer App ausgeführt wird und gleichzeitig den schnellen HTTP-basierten Tokenerwerb ermöglicht, während Anmeldeinformationen vom Anwendungscode isoliert bleiben:

apiVersion: v1
kind: Pod
metadata:
  # Your application container
  name: myapp
spec:
  containers:
  - name: app
    image: myregistry/myapp:latest
    ports:
    - containerPort: 8080
    env:
    - name: SIDECAR_URL
      value: "http://localhost:5000"
  # Microsoft Entra ID Auth SDK (sidecar) container
  - name: sidecar
    image: mcr.microsoft.com/entra-sdk/auth-sidecar:1.0.0
    ports:
    - containerPort: 5000
    env:
    - name: AzureAd__TenantId
      value: "your-tenant-id"
    - name: AzureAd__ClientId
      value: "your-client-id"
    - 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: "your-cert-name"

Kubernetes-Bereitstellung

Weitere Informationen finden Sie unter Kubernetes in Azure Lernprogramm – Vorbereiten einer Anwendung für Azure Kubernetes Service (AKS), wenn Sie Azure Kubernetes Services als Ziel festlegen möchten. Dieses Muster verwendet eine Bereitstellungsressource zum Verwalten von Anwendungs- und Microsoft Entra ID Auth SDK-Containern (Sidecar), sodass Skalierung und Updates möglich sind. Die Bereitstellung behandelt auch Integritätsprüfungen und Ressourcenzuweisungen, um einen sicheren Betrieb in Produktionsumgebungen sicherzustellen:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: myapp-deployment
spec:
  replicas: 3
  selector:
    matchLabels:
      app: myapp
  template:
    metadata:
      labels:
        app: myapp
    spec:
      serviceAccountName: myapp-sa
      containers:
      - name: app
        image: myregistry/myapp:latest
        ports:
        - containerPort: 8080
        env:
        - name: SIDECAR_URL
          value: "http://localhost:5000"
        resources:
          requests:
            memory: "256Mi"
            cpu: "250m"
          limits:
            memory: "512Mi"
            cpu: "500m"
      
      - name: sidecar
        image: mcr.microsoft.com/entra-sdk/auth-sidecar:1.0.0
        ports:
        - containerPort: 5000
        env:
        - name: AzureAd__TenantId
          valueFrom:
            configMapKeyRef:
              name: app-config
              key: tenant-id
        - name: AzureAd__ClientId
          valueFrom:
            configMapKeyRef:
              name: app-config
              key: client-id
        - name: AzureAd__Instance
          value: "https://login.microsoftonline.com/"
        resources:
          requests:
            memory: "128Mi"
            cpu: "100m"
          limits:
            memory: "256Mi"
            cpu: "250m"
        livenessProbe:
          httpGet:
            path: /health
            port: 5000
          initialDelaySeconds: 10
          periodSeconds: 10
        readinessProbe:
          httpGet:
            path: /health
            port: 5000
          initialDelaySeconds: 5
          periodSeconds: 5

Docker Compose

Wenn Sie in einer Docker-Umgebung arbeiten, können Sie Docker Compose verwenden, um Anwendungen mit mehreren Containern zu definieren und auszuführen. Im folgenden Beispiel wird veranschaulicht, wie Sie das Microsoft Entra ID Auth SDK (Sidecar) zusammen mit Ihrem Anwendungscontainer in einer lokalen Entwicklungsumgebung einrichten:

version: '3.8'

services:
  app:
    image: myregistry/myapp:latest
    ports:
      - "8080:8080"
    environment:
      - AzureAd__TenantId=${TENANT_ID}
      - AzureAd__ClientId=${CLIENT_ID}
      - AzureAd__ClientCredentials__0__SourceType=ClientSecret
      - AzureAd__ClientCredentials__0__ClientSecret=${CLIENT_SECRET}
    networks:
      - app-network

networks:
  app-network:
    driver: bridge

Azure Kubernetes-Dienst (AKS) mit verwalteter Identität

Bei der Bereitstellung für AKS können Sie verwaltete Azure-Identität verwenden, um das Microsoft Entra ID Auth SDK (Sidecar) zu authentifizieren, ohne Anmeldeinformationen in der Konfiguration zu speichern. Zuerst müssen Sie Microsoft Entra Workload ID auf Ihrem AKS-Cluster aktivieren und eine Verbundidentitätsanmeldeinformationen für Ihre verwaltete Identität erstellen. Konfigurieren Sie dann das SDK für die Verwendung der verwalteten Identität für die Authentifizierung.

Schritt 1: Erstellen verwalteter Identität

Erstellen einer verwalteten Identität und Zuweisen entsprechender Berechtigungen

# Create managed identity
az identity create \
  --resource-group myResourceGroup \
  --name myapp-identity

# Get the identity details
IDENTITY_CLIENT_ID=$(az identity show \
  --resource-group myResourceGroup \
  --name myapp-identity \
  --query clientId -o tsv)

IDENTITY_OBJECT_ID=$(az identity show \
  --resource-group myResourceGroup \
  --name myapp-identity \
  --query principalId -o tsv)

Schritt 2: Zuweisen von Berechtigungen

Gewähren Sie der verwalteten Identität Berechtigungen für den Zugriff auf nachgelagerte APIs.

# Example: Grant permission to call Microsoft Graph
az ad app permission add \
  --id $IDENTITY_CLIENT_ID \
  --api 00000003-0000-0000-c000-000000000000 \
  --api-permissions e1fe6dd8-ba31-4d61-89e7-88639da4683d=Scope

Schritt 3: Konfigurieren der Workloadidentität

Erstellen Eines Dienstkontos mit Workload-Identitätsverbund:

export AKS_OIDC_ISSUER=$(az aks show \
  --resource-group myResourceGroup \
  --name myAKSCluster \
  --query "oidcIssuerProfile.issuerUrl" -o tsv)

az identity federated-credential create \
  --name myapp-federated-identity \
  --identity-name myapp-identity \
  --resource-group myResourceGroup \
  --issuer $AKS_OIDC_ISSUER \
  --subject system:serviceaccount:default:myapp-sa

Schritt 4: Bereitstellen mit Workload-Identität

Im folgenden Bereitstellungsbeispiel ist das Microsoft Entra ID Auth SDK (Sidecar) so konfiguriert, dass Microsoft Entra Workload ID für die Authentifizierung mithilfe der dateibasierten Tokenprojektion verwendet wird. Der SignedAssertionFilePath Anmeldedatentyp liest das Token aus der Datei, die vom Workload Identity-Webhook bereitgestellt wird.

apiVersion: v1
kind: ServiceAccount
metadata:
  name: myapp-sa
  namespace: default
  annotations:
    azure.workload.identity/client-id: "<MANAGED_IDENTITY_CLIENT_ID>"

---
apiVersion: apps/v1
kind: Deployment
metadata:
  name: myapp-deployment
spec:
  template:
    metadata:
      labels:
        azure.workload.identity/use: "true"
    spec:
      serviceAccountName: myapp-sa
      containers:
      - name: app
        image: myregistry/myapp:latest
        env:
        - name: SIDECAR_URL
          value: "http://localhost:5000"
      
      - name: sidecar
        image: mcr.microsoft.com/entra-sdk/auth-sidecar:1.0.0
        ports:
        - containerPort: 5000
        env:
        - name: AzureAd__TenantId
          value: "your-tenant-id"
        - name: AzureAd__ClientId
          value: "<MANAGED_IDENTITY_CLIENT_ID>"
        
        # Workload Identity credentials - uses file-based token projection
        - name: AzureAd__ClientCredentials__0__SourceType
          value: "SignedAssertionFilePath"

Hinweis: Der Workload-Identitätswebhook projiziert das Verbundtoken automatisch in /var/run/secrets/azure/tokens/azure-identity-token oder eine Umgebungsvariable, wenn der Pod das erforderliche Label und die Dienstkontoanmerkung hat.

Netzwerkkonfiguration

Die richtige Netzwerkkonfiguration ist unerlässlich, um die sichere Kommunikation zwischen dem Microsoft Entra ID Auth SDK (Sidecar) und externen Diensten sicherzustellen, während der unbefugte Zugriff eingeschränkt wird. Die richtige Konfiguration verhindert Sicherheitsrisiken und stellt eine zuverlässige Verbindung zu Microsoft Entra ID Endpunkten sicher. Verwenden Sie die folgenden Richtlinien, um den Netzwerkzugriff für das SDK abhängig von Ihrer Bereitstellungsumgebung zu konfigurieren.

Nur interne Kommunikation

Wenn Sie das Microsoft Entra ID Auth SDK (Sidecar) nur für die interne podlokale Kommunikation konfigurieren möchten, legen Sie die Endpunkt-URL in Ihrer Anwendung so fest, dass sie je nach Ihrer Umgebung auf localhost oder 127.0.0.1 verweist:

containers:
- name: sidecar
  env:
  - name: Kestrel__Endpoints__Http__Url
    value: "http://127.0.0.1:5000" # Same pod, localhost communication

Netzwerkrichtlinien

Um den Netzwerkzugriff weiter einzuschränken, sollten Sie kubernetes-Netzwerkrichtlinien implementieren, um den Datenverkehr auf und vom SDK-Container zu beschränken:

apiVersion: networking.k8s.io/v1
kind: NetworkPolicy
metadata:
  name: sidecar-network-policy
spec:
  podSelector:
    matchLabels:
      app: myapp
  policyTypes:
  - Ingress
  - Egress
  ingress:
  # No external ingress rules - only pod-local communication
  egress:
  - to:
    - namespaceSelector:
        matchLabels:
          name: kube-system
    ports:
    - protocol: TCP
      port: 53  # DNS
  - to:
    - podSelector: {}
  - to:
    # Allow outbound to Microsoft Entra ID
    ports:
    - protocol: TCP
      port: 443

Gesundheitschecks

Das Auth SDK von Microsoft Entra ID (Sidecar) stellt einen /health-Endpunkt für Lebensfähigkeits- und Bereitschaftsprüfungen bereit und stellt sicher, dass der Container sicher ausgeführt werden kann. Konfigurieren Sie Ihre Bereitstellung so, dass sie die folgenden Prüfpunkte enthält:

livenessProbe:
  httpGet:
    path: /health
    port: 5000
  initialDelaySeconds: 10
  periodSeconds: 10

readinessProbe:
  httpGet:
    path: /health
    port: 5000
  initialDelaySeconds: 5
  periodSeconds: 5

Ressourcenanforderungen

Die empfohlenen Ressourcenzuordnungen lauten wie folgt, stellen jedoch sicher, dass sie basierend auf der Tokenakquisitionshäufigkeit, der Anzahl der konfigurierten downstream-APIs und der Cachegrößenanforderungen angepasst werden:

Überlegungen zur Skalierung

Das Microsoft Entra ID Auth SDK (Sidecar) ist für die Skalierung mit Ihrer Anwendung konzipiert:

1. Zustandsloses Design: Jede SDK-Instanz verwaltet einen eigenen Tokencache.
2. Horizontale Skalierung: Skalieren durch Hinzufügen weiterer Anwendungs pods (jeweils mit einer eigenen SDK-Instanz)
3. Cacheerwärmung: Erwägen Sie die Implementierung von Cacheerwärmungsstrategien für Szenarien mit hohem Datenverkehr

Problembehandlung bei der Bereitstellung

Häufige Probleme, die auftreten können, können auf ungültige Konfigurationswerte, Netzwerkkonnektivität mit Microsoft Entra ID oder fehlende Anmeldeinformationen oder Zertifikate zurückzuführen sein. Stellen Sie sicher, dass der verwaltete Identitäts- oder Dienstprinzipal über die richtigen Anwendungsberechtigungen, die Administratorzustimmung (falls erforderlich) und die richtigen Rollenzuweisungen verfügt.

Im Folgenden finden Sie einige häufige Schritte zur Problembehandlung, mit denen Sie Bereitstellungsprobleme beheben können:

Container startet nicht

Containerprotokolle überprüfen:

kubectl logs <pod-name> -c sidecar

Fehler bei der Gesundheitsprüfung

Überprüfen Sie, ob das Microsoft Entra ID Auth SDK (Sidecar) reagiert:

kubectl exec <pod-name> -c sidecar -- curl http://localhost:5000/health

Ausführlichere Schritte zur Problembehandlung finden Sie im Handbuch zur Problembehandlung.

Verwandte Inhalte

• Konfigurationsreferenz
• Endpunktreferenz
• Bewährte Methoden für Sicherheit
• Autorisierungsheader überprüfen