クライアント資格情報フローについては、最初に クライアント資格情報フローのドキュメントを 参照してください。
上位レベルの API を使用する
MSAL は下位レベルの API です。 新しいアプリを作成する場合は、ASP.NET Coreと ASP.NET Classic とのすぐに使用できる高レベルのMicrosoft.Identitity.Webを使用することを検討してください。
最新の MSAL を使用する
最新の MSAL を使用して、バグの修正とパフォーマンスの向上を取得します。 セマンティック バージョン管理 規則に従います。
また、Web アプリと Web API の上位レベルのライブラリである Microsoft Identity Web を使用する必要があるかどうかを確認することもできます。これは、以下で説明する多くのことを行います。 プラットフォームと制約に応じて最適なソリューションを選択するためのデシジョン ツリーを提案する MSAL.NET のバージョンの選択を参照してください。
トークン キャッシュを使用する
既定の動作: MSAL はトークンをメモリにキャッシュします。 各 ConfidentialClientApplication インスタンスには、独自の内部トークン キャッシュがあります。 メモリ内キャッシュは、オブジェクト インスタンスが破棄された場合や、アプリケーション全体が停止した場合などに失われる可能性があります。
推薦： すべてのアプリでトークン キャッシュを保持する必要があります。 Web アプリと Web API では、L1/L2 トークン キャッシュを使用する必要があります。L2 は、スケールを処理するために Redis などの分散ストアです。 デスクトップ アプリでは 、適切なトークン キャッシュのシリアル化戦略を使用する必要があります。
Note
Microsoft.Identity.Web を使用している場合、適切なキャッシュ動作が標準で実装されているため、キャッシュについて心配する必要はありません。 Microsoft.Identity.Web は使用していないものの、Web アプリまたは Web API を構築している場合は、ハイブリッド アプローチを検討するとよいでしょう
既定の動作: MSAL は、ADAL と MSAL の間の移行シナリオ用のセカンダリ ADAL トークン キャッシュを保持します。 ADAL キャッシュ操作は非常に低速です。 推薦： ADAL からの移行に関心がない場合は、ADAL キャッシュを無効にします。 これにより、 大きな パフォーマンスが向上します。パフォーマンスの測定値 については、こちらをご覧ください。
アプリを構築するときに WithLegacyCacheCompatibility(false) を追加して、ADAL キャッシュを無効にします。
MSAL 操作に関する監視を追加する
MSAL は、 AuthenticationResult.AuthenticationResultMetadata オブジェクトの一部として重要なメトリックを公開します。
| Metric | Meaning | アラームをトリガーするタイミング |
|---|---|---|
DurationTotalInMs |
ネットワーク呼び出しとキャッシュを含む、MSAL で費やされた合計時間 | 全体的な待機時間が長い (> 1 秒) のアラーム。 値はトークン ソースによって異なります。 キャッシュから: 1 つのキャッシュ アクセス。 Microsoft Entra IDから: 2 つのキャッシュ アクセス + 1 つの HTTP 呼び出し。 最初の呼び出し (プロセスごと) は、1 つの余分な HTTP 呼び出しのために時間がかかります。 |
DurationInCacheInMs |
トークン キャッシュの読み込みまたは保存に費やされた時間。これはアプリ開発者によってカスタマイズされます (たとえば、Redis に保存)。 | スパイク時のアラーム。 |
DurationInHttpInMs |
Microsoft Entra IDへの HTTP 呼び出しの作成に費やされた時間。 | スパイク時のアラーム。 |
TokenSource |
トークンのソースを示します。 トークンはキャッシュからはるかに高速に取得されます (たとえば、約 100 ミリ秒と約 700 ミリ秒)。 キャッシュ ヒット率を監視およびアラームするために使用できます。 |
DurationTotalInMs で使用します。 |
CacheRefreshReason |
ID プロバイダーからアクセス トークンを取得する理由を指定します。 「 可能な値」を参照してください。 |
TokenSource で使用します。 |
Logging
MSAL ログから出力される Warning レベルおよび Error レベルのメッセージを監視します。 これらは、サイレント エラーや、別の構成を使用するための強い推奨事項です。多くのメッセージを生成し、パフォーマンスに影響を与えるので、運用環境で Verbose ログ記録を設定することはお勧めしません。
ログ記録の詳細については、MSAL.NET ガイドの「ログ記録」を参照してください。
再試行ポリシー
既定の動作: MSAL は失敗した 5xx 要求を 1 回再試行します。
推奨事項:
- Polly を使用 して再試行ポリシー を記述する場合は、再試行ポリシーのドキュメントを参照してください
セッションごとに 1 つの Confidential Client
各セッションで新しい ConfidentialClientApplication を使用し、同じ方法 (セッションごとに 1 つのトークン キャッシュ) でシリアル化することをお勧めします。 これは適切にスケーリングされ、セキュリティも向上します。
公式サンプルは、これを行う方法を示しています。 これを正しく機能させるには 、トークン キャッシュを構成 する必要があります。
Note
Microsoft.Identity.Web は、このアプローチを適用します。トークン キャッシュが有効になっている要求ごとに 1 つの機密クライアント アプリ インスタンスです。
Httpクライアント
既定の動作: MSAL で作成された HttpClient は、Web サイト/Web API では適切にスケーリングされません。ここでは、ユーザー セッションごとに ClientApplication オブジェクトを用意することをお勧めします。
推奨事項: 独自のスケーラブルな HttpClientFactory を提供します。 .NET Core では、System.Net.Http.IHttpClientFactory を依存性注入することをお勧めします。 詳細については、独自の HttpClient の提供、HTTP プロキシのサポート、ユーザー エージェント ヘッダーのカスタマイズに関するガイドと.NETドキュメントを参照してください。
プロアクティブ トークンの更新
ゴール
有効期間の長いアクセス トークンを発行してアプリケーションの可用性を向上させ、有効期限よりも早く更新されるようにします。
現状
既定では、Microsoft Entra IDは 1 時間の有効期限でアクセス トークンを発行します。 トークンを更新する必要があるときにMicrosoft Entra停止が発生した場合、MSAL は失敗します。 エラーは呼び出し元のアプリケーションに伝達され、可用性に影響します。
プロセス
可用性を向上させるために、MSAL はアプリが常に新しい有効なトークンを保持できるようにします。 Microsoft Entraの停止に数時間以上かかることはめったにないため、MSAL がトークンに少なくとも数時間の可用性が常に残っていることを保証できる場合、アプリケーションはMicrosoft Entraの停止の影響を受けなくなります。
有効期間の長いトークンを取得するには、テナントを構成する必要があります (注: 内部Microsoftテナントは既に構成されています)。 client_credentials (サービス 2 サービス) の場合は、これで十分です。 ユーザー資格情報の場合は、CAE - /azure/active-directory/conditional-access/concept-continuous-access-evaluation も構成する必要があります。
Microsoft Entra IDが有効期間の長いトークンを返すと、refresh_in フィールドが含まれます。 通常、アクセス トークンの有効期限の半分に設定されます。
注: MSAL 4.37.0 以降では、 AuthenticationResult.AuthenticationResultMetadata.RefreshOnを調べることでこの値を確認できます。
さらに、Microsoft ID プラットフォーム (プレビュー) の構成可能なトークンの有効期間の説明に従って、既定の 1 時間を超えるトークンの有効期間を構成できます。
同じトークンに対して要求を行うたびに、つまり MSAL がキャッシュからトークンを提供できる場合は常に、MSAL によってrefresh_in値が自動的にチェックされます。 有効期限が切れている場合、MSAL はバックグラウンドで Microsoft Entra ID にトークン要求を発行しますが、既存の有効なトークンをアプリケーションに返します。 万が一、バックグラウンド更新が失敗した場合 (Microsoft Entraの停止など)、アプリは影響を受けなくなります。
証明書のローテーション
機密クライアント アプリの証明書は、セキュリティ上の理由からローテーションする必要があります (prod ではシークレットを使用しないでください)。 最も望ましいものからそうでないものの順に、証明書ローテーションに対処する方法はいくつかあります。
- マネージド ID の使用
マネージド ID では、Azureでアプリをホストして信頼が確立されます。 維持するシークレットはなく、ローテーションする証明書もありません。
-
Microsoft.Identity.Web証明書処理ロジックを使用する
Web アプリと Web API では、MSAL よりも上位レベルの API Microsoft.Identity.Webを使用します。 証明書がAzure Key Vaultに格納されるときに証明書のローテーションを処理し、マネージド ID ケースも処理します。
詳細については、Microsoft.Identity.Web の証明書 ガイドを参照してください。
これは、ASP.NET Coreを使用するMicrosoft以外の内部サービスに推奨されるソリューションです。
- (Microsoft内部のみ) サブジェクト名/発行者証明書に依存します。
このメカニズムにより、Microsoft Entra IDは拇印 (x5t) ではなく SN/I に基づいて証明書を識別できます。 これはストップギャップソリューションです。Microsoft以外のアプリケーションで使用できるようにする予定はありません。
これは、マネージド ID を使用できない内部サービスMicrosoft推奨されるソリューションです。