Przewodnik dotyczący instalacji: wdrażanie zestawu SDK uwierzytelniania Microsoft Entra ID (sidecar)

Zestaw SDK uwierzytelniania Microsoft Entra ID (sidecar) to gotowa do wdrożenia konteneryzowana usługa uwierzytelniania, która usprawnia bezpieczne uzyskiwanie tokenów dla Twoich aplikacji. Ten przewodnik instalacji zawiera instrukcje krok po kroku dotyczące wdrażania kontenera zestawu SDK w środowiskach Kubernetes, Docker i Azure, eliminując konieczność osadzania poufnych poświadczeń bezpośrednio w kodzie aplikacji.

Wymagania wstępne

• Dostęp do Microsoft Artifact Registry
• Środowisko uruchomieniowe kontenera (Docker, Kubernetes lub usługa kontenera)
• Zarejestruj nową aplikację w centrum administracyjne Microsoft Entra, skonfigurowaną dla tylko kont w tym katalogu organizacyjnym. Aby uzyskać więcej informacji, zobacz Rejestrowanie aplikacji . Zapisz następujące wartości na stronie Przegląd aplikacji do późniejszego użycia:
  • Identyfikator aplikacji (klienta)
  • Identyfikator katalogu (klienta)
• Poświadczenia aplikacji:
  • Klucz tajny klienta lub certyfikat przechowywany bezpiecznie (np. Azure Key Vault)
• W przypadku wdrożeń Azure: Azure CLI lub dostępu do portalu Azure portal

Obraz kontenera

Pakiet SDK uwierzytelniania Microsoft Entra ID (sidecar) jest udostępniany jako obraz kontenera z rejestru artefaktów

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

Wzorce wdrażania

Zestaw SDK uwierzytelniania dla Microsoft Entra ID (sidecar) jest przeznaczony do działania jako kontener towarzyszący wraz z aplikacją. Dzięki temu aplikacja może odciążyć pozyskiwanie tokenów i przekazanie zarządzania zestawowi SDK za pośrednictwem wywołań HTTP i utrzymuje poufne poświadczenia poza kodem aplikacji. Poniżej przedstawiono typowe wzorce wdrażania i należy je dostosować do określonego środowiska.

Wzorzec platformy Kubernetes

Wdróż bibliotekę Microsoft Entra ID Auth SDK (sidecar) w tym samym podzie co kontener aplikacji, aby zapewnić bezpieczną komunikację lokalną w obrębie poda. Ten wzorzec zapewnia, że usługa uwierzytelniania działa wraz z aplikacją, umożliwiając szybkie pozyskiwanie tokenów opartych na protokole HTTP przy jednoczesnym zachowaniu poświadczeń odizolowanych od kodu aplikacji:

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"

Wdrożenie rozwiązania Kubernetes

Zobacz samouczek Kubernetes w Azure — przygotowywanie aplikacji do Azure Kubernetes Service (AKS), jeśli chcesz celować w Azure Kubernetes Service. Ten wzorzec wykorzystuje zasób Deployment do zarządzania kontenerami aplikacji oraz kontenerami sidecar Microsoft Entra ID Auth SDK, umożliwiając skalowanie i aktualizacje. Wdrożenie obsługuje również kontrole kondycji i alokację zasobów, zapewniając bezpieczną operację w środowiskach produkcyjnych:

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: /healthz
            port: 5000
          initialDelaySeconds: 10
          periodSeconds: 10
        readinessProbe:
          httpGet:
            path: /healthz
            port: 5000
          initialDelaySeconds: 5
          periodSeconds: 5

Docker Compose

Podczas pracy w środowisku platformy Docker można użyć narzędzia Docker Compose do definiowania i uruchamiania aplikacji wielokontenerowych. W poniższym przykładzie pokazano, jak skonfigurować zestaw SDK uwierzytelniania Microsoft Entra ID (sidecar) obok kontenera aplikacji w lokalnym środowisku programistycznym:

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

usługa Azure Kubernetes Service (AKS) z tożsamością zarządzaną

Podczas wdrażania w AKS można użyć tożsamości zarządzanej platformy Azure do uwierzytelniania zestawu SDK uwierzytelniania Microsoft Entra ID (kontenera sidecar) bez konieczności przechowywania poświadczeń w konfiguracji. Najpierw należy włączyć Tożsamość obciążeń Microsoft Entra w klastrze usługi AKS i utworzyć poświadczenia tożsamości federacyjnej dla tożsamości zarządzanej. Następnie skonfiguruj zestaw SDK do używania tożsamości zarządzanej do uwierzytelniania.

Krok 1. Tworzenie tożsamości zarządzanej

Tworzenie tożsamości zarządzanej i przypisywanie jej odpowiednich uprawnień

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

Krok 2. Przypisywanie uprawnień

Przyznaj tożsamości zarządzanej uprawnienia dostępu do podrzędnych interfejsów API:

# 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

Krok 3. Konfiguracja Workload Identity

Utwórz konto usługi z federacją tożsamości obciążenia:

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

Krok 4: Wdrażanie z użyciem Workload Identity

W poniższym przykładzie wdrożenia zestaw MICROSOFT ENTRA ID Auth SDK (przyczepka) jest skonfigurowany do używania Tożsamość obciążeń Microsoft Entra do uwierzytelniania przy użyciu projekcji tokenu opartego na plikach. SignedAssertionFilePath Typ poświadczeń odczytuje token z pliku dostarczonego przez webhook tożsamości obciążenia.

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"

Uwaga: Webhook tożsamości obciążenia automatycznie przekształca token federacyjny na /var/run/secrets/azure/tokens/azure-identity-token lub zmienną środowiskową, gdy zasobnik ma wymaganą etykietę i adnotację konta usługi.

Konfiguracja sieci

Poprawna konfiguracja sieci jest niezbędna do zapewnienia bezpiecznej komunikacji między zestawem SDK uwierzytelniania Microsoft Entra ID (przyczepki) i usługami zewnętrznymi przy jednoczesnym ograniczeniu nieautoryzowanego dostępu. Właściwa konfiguracja zapobiega lukom w zabezpieczeniach i zapewnia niezawodną łączność z Microsoft Entra ID punktami końcowymi. Skorzystaj z poniższych wskazówek, aby skonfigurować dostęp sieciowy dla zestawu SDK w zależności od środowiska wdrażania.

Tylko komunikacja wewnętrzna

Aby skonfigurować pakiet SDK uwierzytelniania Microsoft Entra ID (sidecar) wyłącznie do wewnętrznej komunikacji lokalnej dla zasobnika, ustaw w aplikacji adres URL punktu końcowego tak, aby wskazywał na localhost lub 127.0.0.1, w zależności od środowiska:

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

Zasady sieciowe

Aby jeszcze bardziej ograniczyć dostęp do sieci, rozważ zaimplementowanie zasad sieci platformy Kubernetes w celu ograniczenia ruchu do i z kontenera zestawu SDK:

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

Kontrole kondycji

Zestaw SDK Microsoft Entra ID Auth (kontener pomocniczy) udostępnia punkt końcowy /healthz dla sond żywotności i gotowości, zapewniając, że kontener działa bezpiecznie. Skonfiguruj wdrożenie tak, aby obejmowało następujące sondy:

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

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

Zapotrzebowanie na zasoby

Upewnij się, aby dostosować alokacje zasobów w oparciu o częstotliwość pozyskiwania tokenów, liczbę skonfigurowanych podrzędnych interfejsów API oraz wymagania dotyczące rozmiaru pamięci podręcznej. Zalecane alokacje są następujące:

Zagadnienia dotyczące skalowania

Zestaw SDK uwierzytelniania dla Microsoft Entra ID (sidecar) został zaprojektowany tak, aby skalować się wraz z aplikacją:

1. Projektowanie bezstanowe: każde wystąpienie zestawu SDK przechowuje własną pamięć podręczną tokenów
2. Skalowanie horyzontalne: skalowanie przez dodanie większej liczby podów aplikacyjnych, z których każdy ma własne wystąpienie SDK
3. Ocieplenie pamięci podręcznej: rozważ zaimplementowanie strategii ocieplenia pamięci podręcznej w scenariuszach o dużym natężeniu ruchu

Rozwiązywanie problemów z wdrażaniem

Typowe problemy, które mogą wystąpić, mogą być spowodowane nieprawidłowymi wartościami konfiguracji, łącznością sieciową z Microsoft Entra ID lub brakującymi poświadczeniami lub certyfikatami. Upewnij się, że tożsamość zarządzana lub jednostka usługi ma odpowiednie uprawnienia aplikacji, udzielono zgody administratora (jeśli jest to wymagane) i poprawność przypisań ról.

Poniżej przedstawiono niektóre typowe kroki rozwiązywania problemów, które mogą pomóc rozwiązać problemy z wdrażaniem:

Kontener nie zostanie uruchomiony

Sprawdź dzienniki kontenera:

kubectl logs <pod-name> -c sidecar

Niepowodzenia związane z kontrolą kondycji

Sprawdź, czy pakiet SDK uwierzytelniania Microsoft Entra ID (sidecar) odpowiada:

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

Aby uzyskać bardziej szczegółowe instrukcje dotyczące rozwiązywania problemów, zapoznaj się z przewodnikiem rozwiązywania problemów.

Treści powiązane

• Dokumentacja konfiguracji
• Referencja punktów końcowych
• Najlepsze rozwiązania w zakresie zabezpieczeń
• Weryfikowanie nagłówka autoryzacji