インストールガイド: Microsoft Entra SDK for AgentID をデプロイする

Microsoft Entra SDK for Agent ID は、アプリケーションのセキュリティで保護されたトークンの取得を効率化する、すぐにデプロイできるコンテナー化された認証サービスです。このインストールガイドでは、Kubernetes、Docker、および Azure 環境に SDK コンテナーをデプロイする手順について説明します。これにより、アプリケーションコードに機密性の高い資格情報を直接埋め込む必要がなくなります。

[前提条件]

Microsoft Artifact Registryへのアクセス
コンテナーランタイム (Docker、Kubernetes、またはコンテナーサービス)
Microsoft Entra 管理センターで、この組織ディレクトリ内のアカウントのみに構成された新しいアプリを登録します。詳細については、「アプリケーションの登録」を参照してください。後で使用するために、アプリケーション の [概要 ] ページから次の値を記録します。
- アプリケーション (クライアント) ID
- ディレクトリ (テナント) ID
アプリケーションの資格情報:
- セキュリティで保護されたクライアントシークレットまたは証明書 (例: Azure Key Vault)
Azureデプロイの場合: Azure CLIまたはAzure ポータルへのアクセス

コンテナーイメージ

Microsoft Entra SDK for Agent ID は、成果物レジストリからコンテナーイメージとして配布されます

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

デプロイパターン

Microsoft Entra SDK for Agent ID は、アプリケーションと共にコンパニオンコンテナーとして実行するように設計されています。これにより、アプリケーションは HTTP 呼び出しを介してトークンの取得と管理を SDK にオフロードし、アプリケーションコードから機密性の高い資格情報を保持できます。一般的なデプロイパターンを次に示します。特定の環境に合わせて調整する必要があります。

Kubernetes パターン

セキュリティで保護されたポッドローカル通信のために、アプリケーションコンテナーと同じポッドに Microsoft Entra SDK for Agent ID をデプロイします。このパターンにより、認証サービスがアプリと共に実行され、アプリケーションコードから資格情報を分離したまま、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 SDK for Agent ID 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 Services をターゲットにする場合は、Azure の Kubernetes チュートリアル - Azure Kubernetes Service (AKS) 用にアプリケーションを準備するを参照してください。このパターンでは、デプロイリソースを使用して、エージェント ID コンテナー用のアプリケーションと Microsoft Entra SDK を管理し、スケーリングと更新を可能にします。デプロイでは、正常性チェックとリソースの割り当ても処理され、運用環境での安全な操作が保証されます。

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

Docker 環境で作業する場合は、Docker Compose を使用してマルチコンテナーアプリケーションを定義して実行できます。次の例では、Microsoft Entra SDK for Agent ID をローカル開発環境のアプリケーションコンテナーと共に設定する方法を示します。

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) におけるマネージド ID

AKS にデプロイするときは、Azure マネージド ID を使用して、構成に資格情報を格納せずに、Microsoft Entra SDK for Agent ID を認証できます。まず、AKS クラスターでMicrosoft Entra ワークロード ID を有効にし、マネージド ID のフェデレーション ID 資格情報を作成する必要があります。次に、認証にマネージド ID を使用するように SDK を構成します。

手順 1: マネージド ID を作成する

マネージド ID を作成し、適切なアクセス許可を割り当てる

# 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 にアクセスするためのアクセス許可をマネージド ID に付与します。

# 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: ワークロード ID を構成する

ワークロード ID フェデレーションを使用してサービスアカウントを作成します。

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: ワークロード ID を使用してデプロイする

次のデプロイ例では、Microsoft Entra SDK for Agent ID は、ファイルベースのトークンプロジェクションを使用した認証に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"

注: ワークロード ID webhook は、ポッドに必要なラベルとサービスアカウントの注釈がある場合に、フェデレーショントークンを /var/run/secrets/azure/tokens/azure-identity-token または環境変数に自動的に投影します。

ネットワーク構成

承認されていないアクセスを制限しながら、Microsoft Entra SDK for Agent ID と外部サービス間の安全な通信を確保するには、正しいネットワーク構成が不可欠です。適切な構成により、セキュリティの脆弱性が防止され、Microsoft Entra IDエンドポイントへの信頼性の高い接続が保証されます。デプロイ環境に応じて、SDK のネットワークアクセスを構成するには、次のガイドラインを使用します。

内部通信のみ

Microsoft Entra SDK for Agent ID を内部ポッドローカル通信専用に構成するには、環境に応じて、アプリケーションのエンドポイント 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

注意事項

Microsoft Entra SDK for Agent ID を LoadBalancer またはイングレス経由で外部に公開しないでください。アプリケーションコンテナーからのみアクセスできる必要があります。

ネットワークポリシー

ネットワークアクセスをさらに制限するには、SDK コンテナーとの間のトラフィックを制限する Kubernetes ネットワークポリシーの実装を検討してください。

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 SDK for Agent ID は、/health エンドポイントを公開して、ライブネスプローブとレディネスプローブを通じてコンテナーが安全に稼働していることを保証します。次のプローブを含むようにデプロイを構成します。

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

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

リソース要件

推奨されるリソースの割り当ては次のとおりですが、トークンの取得頻度、構成済みのダウンストリーム API の数、キャッシュサイズの要件に基づいて調整してください。

リソースプロファイル	記憶	CPU
最低限	128Mi	100m
推奨	256Mi	250m
高トラフィック	512Mi	500m

スケーリングに関する考慮事項

Microsoft Entra SDK for Agent ID は、アプリケーションでスケーリングするように設計されています。

ステートレス設計: 各 SDK インスタンスは独自のトークンキャッシュを保持します
水平スケーリング: アプリケーションポッドを追加してスケーリングする (それぞれに独自の SDK インスタンスがある)
キャッシュウォーミング: トラフィックの多いシナリオに対するキャッシュウォーミング戦略の実装を検討する

デプロイのトラブルシューティング

一般的な問題は、無効な構成値、Microsoft Entra IDへのネットワーク接続、または資格情報または証明書の不足が原因である可能性があります。マネージド ID またはサービスプリンシパルに、適切なアプリケーションアクセス許可、管理者の同意 (必要な場合)、および正しいロールの割り当てが付与されていることを確認します。

デプロイの問題の解決に役立つ一般的なトラブルシューティング手順を次に示します。

コンテナーが起動しない

コンテナーログを確認します。

kubectl logs <pod-name> -c sidecar

ヘルスチェックの障害

Microsoft Entra SDK for Agent ID が応答することを確認します。

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

トラブルシューティングの詳細な手順については、トラブルシューティングガイドを参照してください。

フィードバック

このページはお役に立ちましたか?

Last updated on 2026-04-19