Microsoft Entra ID 認證 SDK(側車)是一款即可部署的容器化認證服務,能簡化應用程式的安全令牌取得流程。 本安裝指南提供逐步說明如何在 Kubernetes、Docker 及 Azure 環境中部署 SDK 容器,免除直接將敏感憑證嵌入應用程式碼的需求。
先決條件
- 存取 Microsoft 工件註冊表
- 容器執行階段 (Docker、Kubernetes 或容器服務)
- 在Microsoft Entra 管理中心註冊新的應用程式,僅設定為此組織目錄中的帳戶。 如需詳細資訊 ,請參閱註冊應用程式 。 從應用程式 [概 觀 ] 頁面記錄下列值,以供稍後使用:
- 應用程式 (用戶端) 識別碼
- 目錄(租戶)識別碼
- 應用程式的認證:
- Client Secret 或 Certificate 安全儲存(例如 Azure Key Vault)
- Azure部署:Azure CLI或可透過Azure入口網站
容器映像
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) 的設計可隨您的應用程式一起擴充:
- 無狀態設計:每個 SDK 實例都維護自己的令牌緩存
- 水平擴展:通過添加更多應用程序 Pod(每個 Pod 都有自己的 SDK 實例)進行擴展
- 快取加熱:考慮針對高流量場景實施快取加熱策略
疑難排解部署
你可能遇到的常見問題包括設定值無效、與 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
如需更詳細的故障排除步驟,請參閱故障排除 指南。