インストールガイド: Microsoft Entra SDK for AgentID を展開する

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

[前提条件]

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

コンテナーイメージ

Microsoft Entra SDK for AgentID は、MCR からコンテナーイメージとして配布されます。

mcr.microsoft.com/entra-sdk/auth-sidecar:<tag>

バージョンタグ

latest - 最新の安定したリリース
<version> - 特定のバージョン (例: 1.0.0)
<version>-preview - プレビューリリース

注

コンテナーイメージは現在プレビュー段階です。 GitHub リリースで最新バージョンのタグを確認します。

デプロイパターン

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

Kubernetes パターン

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

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 AgentID を設定する方法を示します。

version: '3.8'

services:
  app:
    image: myregistry/myapp:latest
    ports:
      - "8080:8080"
    en - sidecar 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

マネージド ID を使用した Azure Kubernetes Service (AKS)

AKS にデプロイするときは、 Azure マネージド ID を使用して、構成に資格情報を格納せずに Microsoft Entra SDK for AgentID を認証できます。まず、AKS クラスターで Azure AD ワークロード 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 AgentID は、ファイルベースのトークンプロジェクションを使用した認証に Azure AD ワークロード 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 AgentID と外部サービス間の安全な通信を確保するには、正しいネットワーク構成が不可欠です。適切な構成により、セキュリティの脆弱性が防止され、Microsoft Entra ID エンドポイントへの信頼性の高い接続が保証されます。デプロイ環境に応じて、SDK のネットワークアクセスを構成するには、次のガイドラインを使用します。

内部通信のみ

内部ポッドローカル通信専用に Microsoft Entra SDK for AgentID を構成するには、環境に応じて、アプリケーションのエンドポイント 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 またはイングレスを介して Microsoft Entra SDK for AgentID を外部に公開しないでください。アプリケーションコンテナーからのみアクセスできる必要があります。

ネットワークポリシー

ネットワークアクセスをさらに制限するには、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 AgentID は、コンテナーが安全に稼働していることを確認するために、稼働チェックと準備チェック用の /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 AgentID は、アプリケーションでスケーリングするように設計されています。

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

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

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

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

コンテナーが起動しない

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

kubectl logs <pod-name> -c sidecar

ヘルスチェックの失敗

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

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

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

次のステップ

設定の構成 - ID 構成を設定する
エンドポイントを確認する - HTTP API を探索する
セキュリティのベストプラクティス - デプロイを強化する
シナリオの選択 - ガイド付き例から始める

フィードバック

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

Last updated on 2025-11-14