Installationshandbuch: Bereitstellen des Microsoft Entra SDK für AgentID

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

Voraussetzungen

• Zugriff auf die Microsoft-Containerregistrierung (MCR)
• Containerlaufzeit (Docker, Kubernetes oder Containerdienst)
• Registrieren Sie eine neue App im Microsoft Entra Admin Center, die nur für Konten 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 das Azure-Portal

Containerimage

Das Microsoft Entra SDK für AgentID wird als Containerimage aus dem MCR verteilt.

mcr.microsoft.com/entra-sdk/auth-sidecar:<tag>

Versionstags

• latest - Neueste stabile Version
• <version> - Spezifische Versionen (z. B. 1.0.0)
• <version>-preview - Vorschauversionen

Bereitstellungsmuster

Das Microsoft Entra SDK für AgentID ist dafür ausgelegt, als unterstützender Container parallel zu Ihrer Anwendung zu laufen. 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 SDK für AgentID 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 SDK for AgentID 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

Siehe Kubernetes im 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 Anwendungen und Microsoft Entra SDK für AgentID-Container, die Skalierung und Updates ermöglichen. 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 SDK für AgentID zusammen mit Ihrem Anwendungscontainer in einer lokalen Entwicklungsumgebung einrichten:

version: '3.8'

services:
  app:
    image: myregistry/myapp:latest
    ports:
      - "8080:8080"
    en - sidecar 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 Service (AKS) mit verwalteter Identität

Bei der Bereitstellung in AKS können Sie Azure Managed Identity verwenden, um das Microsoft Entra SDK für AgentID zu authentifizieren, ohne Anmeldeinformationen in der Konfiguration zu speichern. Zuerst müssen Sie Azure AD Workload Identity auf Ihrem AKS-Cluster aktivieren und einen Verbundidentitätsnachweis 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 SDK für AgentID für die Verwendung der Azure AD Workload Identity für die Authentifizierung mit dateibasierter Tokenprojektion konfiguriert. 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 SDK für AgentID und externen Diensten sicherzustellen, während der unbefugte Zugriff eingeschränkt wird. Die richtige Konfiguration verhindert Sicherheitsrisiken und stellt eine zuverlässige Verbindung mit 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

Um das Microsoft Entra SDK für AgentID nur für die interne pod-lokale Kommunikation zu konfigurieren, legen Sie die Endpunkt-URL in Ihrer Anwendung so fest, dass sie auf localhost oder 127.0.0.1 verweist, je nach Ihrer Umgebung.

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

Integritätsprüfungen

Das Microsoft Entra SDK für AgentID macht einen /health Endpunkt für Liveness- und Readiness-Sonden verfügbar und gewährleistet, dass der Container sicher läuft. 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 SDK für AgentID ist so konzipiert, dass sie mit Ihrer Anwendung skaliert wird:

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 Gesundheitsprüfungen

Überprüfen Sie, ob das Microsoft Entra SDK für AgentID reagiert:

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

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

Nächste Schritte

• Konfigurieren von Einstellungen – Einrichten der Identitätskonfiguration
• Überprüfen von Endpunkten – Erkunden der HTTP-API
• Sicherheitsbest Practices – Härten Ihrer Bereitstellung
• Auswählen eines Szenarios – Beginnen mit einem geführten Beispiel