次の方法で共有

Microsoft Entra SDK for AgentID についてよく寄せられる質問

一般的な質問

Microsoft Entra SDK for AgentID とは

Microsoft Entra SDK for AgentID は、トークンの取得、検証、および安全なダウンストリーム API 呼び出しを処理するコンテナー化された Web サービスです。 アプリケーションと共にコンパニオン コンテナーとして実行されるため、ID ロジックを専用サービスにオフロードできます。 SDK で ID 操作を一元化することで、各サービスに複雑なトークン管理ロジックを埋め込む必要がなくなり、コードの重複と潜在的なセキュリティの脆弱性が軽減されます。

Microsoft.Identity.Web の代わりに Microsoft Entra SDK for AgentID を使用する理由

特徴 Microsoft.Identity.Web Microsoft Entra SDK for AgentID
言語サポート C# / .NET のみ 任意の言語 (HTTP)
Deployment インプロセス ライブラリ 個別のコンテナー
トークンの取得 ✅ ダイレクト MSAL.NET ✅ HTTP API 経由
トークン キャッシュ ✅ メモリ内、 ✅ 分散 ✅ メモリ内、 ❌分散
OBO フロー ✅ ネイティブ サポート ✅ HTTP エンドポイント経由
クライアント資格情報 ✅ ネイティブ サポート ✅ HTTP エンドポイント経由
マネージド ID ✅ 直接サポート ✅ 直接サポート
エージェント ID ✅ 拡張機能を使用する ✅ クエリ パラメーター
トークンの検証 ✅ ミドルウェア ✅ /エンドポイントを検証する
ダウンストリーム API ✅ IDownstreamApi ✅ /DownstreamApi エンドポイント
Microsoft Graph ✅ Graph SDK の統合 ⚠️ DownstreamApi 経由
パフォーマンス ⚡ インプロセス (最速) 🔄 HTTP オーバーヘッド
Configuration appsettings.json とコード appsettings.json 環境変数と環境変数
デバッグ ✅ 標準の .NET デバッグ ⚠️ コンテナーのデバッグ
ホット リロード ✅ .NET ホット リロード ❌ コンテナーの再起動
パッケージの更新 📦 NuGet パッケージ 🐳 コンテナー イメージ
ライセンス MIT MIT

詳細なガイダンスについては、 比較ガイド を参照してください。

Microsoft Entra SDK for AgentID は運用環境に対応していますか?

はい。SDK は運用環境の準備ができています。 最新のリリースの状態と運用環境の準備のガイドラインについては、 GitHub リリースを参照してください。

コンテナー イメージは使用できますか?

はい - 使用可能なイメージとバージョン タグについては 、インストール ガイド を参照してください。

Kubernetes の外部で SDK を実行できますか?

はい - Docker Compose またはその他のコンテナー環境 (Docker Compose、Azure Container Instances、AWS ECS/Fargate、スタンドアロン Docker) で SDK を実行する手順については、 インストール ガイド を参照してください。

SDK はどのネットワーク ポートを使用しますか?

既定のポート: 5000 (構成可能)

SDK にはアプリケーション コンテナーからのみアクセスでき、外部に公開されることはありません。

デプロイメント

デプロイ オプション、リソース要件、Docker Compose や Kubernetes などのコンテナー プラットフォームとの統合について説明します。

リソースの要件は何ですか?

はい - リソース要件については 、インストール ガイド を参照してください。

Docker Compose で SDK を使用できますか?

はい - Docker Compose の例の インストール ガイド を参照してください。

マネージド ID を使用して AKS にデプロイする方法

はい - Azure Kubernetes Service (AKS) とマネージド ID セクションのインストール ガイドに従います。

コンフィギュレーション

デプロイ要件に合わせて、資格情報、ダウンストリーム API、要求オーバーライドなどの SDK 設定を構成します。

構成参照は利用できますか?

はい - 詳細な構成オプションについては、 構成リファレンスを参照 してください。

クライアント シークレットまたは証明書を使用する必要がありますか?

クライアント シークレットよりも証明書を優先する:

  • セキュリティの強化
  • 回転が簡単
  • Microsoft が推奨

ベスト: Azure でマネージド ID を使用する (資格情報は必要ありません)

ガイダンスについては、「 セキュリティのベスト プラクティス 」を参照してください。

複数のダウンストリーム API を構成できますか?

Yes. それぞれに独自のセクションを構成します。

DownstreamApis__Graph__BaseUrl: "https://graph.microsoft.com/v1.0"
DownstreamApis__Graph__Scopes: "User.Read"

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

要求ごとに構成をオーバーライドする方法

エンドポイントでクエリ パラメーターを使用する:

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

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

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

すべてのオプションについては、「 構成リファレンス」を参照 してください。

エージェント ID

エージェント ID を使用すると、エージェント アプリケーションが適切なコンテキスト分離とスコープを使用して、自律的に、またはユーザーの代わりに動作できるシナリオが可能になります。

エージェント ID とは

エージェント ID を使用すると、エージェント アプリケーションが次のいずれかの動作をするシナリオが有効になります。

  • 自律的 - 独自のアプリケーション コンテキストで
  • 対話型 - 呼び出したユーザーに代わって

包括的なドキュメントについては 、エージェント ID を参照してください。

自律エージェント モードを使用する必要があるタイミング

自律エージェント モードは、次の場合に使用します。

  • ユーザー コンテキストを使用しないバッチ処理
  • バックグラウンド タスク
  • システム間操作
  • スケジュールされたジョブ

例:

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

対話型エージェント モードを使用する必要があるタイミング

次の場合は、委任されたエージェント モードを使用します。

  • 対話型エージェント アプリケーション
  • ユーザーに代わって動作する AI アシスタント
  • ユーザー スコープの自動化
  • カスタマイズされたワークフロー

例:

GET /AuthorizationHeader/Graph?AgentIdentity=<agent-client-id>&AgentUsername=user@contoso.com

AgentIdentity なしで AgentUsername を使用できないのはなぜですか?

AgentUsername は、エージェントが代理で操作するユーザーを指定する修飾子です。 使用するエージェント コンテキストを指定するには、 AgentIdentity が必要です。 AgentIdentityしないと、パラメーターには意味がありません。

AgentUsername と AgentUserId が相互に排他的なのはなぜですか?

同じユーザーを識別するには、次の 2 つの方法があります。

  • AgentUsername - ユーザー プリンシパル名 (UPN)
  • AgentUserId - オブジェクト ID (OID)

両方を許可すると、あいまいさが生じします。 シナリオに合ったものを選択します。

  • ユーザーの UPN がある場合に AgentUsername を使用する
  • ユーザーのオブジェクト ID がある場合に AgentUserId を使用する

API の使用状況

SDK では、認証されたフローと認証されていないフローの両方をサポートする、トークンの取得、検証、およびダウンストリーム API 呼び出し用の HTTP エンドポイントがいくつか公開されています。

SDK で公開されているエンドポイントは何ですか?

  • /Validate - トークンを検証し、要求を返す
  • /AuthorizationHeader/{serviceName} - トークンを使用して承認ヘッダーを取得する
  • /AuthorizationHeaderUnauthenticated/{serviceName} - 受信ユーザー トークンなしでトークンを取得する
  • /DownstreamApi/{serviceName} - ダウンストリーム API を直接呼び出す
  • /DownstreamApiUnauthenticated/{serviceName} - 受信ユーザー トークンを使用せずにダウンストリーム API を呼び出す
  • /healthz - 正常性プローブ

詳細については、「 エンドポイント リファレンス」 を参照してください。

認証されたエンドポイントと認証されていないエンドポイントの違いは何ですか?

認証済み: Authorization ヘッダーにベアラー トークンを要求する (OBO フローの場合) 認証されていない: 受信トークンを検証しない (アプリ専用またはエージェントのシナリオの場合)

ユーザー トークンを検証する方法

GET /Validate
Authorization: Bearer <user-token>

応答には、トークンからのすべての要求が含まれます。

ダウンストリーム API のアクセス トークンを取得するにはどうすればよいですか?

GET /AuthorizationHeader/Graph
Authorization: Bearer <user-token>

応答には、ダウンストリーム API で使用できる承認ヘッダーが含まれます。

要求ごとに HTTP メソッドまたはパスをオーバーライドできますか?

はい。クエリ パラメーターを使用します。

# Override method
GET /DownstreamApi/Graph?optionsOverride.HttpMethod=POST

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

トークン キャッシュ

SDK は、パフォーマンスを最適化し、冗長なトークン取得要求を減らすために、トークンをメモリに自動的にキャッシュします。

SDK はトークンをキャッシュしますか?

はい - SDK は既定でメモリにトークンをキャッシュします。

トークンはどのくらいの期間キャッシュされますか?

トークンは有効期限が近くまでキャッシュされ、自動的に更新されます。 正確な期間は、トークンの有効期間によって異なります (通常、Entra ID トークンの場合は 1 時間)。

キャッシュを無効にすることはできますか?

トークン キャッシュは自動で最適化されています。 現在、無効にするオプションはありません。

トークン キャッシュは SDK インスタンス間で共有されますか?

いいえ - 各 SDK インスタンスは、独自のメモリ内キャッシュを維持します。 高可用性デプロイでは、各ポッドには独立したキャッシュがあります。

セキュリティ

セキュリティで保護された SDK のデプロイは、マネージド ID の使用、ネットワークの分離、適切な資格情報の処理など、Microsoft Entra ID とデータ保護のベスト プラクティスに従います。

SDK を実行しても安全ですか?

はい - セキュリティのベスト プラクティス については、セキュリティのベスト プラクティスを参照してください。

SDK を外部で公開する必要がありますか?

なし - SDK には、アプリケーション コンテナーからのみアクセスできます。 セキュリティのベスト プラクティスの詳細については、「 セキュリティのベスト プラクティス」を参照してください。

SDK をセキュリティで保護する方法

包括的なガイダンスについては、「 セキュリティのベスト プラクティス」 を参照してください。

どのような資格情報を使用する必要がありますか?

基本設定の順序:

  1. マネージド ID (Azure) - 最も安全、資格情報なし
  2. 証明書 - セキュリティで保護され、ローテーション可能
  3. クライアント シークレット - あまり優先されません。セキュリティで保護されたコンテナーに保持する

SDK のコンプライアンスが認定されていますか?

GitHub リポジトリで現在のコンプライアンス情報を確認します。

Performance

SDK のパフォーマンスは、トークン キャッシュの有効性とネットワークラウンドトリップ待機時間に依存し、キャッシュされたトークンの一般的な応答時間は 10 から 50 ミリ秒です。

SDK を使用した場合のパフォーマンスへの影響は何ですか?

一般的な HTTP ラウンド トリップ: 10 ~ 50 ミリ秒

トークン キャッシュにより、取得の繰り返しが最小限に抑えられます。 最初の要求は低速 (トークンの取得) であり、後続の要求ではキャッシュされたトークンが使用されます。

SDK のパフォーマンスはインプロセス ライブラリとどのように比較されますか?

インプロセス ライブラリの方が高速ですが (ネットワークラウンドトリップはありません)、SDK では次の機能が提供されます。

  • 言語に依存しないアクセス
  • 一元化された構成
  • サービス間の共有トークン キャッシュ
  • 簡素化スケーリング

詳細については、 比較ガイド を参照してください。

SDK を水平方向にスケーリングできますか?

Yes. Kubernetes Deployment を使用して複数の SDK レプリカをデプロイします。 各ポッドは、独立したトークン キャッシュを維持します。

Migration

Microsoft.Identity.Web から SDK に移行すると、複数言語のサポート、一元化された構成、サービス間の簡素化されたスケーリングの利点が得られます。

Microsoft.Identity.Web から Microsoft Entra SDK for AgentID に移行できますか?

はい - 移行の詳細な手順については、 比較ガイド を参照してください

Support

公式チャネルを使用して、問題に関するヘルプを表示したり、追加のドキュメントを見つけたり、コミュニティ リソースにアクセスしたりできます。

バグを報告する場所

Entra ID テンプレートを使用して、 GitHub リポジトリで問題を報告します。

トラブルシューティング

SDK で問題が発生した場合は、トラブルシューティング ガイドの診断手順、一般的な問題、および解決策に関する包括的な トラブルシューティング ガイドを参照してください。

詳細情報はどこで入手できますか?

こちらもご覧ください

  • Last updated on