Installationsguide: Distribuera Microsoft Entra ID Auth SDK (sidecar)

Microsoft Entra ID Auth SDK (sidecar) är en distributionsklar, containerbaserad autentiseringstjänst som effektiviserar säker hämtning av token för dina applikationer. Den här installationsguiden innehåller stegvisa instruktioner för att distribuera SDK-containern i Kubernetes-, Docker- och Azure-miljöer, vilket eliminerar behovet av att bädda in känsliga autentiseringsuppgifter direkt i programkoden.

Förutsättningar

• Åtkomst till Microsoft Artifact Registry
• Container-runtime (Docker, Kubernetes eller containertjänst)
• Registrera en ny app i Microsoft Entra administrationscenter som konfigurerats för Konton endast i den här organisationskatalogen. Mer information finns i Registrera ett program . Registrera följande värden från programöversiktssidan för senare användning:
  • App-ID (klient-ID)
  • Katalog-ID (hyresgäst)
• Autentiseringsuppgifter för programmet:
  • Klienthemlighet eller certifikat som lagras på ett säkert sätt (t.ex. Azure Key Vault)
• För Azure distributioner: Azure CLI eller åtkomst till portalen Azure

Containeravbildning

Microsoft Entra ID Auth SDK (sidovagn) distribueras som en containeravbildning från artefaktregistret

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

Distributionsmönster

Microsoft Entra ID Auth SDK (sidecar) är utformat för att köras som en kompletterande container vid sidan av din applikation. På så sätt kan ditt program avlasta tokenförvärv och hantering till SDK via HTTP-anrop och hålla känsliga autentiseringsuppgifter borta från programkoden. Följande är vanliga distributionsmönster och bör anpassas till din specifika miljö.

Kubernetes-mönster

Driftsätt Microsoft Entra ID Auth SDK (sidecar) i samma pod som din programcontainer för säker kommunikation lokalt inom poden. Det här mönstret säkerställer att autentiseringstjänsten körs tillsammans med din app, vilket möjliggör snabbt HTTP-baserat tokenförvärv samtidigt som autentiseringsuppgifterna hålls isolerade från programkoden:

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"

Kubernetes-distribution

Se självstudien Kubernetes i Azure – Förbereda ett program för Azure Kubernetes Service (AKS) om du vill rikta in dig på Azure Kubernetes Services. Det här mönstret använder en distributionsresurs för att hantera program- och Microsoft Entra ID Auth SDK-containrar (sidovagn), vilket möjliggör skalning och uppdateringar. Implementeringen hanterar även hälsokontroller och resursallokering, vilket säkerställer säker drift i produktionsmiljöer.

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

När du arbetar i en Docker-miljö kan du använda Docker Compose för att definiera och köra program med flera containrar. I följande exempel visas hur du konfigurerar Microsoft Entra ID Auth SDK (sidovagn) tillsammans med programcontainern i en lokal utvecklingsmiljö:

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-tjänsten (AKS) med hanterad identitet

När du distribuerar till AKS kan du använda Azure Managed Identity för att autentisera Microsoft Entra ID Auth SDK (sidecar) utan att lagra autentiseringsuppgifter i konfigurationen. Först måste du aktivera Microsoft Entra Workload ID i ditt AKS-kluster och skapa en federerad identitetsautentisering för din hanterade identitet. Konfigurera sedan SDK för att använda den hanterade identiteten för autentisering.

Steg 1: Skapa hanterad identitet

Skapa en hanterad identitet och tilldela den lämpliga behörigheter

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

Steg 2: Tilldela behörigheter

Ge den hanterade identiteten behörighet att komma åt underordnade API:er:

# 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

Steg 3: Konfigurera arbetsbelastningsidentitet

Skapa ett tjänstkonto med identitetsfederation för arbetsbelastning:

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

Steg 4: Distribuera med Workload Identity

I följande distributionsexempel är Microsoft Entra ID Auth SDK (sidovagn) konfigurerad för att använda Microsoft Entra Workload ID för autentisering med hjälp av filbaserad tokenprojektion. Typ SignedAssertionFilePath av autentiseringsuppgifter läser token från filen som projiceras av webhooken för arbetsbelastningsidentitet:

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"

Obs! Webhooken för arbetsbelastningsidentitet projicerar automatiskt den federerade token till /var/run/secrets/azure/tokens/azure-identity-token eller en miljövariabel när podden har den nödvändiga etiketten och tjänstkontoannotationen.

Konfiguration av nätverk

Rätt nätverkskonfiguration är viktigt för att säkerställa säker kommunikation mellan Microsoft Entra ID Auth SDK (sidovagn) och externa tjänster samtidigt som obehörig åtkomst begränsas. Korrekt konfiguration förhindrar säkerhetsrisker och säkerställer tillförlitlig anslutning till Microsoft Entra ID slutpunkter. Använd följande riktlinjer för att konfigurera nätverksåtkomst för SDK beroende på din distributionsmiljö.

Endast intern kommunikation

Om du vill konfigurera Microsoft Entra ID Auth SDK (sidecar) endast för intern pod-lokal kommunikation anger du slutpunkts-URL:en i programmet så att den pekar mot localhost eller 127.0.0.1, beroende på din miljö:

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

Nätverksprinciper

Om du vill begränsa nätverksåtkomsten ytterligare kan du överväga att implementera Kubernetes-nätverksprinciper för att begränsa trafiken till och från SDK-containern:

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

Hälsokontroller

Microsoft Entra ID Auth SDK (sidecar) tillhandahåller en /health ändpunkt för liveness- och readiness-avsökningar, vilket säkerställer att containern körs säkert. Konfigurera distributionen för att inkludera dessa sonder.

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

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

Resurskrav

De rekommenderade resursallokeringarna är följande, men se till att justera baserat på hämtningsfrekvens för token, antal konfigurerade underordnade API:er och krav på cachestorlek:

Att tänka på vid skalning

Microsoft Entra ID Auth SDK (sidecar) är utformat för att skala med din applikation:

1. Tillståndslös design: Varje SDK-instans har en egen cache för tokenar
2. Horisontell skalning: Skala genom att lägga till fler programpoddar (var och en med sin egen SDK-instans)
3. Cacheuppvärmning: Överväg att implementera strategier för cacheuppvärmning för scenarier med hög trafik

Felsöka utveckling

Vanliga problem som kan uppstå kan bero på ogiltiga konfigurationsvärden, nätverksanslutning till Microsoft Entra ID eller saknade autentiseringsuppgifter eller certifikat. Kontrollera att den hanterade identiteten eller tjänstens huvudprincip har rätt applikationsbehörigheter, administratörsmedgivande beviljat (om det behövs) och rätt rolltilldelningar.

Följande är några vanliga felsökningssteg som kan hjälpa dig att lösa distributionsproblem:

Containern startar inte

Kontrollera containerloggarna:

kubectl logs <pod-name> -c sidecar

Misslyckad hälsokontroll

Kontrollera att Microsoft Entra ID Auth SDK (sidecar) svarar:

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

Mer detaljerade anvisningar om felsökning finns i felsökningsguiden.

Relaterat innehåll

• Konfigurationsreferens
• Referens för slutpunkter
• Metodtips för säkerhet
• Verifiera auktoriseringshuvud