Przewodnik instalacji: Wdrażanie zestawu Microsoft Entra SDK dla identyfikatora agenta

Zestaw Microsoft Entra SDK for AgentID to gotowa do wdrożenia konteneryzowana usługa uwierzytelniania, która usprawnia pozyskiwanie bezpiecznego tokenu dla 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 usługi Microsoft Container Registry (MCR)
Środowisko uruchomieniowe kontenera (Docker, Kubernetes lub usługa kontenera)
Zarejestruj nową aplikację w centrum administracyjnym usługi Microsoft Entra, skonfigurowaną tylko dla 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. usługa Azure Key Vault)
W przypadku wdrożeń platformy Azure: interfejs wiersza polecenia platformy Azure lub dostęp do witryny Azure Portal

Obraz kontenera

Microsoft Entra SDK for AgentID jest dystrybuowany jako obraz kontenera w MCR.

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

Tagi wersji

latest - Najnowsza stabilna wersja
<version> - Określone wersje (np. 1.0.0)
<version>-preview — Wersje zapoznawcza

Uwaga / Notatka

Obraz kontenera jest obecnie w wersji zapoznawczej. Sprawdź wydania GitHub pod kątem najnowszych tagów wersji.

Wzorce wdrażania

Zestaw Microsoft Entra SDK for AgentID jest przeznaczony do uruchamiania 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óż zestaw Microsoft Entra SDK for AgentID w tym samym zasobniku co kontener aplikacji, aby zapewnić bezpieczną komunikację lokalną w zasobniku. 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 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"

Wdrażanie rozwiązania Kubernetes

Zobacz Poradnik dotyczący rozwiązania Kubernetes na platformie Azure — przygotowywanie aplikacji dla usługi Azure Kubernetes Service (AKS), jeśli chcesz korzystać z usługi Azure Kubernetes Service. Ten wzorzec używa zasobu wdrożenia do zarządzania aplikacją i zestawem Microsoft Entra SDK dla kontenerów AgentID, co umożliwia 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: /health
            port: 5000
          initialDelaySeconds: 10
          periodSeconds: 10
        readinessProbe:
          httpGet:
            path: /health
            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 Microsoft Entra SDK for AgentID wraz z kontenerem aplikacji w lokalnym środowisku programistycznym:

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

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

Podczas wdrażania w usłudze AKS można użyć tożsamości zarządzanej platformy Azure do uwierzytelniania zestawu Microsoft Entra SDK dla identyfikatora AgentID bez przechowywania poświadczeń w konfiguracji. Najpierw należy włączyć tożsamość obciążenia Azure AD w klastrze AKS i utworzyć poświadczenie tożsamości federacyjnej dla zarządzanej tożsamości. 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 SDK Microsoft Entra dla AgentID został skonfigurowany do uwierzytelniania przy użyciu tożsamości obciążenia Azure AD, z zastosowaniem projekcji tokenów opartych 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

Prawidłowa konfiguracja sieci jest niezbędna do zapewnienia bezpiecznej komunikacji między zestawem Microsoft Entra SDK dla identyfikatora AgentID i usług zewnętrznych przy jednoczesnym ograniczeniu nieautoryzowanego dostępu. Właściwa konfiguracja zapobiega lukom w zabezpieczeniach i zapewnia niezawodną łączność z punktami końcowymi identyfikatora Entra firmy Microsoft. 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 Microsoft Entra dla AgentID do wewnętrznej, pod-lokalnej komunikacji, ustaw w aplikacji adres URL punktu końcowego, 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

Ostrzeżenie

Nigdy nie wystawiaj Microsoft Entra SDK na zewnątrz poprzez LoadBalancer lub Ingress. Powinna być dostępna tylko z kontenera aplikacji.

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 Microsoft Entra SDK dla AgentID uwidacznia /health punkt końcowy dla sond żywotności i gotowości, zapewniając, że kontener działa poprawnie. Skonfiguruj wdrożenie tak, aby obejmowało następujące sondy:

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

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

Wymagania dotyczące zasobów

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:

Profil zasobu	Memory	CPU
Minimum	128Mi	100 m
Recommended	256Mi	250 m
Duży ruch	512Mi	500 m

Zagadnienia dotyczące skalowania

Microsoft Entra SDK dla AgentID został zaprojektowany do skalowania razem z twoją aplikacją.

Projektowanie bezstanowe: każde wystąpienie zestawu SDK przechowuje własną pamięć podręczną tokenów
Skalowanie horyzontalne: skalowanie przez dodanie większej liczby podów aplikacyjnych, z których każdy ma własne wystąpienie SDK
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 identyfikatorem Entra firmy Microsoft 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 sprawdzania kondycji

Sprawdź, czy zestaw Microsoft Entra SDK dla identyfikatora AgentID odpowiada:

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

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

Dalsze kroki

Konfigurowanie ustawień — konfigurowanie konfiguracji tożsamości
Przeglądanie punktów końcowych — eksplorowanie interfejsu API HTTP
Najlepsze rozwiązania w zakresie zabezpieczeń — wzmacnianie zabezpieczeń wdrożenia
Wybieranie scenariusza — rozpocznij od przykładu z przewodnikiem

Sprzężenie zwrotne

Czy ta strona była pomocna?

Last updated on 2025-11-14