Installationshandbuch: Bereitstellen des Microsoft Entra SDK für AgentID

Das Microsoft Entra SDK für Agent-ID 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 SDK für Agent-ID wird als Containerimage aus der Artefaktregistrierung verteilt.

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

Bereitstellungsmuster

Das Microsoft Entra SDK für Agent-ID 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 SDK für Agent-ID 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 Agent ID 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 Anwendungen und Microsoft Entra SDK für Agent-ID-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 Agent-ID 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 in AKS können Sie Azure Managed Identity verwenden, um das Microsoft Entra SDK für die Authentifizierung der Agent-ID zu nutzen, ohne Anmeldeinformationen in der Konfiguration speichern zu müssen. 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 SDK für Agent-ID 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 SDK für Agent-ID und externen Diensten sicherzustellen und nicht autorisierten Zugriff einzuschränken. 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

Um das Microsoft Entra SDK für die Agent-ID nur für die interne pod-lokale Kommunikation zu konfigurieren, legen Sie die Endpunkt-URL in Ihrer Anwendung so fest, dass sie je nach 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 Microsoft Entra SDK für Agent-ID stellt einen /health-Endpunkt für Lebendheits- und Bereitschaftssonden bereit, um sicherzustellen, dass der Container sicher betrieben wird. 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 Agent-ID 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 der Gesundheitsprüfung

Überprüfen Sie, ob das Microsoft Entra SDK für die Agent-ID 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