構成リファレンス: Microsoft Entra SDK for AgentID の設定

このガイドでは、コンテナー化された環境でのアプリケーションのトークンの取得と管理を処理するコンテナー化認証サービスである Microsoft Entra SDK for AgentID の構成オプションを提供します。 SDK は、認証ライブラリを直接埋め込む必要なく、Microsoft Entra ID 認証、代理 (OBO) トークン フロー、ダウンストリーム API 呼び出しを管理することで、ID 統合を簡素化します。

このガイドでは Kubernetes デプロイ パターンに焦点を当てていますが、SDK は、Docker、Azure Container Instances、その他のコンテナー オーケストレーション プラットフォームを含む任意のコンテナー化された環境にデプロイできます。

Azure Kubernetes Service (AKS) にデプロイする場合、開発環境を設定する場合、または運用ワークロードを構成する場合、このリファレンスでは、Microsoft Entra ID を使用してアプリケーションをセキュリティで保護するために必要な構成パターン、資格情報の種類、環境変数について説明します。

構成の概要

Microsoft Entra SDK for AgentID は、ASP.NET Core 規則に従って構成ソースを使用して構成されます。 構成値は、次のような複数の方法で指定できます。

• 環境変数 (Kubernetes に推奨)
• Entra ID 構成 - appsettings.json コンテナーにアタッチされたファイル、または yaml ファイルに埋め込まれたファイル。
• コマンドライン引数
• Azure App Configuration または Key Vault (高度なシナリオ向け)

コア Entra ID の設定

Microsoft Entra SDK for AgentID デプロイでは、受信トークンを認証し、ダウンストリーム API のトークンを取得するために、コア Entra ID 設定が必要です。 セキュリティで保護された認証を確保するには、次の YAML 形式の適切なクライアント資格情報 (通常は環境変数) を使用します。

必要な構成

まず、SDK のコア Entra ID 設定を構成して、受信トークンを認証し、ダウンストリーム API のトークンを取得します。

env:
- name: AzureAd__Instance
  value: "https://login.microsoftonline.com/"
- name: AzureAd__TenantId
  value: "<your-tenant-id>"
- name: AzureAd__ClientId
  value: "<your-client-id>"

クライアント資格情報の構成

Microsoft Entra SDK for AgentID では、ダウンストリーム API のトークンを取得するときに、Microsoft Entra ID で認証するための複数のクライアント資格情報の種類がサポートされています。 デプロイ環境とセキュリティ要件に最適な資格情報の種類を選択し、選択した構成がシナリオに適していることを確認します。

資格情報の種類ごとに、さまざまなシナリオが提供されます。

• クライアント シークレット: 開発とテスト用の簡単なセットアップ (運用環境では推奨されません)
• Key Vault 証明書: 証明書管理を一元化した運用環境
• ファイル証明書: 証明書がファイルとしてマウントされている場合 (たとえば、Kubernetes シークレットを使用)
• 証明書ストア: 証明書ストアを含む Windows 環境
• コンテナーのワークロード ID: ファイル ベースのトークン プロジェクションで Azure AD ワークロード ID を使用する AKS に推奨
• VM/App Services のマネージド ID: システムまたはユーザー割り当てマネージド ID を持つ Azure Virtual Machines と App Services (コンテナー用ではありません)

次の YAML 形式で 1 つ以上の資格情報ソースを構成します。

クライアント シークレット

この構成では、サービス間認証にクライアント シークレットを使用して Entra ID 認証を設定します。

- name: AzureAd__ClientCredentials__0__SourceType
  value: "ClientSecret"
- name: AzureAd__ClientCredentials__0__ClientSecret
  value: "<your-client-secret>"

Key Vault からの証明書

この構成では、Azure Key Vault に格納されている証明書を使用して Entra 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: "<certificate-name>"

ファイルからの証明書

この構成では、ファイルとして格納されている証明書を使用して Entra ID 認証を設定します。

- name: AzureAd__ClientCredentials__0__SourceType
  value: "Path"
- name: AzureAd__ClientCredentials__0__CertificateDiskPath
  value: "/path/to/certificate.pfx"
- name: AzureAd__ClientCredentials__0__CertificatePassword
  value: "<certificate-password>"

ストアからの証明書

この構成では、ローカル証明書ストアの証明書を使用して Entra ID 認証を設定します。

- name: AzureAd__ClientCredentials__0__SourceType
  value: "StoreWithThumbprint"
- name: AzureAd__ClientCredentials__0__CertificateStorePath
  value: "CurrentUser/My"
- name: AzureAd__ClientCredentials__0__CertificateThumbprint
  value: "<thumbprint>"

コンテナーのワークロード ID (AKS に推奨)

この構成では、コンテナー化されたデプロイ (AKS) に Azure AD ワークロード ID を使用して Entra ID 認証を設定します。 これは、ファイル ベースのトークン プロジェクションを使用するコンテナー ベースのシナリオに推奨されるアプローチです。

- name: AzureAd__ClientCredentials__0__SourceType
  value: "SignedAssertionFilePath"

注: トークン ファイル パス /var/run/secrets/azure/tokens/azure-identity-token または環境変数は、ポッドがサービス アカウントの注釈とポッド ラベルで適切に構成されている場合に、Azure Workload Identity webhook によって自動的に投影されます。 完全なセットアップ手順については 、マネージド ID の使用 に関する記事を参照してください。

VM と App Services のマネージド ID

仮想マシンまたは App Services (コンテナーではなく) での従来の Azure マネージド ID シナリオでは、次の SignedAssertionFromManagedIdentity使用します。

- name: AzureAd__ClientCredentials__0__SourceType
  value: "SignedAssertionFromManagedIdentity"
- name: AzureAd__ClientCredentials__0__ManagedIdentityClientId
  value: "<managed-identity-client-id>"

重要: コンテナー化された環境 (Kubernetes、AKS、Docker) には SignedAssertionFromManagedIdentity を使用しないでください。 AKS の場合は、上記のように SignedAssertionFilePath を使用します。 Kubernetes と Docker の場合は、クライアント証明書を使用します。 詳細については、以下を参照してください。 https://aka.ms/idweb/client-credentials

その他のリソース

すべての資格情報構成オプションとその使用方法の詳細については、microsoft-identity-abstractions-for-dotnet リポジトリの CredentialDescription 仕様 を参照してください。

資格情報の優先順位

優先順位ベースの選択を使用して複数の資格情報を構成します。

# First priority - Key Vault certificate
- name: AzureAd__ClientCredentials__0__SourceType
  value: "KeyVault"
- name: AzureAd__ClientCredentials__0__KeyVaultUrl
  value: "https://prod-keyvault.vault.azure.net"
- name: AzureAd__ClientCredentials__0__KeyVaultCertificateName
  value: "prod-cert"

# Second priority - Client secret (fallback)
- name: AzureAd__ClientCredentials__1__SourceType
  value: "ClientSecret"
- name: AzureAd__ClientCredentials__1__ClientSecret
  valueFrom:
    secretKeyRef:
      name: app-secrets
      key: client-secret

Microsoft Entra SDK for AgentID は、数値順 (0、1、2 など) で資格情報を評価し、正常に認証された最初の資格情報を使用します。

ダウンストリーム API の構成

アプリケーションが代理 (OBO) トークン フローを使用して呼び出す必要があるダウンストリーム API を構成します。 Microsoft Entra SDK for AgentID は、トークンの取得を管理し、これらの API 呼び出しの認証ヘッダーを提供します。 各ダウンストリーム API には、トークンの取得と HTTP 要求の処理に一意の構成名と特定のパラメーターが必要です。

各ダウンストリーム API は、そのベース URL、必要なスコープ、および省略可能なパラメーターを使用して定義します。 SDK は、受信ユーザー トークンを使用してトークンの取得を自動的に処理し、アプリケーションの API 呼び出しに適切な承認ヘッダーを提供します。

- name: DownstreamApis__Graph__BaseUrl
  value: "https://graph.microsoft.com/v1.0"
- name: DownstreamApis__Graph__Scopes
  value: "User.Read Mail.Read"
- name: DownstreamApis__Graph__RelativePath
  value: "/me"

- name: DownstreamApis__MyApi__BaseUrl
  value: "https://api.contoso.com"
- name: DownstreamApis__MyApi__Scopes
  value: "api://myapi/.default"

トークン取得オプション

トークン取得の動作を微調整します。

- name: DownstreamApis__Graph__AcquireTokenOptions__Tenant
  value: "<specific-tenant-id>"

- name: DownstreamApis__Graph__AcquireTokenOptions__AuthenticationScheme
  value: "Bearer"

- name: DownstreamApis__Graph__AcquireTokenOptions__CorrelationId
  value: "<correlation-id>"

署名済み HTTP 要求 (SHR) の構成

セキュリティ強化のために署名済み HTTP 要求を有効にします。

- name: DownstreamApis__SecureApi__AcquireTokenOptions__PopPublicKey
  value: "<base64-encoded-public-key>"

- name: DownstreamApis__SecureApi__AcquireTokenOptions__PopClaims
  value: '{"custom_claim": "value"}'

ログ記録の構成

ログ 記録レベルを構成します。

- name: Logging__LogLevel__Default
  value: "Information"
- name: Logging__LogLevel__Microsoft.Identity.Web
  value: "Debug"
- name: Logging__LogLevel__Microsoft.AspNetCore
  value: "Warning"

ASP.NET コア設定

- name: ASPNETCORE_ENVIRONMENT
  value: "Production"
- name: ASPNETCORE_URLS
  value: "http://+:5000"

Per-Request 構成のオーバーライド

すべてのトークン取得エンドポイントは、構成をオーバーライドするクエリ パラメーターを受け入れます。

# Override scopes
GET /AuthorizationHeader/Graph?optionsOverride.Scopes=User.Read&optionsOverride.Scopes=Mail.Read

# Request app token instead of OBO
GET /AuthorizationHeader/Graph?optionsOverride.RequestAppToken=true

GET /AuthorizationHeaderUnauthenticated/Graph?optionsOverride.RequestAppToken=true

# Override tenant
GET /AuthorizationHeader/Graph?optionsOverride.AcquireTokenOptions.Tenant=<tenant-id>

# Override relative path
GET /DownstreamApi/Graph?optionsOverride.RelativePath=me/messages

# Enable SHR for this request
GET /AuthorizationHeader/Graph?optionsOverride.AcquireTokenOptions.PopPublicKey=<base64-key>

エージェント ID のオーバーライド

要求時にエージェント ID を指定します。

# Autonomous agent
GET /AuthorizationHeader/Graph?AgentIdentity=<agent-client-id>

# Autonomous agent with specific agent user identity (by username)
GET /AuthorizationHeader/Graph?AgentIdentity=<agent-client-id>&AgentUsername=user@contoso.com

# Autonomous agent with specific agent user identity (by object ID)
GET /AuthorizationHeader/Graph?AgentIdentity=<agent-client-id>&AgentUserId=<user-object-id>

重要な規則:

• AgentUsername と AgentUserId が必要 AgentIdentity
• AgentUsername と AgentUserId は相互に排他的です

詳細なセマンティクスについては 、「エージェント ID」を 参照してください。

完全な構成例

次に、構成とシークレットを適切に分離して SDK をデプロイする方法を示す実稼働対応の例を示します。 この例では、機密性の低い設定に Kubernetes ConfigMaps を使用して複数のダウンストリーム API を構成し、資格情報をシークレットに安全に格納し、環境固有の構成を適用してセキュリティで保護されたデプロイを行う方法を示します。

このパターンは、構成データを機密性の高い資格情報から分離し、セキュリティを維持しながらさまざまな環境を効果的に管理できるようにすることで、Kubernetes のベスト プラクティスに従います。

Kubernetes ConfigMap

ConfigMap には、Entra ID 設定、ダウンストリーム API、ログ レベルなど、SDK の機密性の高い構成設定が格納されます。

apiVersion: v1
kind: ConfigMap
metadata:
  name: sidecar-config
data:
  ASPNETCORE_ENVIRONMENT: "Production"
  ASPNETCORE_URLS: "http://+:5000"
  
  AzureAd__Instance: "https://login.microsoftonline.com/"
  AzureAd__TenantId: "common"
  AzureAd__ClientId: "your-app-client-id"
  AzureAd__Scopes: "access_as_user"
  
  DownstreamApis__Graph__BaseUrl: "https://graph.microsoft.com/v1.0"
  DownstreamApis__Graph__Scopes: "User.Read Mail.Read"
  
  DownstreamApis__MyApi__BaseUrl: "https://api.contoso.com"
  DownstreamApis__MyApi__Scopes: "api://myapi/.default"
  
  Logging__LogLevel__Default: "Information"
  Logging__LogLevel__Microsoft.Identity.Web: "Debug"

Kubernetes シークレット

シークレットには、クライアント シークレットなどの機密性の高い資格情報が ConfigMap とは別に格納されます。

apiVersion: v1
kind: Secret
metadata:
  name: sidecar-secrets
type: Opaque
stringData:
  AzureAd__ClientCredentials__0__ClientSecret: "your-client-secret"

ConfigMap とシークレットを使用したデプロイ

Deployment によって ConfigMap とシークレットの両方が SDK コンテナーにマウントされ、構成と資格情報が適切に分離されます。

apiVersion: apps/v1
kind: Deployment
metadata:
  name: myapp
spec:
  template:
    spec:
      containers:
      - name: sidecar
        image: mcr.microsoft.com/entra-sdk/auth-sidecar:1.0.0
        envFrom:
        - configMapRef:
            name: sidecar-config
        - secretRef:
            name: sidecar-secrets

環境固有の構成

環境固有の設定を構成して、デプロイ環境のセキュリティ、ログ記録、テナントの分離を調整します。 開発効率、ステージング検証、運用のセキュリティ要件のバランスを取るために、環境ごとに異なる構成アプローチが必要です。

発達

- name: ASPNETCORE_ENVIRONMENT
  value: "Development"
- name: Logging__LogLevel__Default
  value: "Debug"
- name: AzureAd__TenantId
  value: "<dev-tenant-id>"

Staging

- name: ASPNETCORE_ENVIRONMENT
  value: "Staging"
- name: Logging__LogLevel__Default
  value: "Information"
- name: AzureAd__TenantId
  value: "<staging-tenant-id>"

生産

- name: ASPNETCORE_ENVIRONMENT
  value: "Production"
- name: Logging__LogLevel__Default
  value: "Warning"
- name: Logging__LogLevel__Microsoft.Identity.Web
  value: "Information"
- name: AzureAd__TenantId
  value: "<prod-tenant-id>"
- name: ApplicationInsights__ConnectionString
  value: "<app-insights-connection>"

Validation

Microsoft Entra SDK for AgentID は起動時に構成を検証し、次のエラーをログに記録します。

• 必要な設定がない (TenantId、 ClientId)
• 無効な資格情報の構成
• 形式が正しくないダウンストリーム API 定義
• 無効な URL またはスコープ形式

検証メッセージのコンテナー ログを確認します。

kubectl logs <pod-name> -c sidecar

ベスト プラクティス

1. 資格情報にシークレットを使用する: クライアント シークレットと証明書を Kubernetes シークレットまたは Azure Key Vault に格納します。 関連項目 https://aka.ms/msidweb/client-credentials
2. 環境ごとに個別の構成: ConfigMaps を使用して環境固有の設定を管理する
3. 適切なログ記録を有効にする: 開発中はデバッグ ログを使用し、運用環境では情報/警告を使用する
4. 正常性チェックの構成: 正常性チェック エンドポイントが正しく構成されていることを確認する
5. コンテナーにワークロード ID を使用する: コンテナー化されたデプロイ (AKS) の場合、セキュリティ強化のためにクライアント シークレットよりも SignedAssertionFilePath を使用した Azure AD ワークロード ID を優先します
6. VM/App Services にマネージド ID を使用する: Azure VM と App Services の場合は、システムまたはユーザー割り当てマネージド ID を使用します
7. デプロイ時に検証する: 運用環境のデプロイ前にステージングで構成をテストする

こちらもご覧ください

• エージェント ID
• エンドポイント リファレンス
• セキュリティのベスト プラクティス
• Troubleshooting