安裝指南:部署 Microsoft Entra ID 認證 SDK(側車)

Microsoft Entra ID 認證 SDK(側車)是一款即可部署的容器化認證服務,能簡化應用程式的安全令牌取得流程。 本安裝指南提供逐步說明如何在 Kubernetes、Docker 及 Azure 環境中部署 SDK 容器,免除直接將敏感憑證嵌入應用程式碼的需求。

先決條件

容器映像

Microsoft Entra ID 認證 SDK(側車)以容器映像形式從工件登錄檔發佈

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

Note

入站 SHR PoP 驗證需使用側車版本或更新版本 1.1.2-preview 。

部署模式

Microsoft Entra ID 驗證 SDK(sidecar)旨在作為伴隨容器,與您的應用程式一同執行。 這可讓您的應用程式透過 HTTP 呼叫將權杖取得和管理卸載至 SDK,並將敏感認證排除在應用程式程式碼之外。 以下是常見的部署模式,應根據您的特定環境進行調整。

Kubernetes 模式

將 Microsoft Entra ID Auth SDK(Sidecar)部署在與您的應用程式容器位於同一個 Pod 中,以確保 Pod 內本機通訊的安全性。 此模式可確保驗證服務與您的應用程式一起執行,實現基於 HTTP 的快速權杖獲取,同時將認證與您的應用程式代碼隔離:

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 部署

如果你想針對 Azure Kubernetes Service,請參考 Kubernetes on Azure 教學:準備應用程式以支援 Azure Kubernetes Service (AKS)。 此模式使用 Deployment 資源來管理應用程式容器和 Microsoft Entra ID Auth SDK(sidecar)容器,從而支援擴充與更新。 部署也會處理健康情況檢查和資源分配,確保生產環境中的安全運作:

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

在Docker環境中工作時,可以使用Docker Compose來定義和執行多容器應用程式。 以下範例示範如何在本機開發環境中,將 Microsoft Entra ID Auth SDK(Sidecar)與您的應用程式容器一併設定:

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 服務(AKS)與受管理的身份驗證

部署到 AKS 時,你可以使用 Azure Managed Identity 來驗證 Microsoft Entra ID Auth SDK(側車),而不必在設定中儲存憑證。 首先你需要在 AKS 叢集啟用 Microsoft Entra 工作負載 ID,並為你的管理身份建立聯邦身份憑證。 然後設定 SDK 以使用受控識別進行驗證。

步驟 1:建立受控識別

建立受控識別並指派適當的許可權

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

步驟 2:指派權限

授與受控識別存取下游 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

步驟 3:設定工作負載身分識別

創建工作負載身分識別聯合服務帳戶:

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

步驟 4:使用工作負載身分識別進行部署

在以下部署範例中,Microsoft Entra ID Auth SDK(側車)被設定為使用 Microsoft Entra 工作負載 ID 進行基於檔案的憑證投影驗證。 SignedAssertionFilePath認證類型會從工作負載身分識別 Webhook 投影的檔案中讀取權杖:

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"

附註:當 Pod 具有必要的標籤和服務帳戶註解時,工作負載身分 Webhook 會自動將聯合權杖映射到 /var/run/secrets/azure/tokens/azure-identity-token 或環境變數。

網路設定

正確的網路設定對於確保 Microsoft Entra ID Auth SDK(側車)與外部服務之間安全通訊,同時限制未經授權存取至關重要。 正確的設定能防止安全漏洞,並確保與 Microsoft Entra ID 端點的可靠連線。 根據您的部署環境,請使用下列指導方針來設定 SDK 的網路存取。

僅限內部溝通

若要將 Microsoft Entra ID Auth SDK(側車)設定為僅供 Pod 內部本機通訊使用,請將應用程式中的端點 URL 設為指向 localhost 或 127.0.0.1,取決於您的環境:

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

謹慎

切勿透過 LoadBalancer 或 Ingress 外部公開 Microsoft Entra ID Auth SDK(sidecar)。 它應該只能從您的應用程式容器存取。

網路原則

若要進一步限制網路存取,請考慮實作 Kubernetes 網路原則,以限制進出 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

健康檢查

Microsoft Entra ID 驗證 SDK(sidecar)會公開一個/healthz端點,用於存活與就緒探測,確保容器安全地執行。 設定部署以包含以下探針:

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

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

資源需求

建議的資源分配如下,但請確保根據令牌獲取頻率、配置的下游 API 數量和快取大小需求進行調整:

資源概況 Memory CPU
最低 128英里 100公尺
推薦 256英里 250公尺
高流量 512兆字節 500m

調整考量

Microsoft Entra ID 認證 SDK (sidecar) 的設計可隨您的應用程式一起擴充:

  1. 無狀態設計:每個 SDK 實例都維護自己的令牌緩存
  2. 水平擴展:通過添加更多應用程序 Pod(每個 Pod 都有自己的 SDK 實例)進行擴展
  3. 快取加熱:考慮針對高流量場景實施快取加熱策略

疑難排解部署

你可能遇到的常見問題包括設定值無效、與 Microsoft Entra ID 的網路連線問題、或是缺少認證資訊或憑證。 請確定受控識別或服務主體具有正確的應用程式許可權、授與的系統管理員同意 (如有需要) ,以及正確的角色指派。

以下是一些常見的疑難排解步驟,可協助解決部署問題:

貨櫃無法啟動

檢查容器日誌:

kubectl logs <pod-name> -c sidecar

健康檢查失敗

確認 Microsoft Entra ID Auth SDK(側車)有回應:

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

如需更詳細的故障排除步驟,請參閱故障排除 指南。