Průvodce instalací: Nasazení sady Microsoft Entra ID Auth SDK (sidecar)

Microsoft Entra ID Auth SDK (sidecar) je kontejnerizovaná ověřovací služba připravená k nasazení, která zjednodušuje bezpečné získávání tokenů pro vaše aplikace. Tento průvodce instalací obsahuje podrobné pokyny k nasazení kontejneru sady SDK napříč prostředími Kubernetes, Dockeru a Azure, což eliminuje nutnost vkládat citlivé přihlašovací údaje přímo do kódu aplikace.

Požadavky

Přístup k Microsoft Artifact Registry
Modul runtime kontejneru (Docker, Kubernetes nebo služba kontejneru)
Zaregistrujte novou aplikaci v Centrum pro správu Microsoft Entra, která je nakonfigurována pouze pro účty v tomto organizačním adresáři. Další podrobnosti najdete v tématu Registrace aplikace . Na stránce Přehled aplikace si poznamenejte následující hodnoty pro pozdější použití:
- ID aplikace (klienta)
- ID adresáře (klienta)
Přihlašovací údaje pro aplikaci:
- Tajný klíč klienta nebo certifikát uložený bezpečně (např. Azure Key Vault)
Pro nasazení Azure: Azure CLI nebo přístup k portálu Azure

Image kontejneru

Sada Microsoft Entra ID Auth SDK (sidecar) se distribuuje jako image kontejneru z registru artefaktů.

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

Vzory nasazení

Sada Microsoft Entra ID Auth SDK (sidecar) je navržená tak, aby běžela jako doprovodný kontejner společně s vaší aplikací. Tímto můžete přenést získávání a správu tokenů na sadu SDK prostřednictvím volání HTTP, což udržuje citlivé přihlašovací údaje mimo kód vaší aplikace. Níže jsou uvedené běžné vzory nasazení a měly by se přizpůsobit vašemu konkrétnímu prostředí.

Vzorec Kubernetes

Nasaďte sadu SDK Microsoft Entra ID Auth (sidecar) ve stejném podu jako kontejner vaší aplikace, aby byla zajištěna zabezpečená lokální komunikace v rámci podu. Tento model zajišťuje, aby ověřovací služba běžela společně s vaší aplikací a umožňovala rychlé získání tokenu založeného na PROTOKOLU HTTP a přitom byla přihlašovací údaje izolované od kódu aplikace:

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"

Nasazení Kubernetes

Pokud chcete cílit na Službu Azure Kubernetes, přečtěte si kurz Kubernetes na Azure – Jak připravit aplikaci pro Azure Kubernetes Service (AKS). Tento vzor používá prostředek Deployment ke správě kontejnerů aplikace a kontejnerů Microsoft Entra ID Auth SDK (sidecar), což umožňuje škálování a aktualizace. Nasazení také zpracovává kontroly stavu a přidělování prostředků a zajišťuje zabezpečenou operaci v produkčních prostředích:

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

Při práci v prostředí Dockeru můžete pomocí Docker Compose definovat a spouštět vícekontenerové aplikace. Následující příklad ukazuje, jak v místním vývojovém prostředí nakonfigurovat sadu Microsoft Entra ID Auth SDK (sidecar) vedle kontejneru aplikace:

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 service (AKS) se spravovanou identitou

Při nasazování do AKS můžete použít spravovanou identitu Azure k ověření sady Microsoft Entra ID Auth SDK (sidecar) bez uložení přihlašovacích údajů v konfiguraci. Nejprve budete muset povolit ID úloh Microsoft Entra v clusteru AKS a vytvořit přihlašovací údaje federované identity pro vaši spravovanou identitu. Pak sadu SDK nakonfigurujte tak, aby používala spravovanou identitu pro ověřování.

Krok 1: Vytvoření spravované identity

Vytvoření spravované identity a přiřazení odpovídajících oprávnění

# 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: Přiřazení oprávnění

Udělte oprávnění spravované identity pro přístup k podřízeným rozhraním 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: Konfigurace identity úlohy

Vytvoření účtu služby s federací identit úloh:

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: Nasazení s využitím identity úloh

V následujícím příkladu nasazení je sada Microsoft Entra ID Auth SDK (sidecar) nakonfigurovaná tak, aby používala ID úloh Microsoft Entra k ověřování pomocí projekce tokenu založeného na souborech. Typ SignedAssertionFilePath přihlašovacích údajů načte token ze souboru projektovaného webhookem identity úlohy:

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"

Poznámka: Webhook workload identity automaticky provádí projekci federovaného tokenu do /var/run/secrets/azure/tokens/azure-identity-token nebo proměnné prostředí, pokud má pod požadovaný popisek a anotaci účtu služby.

Konfigurace sítě

Správná konfigurace sítě je nezbytná k zajištění zabezpečené komunikace mezi sadou Microsoft Entra ID Auth SDK (sidecar) a externími službami při omezení neoprávněného přístupu. Správná konfigurace zabraňuje ohrožením zabezpečení a zajišťuje spolehlivé připojení ke koncovým bodům Microsoft Entra ID. Následující pokyny použijte ke konfiguraci síťového přístupu pro sadu SDK v závislosti na vašem prostředí nasazení.

Pouze interní komunikace

Pokud chcete nakonfigurovat sadu SDK Microsoft Entra ID Auth (sidecar) pouze pro interní komunikaci v rámci lokálního podu, nastavte v aplikaci adresu URL koncového bodu tak, aby směřovala na localhost nebo 127.0.0.1 v závislosti na vašem prostředí:

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

Upozornění

Nikdy nezpřístupňujte Microsoft Entra ID Auth SDK (sidecar) externě pomocí LoadBalancer nebo Ingress. Měla by být přístupná jenom z kontejneru vaší aplikace.

Zásady sítě

Pokud chcete dále omezit přístup k síti, zvažte implementaci zásad sítě Kubernetes, abyste omezili provoz do kontejneru sady SDK a z kontejneru sady 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

Zdravotní prohlídky

Microsoft Entra ID Auth SDK (sidecar) zpřístupňuje endpoint /health pro sondy živosti a připravenosti, čímž zajišťuje, že kontejner běží bezpečně. Nakonfigurujte nasazení tak, aby zahrnovalo tyto sondy:

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

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

Požadavky na zdroje

Doporučené přidělení prostředků jsou následující, ale ujistěte se, že je potřeba upravit na základě frekvence získání tokenů, počtu nakonfigurovaných podřízených rozhraní API a požadavků na velikost mezipaměti:

Profil zdroje	Memory	CPU
Minimální	128Mi	100 m
Recommended	256Mi	250 m
Vysoký provoz	512Mi	500 m

Důležité informace o škálování

Sada Microsoft Entra ID Auth SDK (sidecar) je navržená pro škálování s vaší aplikací:

Bezstavový návrh: Každá instance sady SDK udržuje vlastní mezipaměť tokenů.
Horizontální škálování: Škálování přidáním dalších podů aplikací (každý s vlastní instancí sady SDK)
Oteplování mezipaměti: Zvažte implementaci strategií oteplování mezipaměti pro scénáře s vysokým provozem

Řešení potíží s nasazením

Běžné problémy, ke kterým může dojít, můžou být způsobené neplatnými hodnotami konfigurace, síťovým připojením k Microsoft Entra ID nebo chybějícími přihlašovacími údaji nebo certifikáty. Ujistěte se, že spravovaná identita nebo instanční objekt mají správná oprávnění aplikace, udělený souhlas správce (v případě potřeby) a správná přiřazení rolí.

Tady je několik běžných kroků pro řešení potíží, které vám můžou pomoct s řešením problémů s nasazením:

Kontejner se nespustí

Zkontrolujte protokoly kontejneru:

kubectl logs <pod-name> -c sidecar

Selhání kontroly zdraví

Ověřte, že Microsoft Entra ID Auth SDK (sidecar) odpovídá:

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

Podrobnější pokyny k řešení potíží najdete v průvodci odstraňováním potíží.

Váš názor

Byla tato stránka užitečná?

Last updated on 2026-06-16