MSAL での認証フローのサポート

  • [アーティクル]

Microsoft Authentication Library (MSAL) では、さまざまなアプリケーションの種類とシナリオで使用できる複数の承認許可および関連付けられたトークン・フローがサポートされています。

Authentication flow 可能になること サポートされているアプリケーションの種類
承認コード ユーザーに代わって、ユーザーのサインインと Web API へのアクセスを行います。 デスクトップ
モバイル
シングルページ アプリ (SPA) (PKCE が必要)
Web
クライアント資格情報 アプリケーション自体の ID を使用して Web API にアクセスします。 通常は、サーバー間通信や、ユーザー操作を必要としない自動化されたスクリプトに使用されます。 Daemon
デバイス コード スマート TV や IoT デバイスなど、入力に制約のあるデバイスでユーザーに代わって、ユーザーのサインインと Web API へのアクセスを行います。 コマンド ライン インターフェイス (CLI) アプリケーションでも使用されます。 デスクトップ、モバイル
暗黙的な許可 ユーザーに代わって、ユーザーのサインインと Web API へのアクセスを行います。 暗黙的な許可フローは推奨されなくなりました。代わりに PKCE で承認コードを使用してください。 * シングルページ アプリ (SPA)
* Web
On-behalf-of (OBO) ユーザーに代わって、"アップストリーム" Web API から "ダウンストリーム" Web API にアクセスします。 ユーザーの ID と委任されたアクセス許可は、アップストリーム API からダウンストリーム API に渡されます。 Web API
ユーザー名/パスワード (ROPC) アプリケーションはパスワードを直接処理することによって、ユーザーをサインインさせることができます。 ROPC フローは推奨されません。 デスクトップ、モバイル
統合 Windows 認証 (IWA) ドメインまたは Microsoft Entra に参加しているコンピューターのアプリケーションは、サイレントで (ユーザーからの UI 操作なしで) トークンを取得できます。 デスクトップ、モバイル

トークン

アプリケーションでは、1 つ以上の認証フローを使用できます。 各フローでは、認証、承認、トークンの更新に特定のトークンの種類が使用され、一部では承認コードも使用されます。

認証フローまたはアクション 必要 ID トークン アクセス トークン リフレッシュトークン Authorization code (承認コード)
承認コード フロー 認可フローは ID トークンに対して機能する 認可フローはアクセス トークンに対して機能する 認可フローは更新トークンに対して機能する 認可コードは機能する
クライアントの資格情報 認可フローはアクセス トークンに対して機能する (アプリのみ)
デバイス コード フロー 認可フローは ID トークンに対して機能する 認可フローはアクセス トークンに対して機能する 認可フローは更新トークンに対して機能する
暗黙的なフロー 認可フローは ID トークンに対して機能する 認可フローはアクセス トークンに対して機能する
On-Behalf-Of フロー アクセス トークン 認可フローは ID トークンに対して機能する 認可フローはアクセス トークンに対して機能する 認可フローは更新トークンに対して機能する
ユーザー名/パスワード (ROPC) ユーザー名、パスワード 認可フローは ID トークンに対して機能する 認可フローはアクセス トークンに対して機能する 認可フローは更新トークンに対して機能する
ハイブリッド OIDC フロー 認可フローは ID トークンに対して機能する 認可コードは機能する
更新トークンの使用 更新トークン 認可フローは ID トークンに対して機能する 認可フローはアクセス トークンに対して機能する 認可フローは更新トークンに対して機能する

対話型と非対話型の認証

これらのフローのいくつかでは、対話型と非対話型の両方のトークンの取得がサポートされています。

  • 対話型 - ユーザーに対して、承認サーバーから入力を求めるプロンプトが出される場合があります。 たとえば、サインインを要求したり、多要素認証 (MFA) を実行したり、追加のリソース アクセス許可に対する同意を付与したりすることができます。
  • 非対話型 (サイレント) - 入力を求めるプロンプトがユーザーに表示されることはあり "ません"。 "サイレント" トークン取得とも呼ばれ、アプリケーションは、承認サーバーがユーザーに入力を求めるプロンプトを出さない方法を使用してトークンを取得します。

MSAL ベースのアプリケーションでは、最初にトークンをサイレントで取得しようとします。その後、非対話型での試行が失敗した場合にのみ対話型の方法を試みます。 このパターンの詳細については、「Microsoft Authentication Library (MSAL) を使用してトークンを取得し、キャッシュする」を参照してください。

Authorization code (承認コード)

OAuth 2.0 承認コード付与は、Web アプリ、シングルページ アプリ (SPA)、ネイティブ (モバイルおよびデスクトップ) アプリで、Web API などの保護されたリソースにアクセスへのアクセス権を付与するために使用できます。

ユーザーが Web アプリケーションにサインインすると、アプリケーションは、Web API を呼び出すアクセス トークンに引き換えることができる承認コードを受け取ります。

下の図では、アプリケーションは次の処理を行います。

  1. アクセス トークンと引き換えられた認可コードを要求します
  2. アクセス トークンを使って Web API (Microsoft Graph) を呼び出します

承認コード フローの図。

承認コードの制約

  • シングルページ アプリケーションでは、承認コード付与フローを使用するときに、Proof Key for Code Exchange (PKCE) が必要です。 PKCE は MSAL でサポートされています。

  • OAuth 2.0 仕様では、承認コードを使用してアクセス トークンを "1 回だけ" 引き換える必要があります。

    同じ承認コードを使用してアクセス トークンを複数回取得しようとすると、Microsoft ID プラットフォームから次のようなエラーが返されます。 一部のライブラリとフレームワークでは自動的に承認コードが要求されるため、そのような場合に手動でコードを要求した場合にもこのエラーが発生します。

    AADSTS70002: Error validating credentials. AADSTS54005: OAuth2 Authorization code was already redeemed, please retry with a new valid code or use an existing refresh token.

クライアントの資格情報

OAuth 2.0 クライアントの資格情報フローにより、アプリケーションの ID を使って Web でホストされているリソースにアクセスできます。 この種類の許可は、バックグラウンドでの実行が必要なサーバー間の相互作用に使用され、ユーザーとの即時の相互動作は必要ありません。 これらのアプリケーションは、デーモンまたはサービス アカウントと呼ばれます。

クライアント資格情報許可フローでは、Web サービス (Confidential クライアント) が別の Web サービスを呼び出すときに、ユーザーを偽装する代わりに、独自の資格情報を使用して認証することができます。 このシナリオでは、クライアントは通常、中間層の Web サービス、デーモン サービス、または Web サイトです。 高いレベルの保証では、Microsoft ID プラットフォームにより、呼び出し元サービスが、資格情報として (共有シークレットではなく) 証明書を使用することもできます。

アプリケーション シークレット

下の図では、アプリケーションは次の処理を行います。

  1. アプリケーションのシークレットまたはパスワード資格情報を使ってトークンを取得します
  2. トークンを使ってリソースの要求を行います

パスワードを使用する機密クライアントの図。

証明書

下の図では、アプリケーションは次の処理を行います。

  1. 証明書の資格情報を使ってトークンを取得します
  2. トークンを使ってリソースの要求を行います

証明書を使用する機密クライアントの図。

これらのクライアント資格情報では以下のことが必要です。

  • Microsoft Entra ID に登録されている
  • コード内のコンフィデンシャル クライアント アプリケーションのオブジェクトの構築時に渡されている

クライアント資格情報の制約

機密クライアントフローは、Android、iOS、UWP などのモバイル プラットフォームではサポートされません。 モバイル アプリケーションは、資格情報の機密性を保証できないパブリック クライアント アプリケーションと見なされます。

デバイス コード

OAuth 2.0 デバイス コード フローでは、ユーザーがスマート TV、IoT デバイス、プリンターなどの入力制限のあるデバイスにサインインできます。 Microsoft Entra ID を使用した対話型認証には、Web ブラウザーが必要です。 Web ブラウザーを提供しないデバイスまたはオペレーティング システムでは、ユーザーはデバイス コード フローによって別のデバイス (コンピューターや携帯電話など) を使用して対話形式でサインインできます。

デバイス コード フローを使用すると、アプリケーションでは、これらのデバイスおよびオペレーティング システム用に設計された 2 ステップ プロセスを通じてトークンを取得します。 このようなアプリケーションには、IoT デバイスで実行されているアプリケーションやコマンドライン インターフェイス (CLI) ツールなどがあります。

次の図で説明します。

  1. ユーザー認証が必要になるたびに、アプリがコードを提供し、ユーザーに別のデバイス (インターネットに接続されたスマートフォンなど) を使用して特定の URL (たとえば、https://microsoft.com/devicelogin) に移動するよう求めます。 その後、ユーザーはコードの入力を求められ、必要に応じて、同意のプロンプトや多要素認証を含む通常の認証エクスペリエンスが実行されます。
  2. 認証が成功すると、コマンドライン アプリはバック チャネル経由で必要なトークンを受信し、それらを使用して必要な Web API の呼び出しを実行します。

デバイス コード フローの図。

デバイス コードの制約

  • デバイス コード フローは、パブリック クライアント アプリケーションでのみ使用できます。
  • MSAL でパブリック クライアント アプリケーションを初期化する場合は、次のいずれかの形式の機関を使用します。
    • テナント: https://login.microsoftonline.com/{tenant}/,。この {tenant} は、テナント ID またはテナントに関連付けられているドメイン名です。
    • 職場または学校のアカウント: https://login.microsoftonline.com/organizations/

Implicit grant (暗黙的な付与)

暗黙的な許可フローは、クライアント側のシングルページ アプリケーション (SPA) で推奨される、よりセキュアなトークン許可フローとして、PKCE を使った認可コード フローに置き換えられました。 暗黙的な許可フローの使用は推奨されなくなりました。 SPA を構築する場合は、代わりに PKCE を使用した承認コード フローを使用してください。

JavaScript で記述されたシングルページ Web アプリ (Angular、Vue.js、React.js などのフレームワークを含む) がサーバーからダウンロードされ、そのコードがブラウザーで直接実行されます。 クライアント側のコードが Web サーバーではなくブラウザーで実行されるため、従来のサーバー側の Web アプリケーションとは異なるセキュリティ特性を持ちます。 承認コード フローに対して Proof Key for Code Exchange (PKCE) が使用可能になる前は、アクセストークンを取得する際の応答性と効率を向上させるために、暗黙的な許可フローが SPA によって使用されていました。

OAuth 2.0 の暗黙的な許可フローでは、バックエンド サーバーとの資格情報交換を実行しなくても、アプリによって Microsoft ID プラットフォームからアクセス トークンを取得できます。 暗黙的な許可フローを使用すると、アプリで、ユーザーのサインイン、セッションの維持、ユーザー エージェント (通常は Web ブラウザー) によってダウンロードおよび実行される JavaScript コード内からの他の Web API のトークンの取得が可能になります。

暗黙的な許可のフローの図

暗黙的な許可の制約

暗黙的な許可フローには、Electron や React Native などのクロスプラットフォーム JavaScript フレームワークを使用するアプリケーション シナリオは含まれていません。 このようなクロスプラットフォーム フレームワークでは、それらが動作するデスクトップおよびモバイルのネイティブ プラットフォームと対話するための追加の機能が必要です。

暗黙的モードで発行されたトークンには、URL によってブラウザーに返されるために長さの制限があります (response_mode は query または fragment のいずれか)。 一部のブラウザーでは、ブラウザーのバー内の URL の長さが制限され、長すぎると失敗します。 そのため、これらの暗黙的なフロー トークンには groups または wids 要求が含まれていません。

On-behalf-of (OBO)

OAuth 2.0 の On-Behalf-Of 認証フローというフローは、アプリケーションでサービスまたは Web API を呼び出し、それがさらに別のサービスまたは Web API を呼び出す必要がある場合に、使われます。 その考え方は、委任されたユーザー ID とアクセス許可を要求チェーン経由で伝達するというものです。 中間層サービスがダウンストリーム サービスに認証済み要求を発行するには、そのサービスは Microsoft ID プラットフォームからのアクセス トークンをユーザーに代わってセキュリティ保護する必要があります。

次の図で説明します。

  1. アプリケーションは Web API 用のアクセス トークンを取得します。
  2. クライアント (Web、デスクトップ、モバイル、またはシングルページ アプリケーション) が保護された Web API を呼び出し、HTTP 要求の認証ヘッダーのベアラー トークンとしてアクセス トークンを追加します。 Web API がユーザーを認証します。
  3. クライアントが Web API を呼び出すと、Web API はユーザーの代わりに別のトークンを要求します。
  4. 保護された Web API は、このトークンを使用して、ユーザーの代わりにダウンストリームの Web API を呼び出します。 Web API は、他のダウンストリーム API のトークンを (ただし、ここでも同じユーザーの代わりとして) 後で要求することもできます。

on-behalf-of フローの図。

ユーザー名/パスワード (ROPC)

警告

リソース所有者のパスワード資格情報 (ROPC) フローは推奨されません。 ROPC には、高度な信頼と資格情報の公開が要求されます。 ROPC を使用するのは、より安全なフローを使用できない場合のみにしてください。 詳細については、深刻化するパスワードの問題の解決策に関する記事を参照してください。

OAuth 2.0 のリソース所有者のパスワード資格情報 (ROPC) の付与により、アプリケーションでは、ユーザーのパスワードを直接処理することでユーザーをサインインさせることができます。 デスクトップ アプリケーションでは、ユーザー名/パスワードのフローを使ってサイレントにトークンを取得できます。 アプリケーションを使用するときに UI は必要ありません。

DevOps のような一部のアプリケーション シナリオでは ROPC が有用であることもありますが、ユーザー サインインのための対話型 UI を提供するアプリケーションでは、使用しないようにしてください。

下の図では、アプリケーションは次の処理を行います。

  1. ID プロバイダーにユーザー名とパスワードを送信することによって、トークンを取得します
  2. トークンを使って Web API を呼び出します

ユーザー名/パスワード フローの図。

Windows ドメインに参加済みのマシン上でサイレントにトークンを取得する場合は、ROPC ではなく統合 Windows 認証 (IWA) をお勧めします。 その他のシナリオでは、デバイス コード フローを使用してください。

ROPC の制約

ROPC フローを使用するアプリケーションには、次の制約が適用されます。

  • シングル サインオンはサポートされません。
  • 多要素認証 (MFA) はサポートされません。
    • このフローを使用する前に、テナント管理者に確認してください。MFA は一般的に使用されている機能です。
  • 条件付きアクセスはサポートされません。
  • ROPC は職場および学校のアカウントにのみ有効です。
  • ROPC では、個人の Microsoft アカウント (MSA) はサポートされません。
  • ROPC は、.NET デスクトップおよび ASP.NET Core のアプリケーションでサポートされます。
  • ROPC は、ユニバーサル Windows プラットフォーム (UWP) アプリケーションではサポートされません。
  • Azure AD B2C での ROPC は、ローカル アカウントでのみサポートされます。

統合 Windows 認証 (IWA)

MSAL では、ドメイン参加済みまたは Microsoft Entra 参加済み Windows コンピューター上で実行されるデスクトップおよびモバイルのアプリケーションに対して統合 Windows 認証 (IWA) がサポートされています。 IWA を使用すると、これらのアプリケーションは、ユーザーによる UI 操作なしでトークンをサイレントに取得します。

下の図では、アプリケーションは次の処理を行います。

  1. 統合 Windows 認証を使ってトークンを取得します
  2. トークンを使ってリソースの要求を行います

統合 Windows 認証の図。

IWA の制約

互換性

統合 Windows 認証 (IWA) は、.NET デスクトップ、.NET、および Windows ユニバーサル プラットフォームの各アプリに対して有効です。

IWA は AD FS フェデレーション ユーザー、つまり Active Directory で作成され、Microsoft Entra ID による支援があるユーザー "のみ" をサポートします。 Microsoft Entra ID で直接作成され、Active Directory のサポートのないユーザー (マネージド ユーザー) はこの認証フローを使用できません。

多要素認証 (MFA)

Microsoft Entra テナントで MFA が有効になっていて、Microsoft Entra ID によって MFA チャレンジが発行されている場合、IWA の非対話型 (サイレント) 認証は失敗する可能性があります。 IWA が失敗した場合は、前述のように、対話型の認証方式に切り替える必要があります。

Microsoft Entra ID では、AI を使用して、2 要素認証が必要な状況を判別します。 通常、2 要素認証は、ユーザーが異なる国/リージョンからサインインする場合および VPN を使用せずに企業ネットワークに接続している場合に必要ですが、VPN 経由で接続している場合でも必要になることがあります。 MFA の構成とチャレンジの頻度は開発者が制御できないため、アプリケーションが、IWA のサイレント トークン取得の失敗を適切に処理する必要があります。

機関 URI の制限

パブリック クライアント アプリケーションを構築するときに渡される機関は、次のいずれかである必要があります。

  • https://login.microsoftonline.com/{tenant}/ - この機関は、サインイン対象ユーザーが指定された Microsoft Entra テナント内のユーザーに制限されている、シングル テナント アプリケーションを示します。 {tenant} の値には、GUID 形式のテナント ID、またはテナントに関連付けられているドメイン名を指定できます。
  • https://login.microsoftonline.com/organizations/ - この機関は、サインイン対象ユーザーが任意の Microsoft Entra テナント内のユーザーであるマルチテナント アプリケーションを示します。

個人の Microsoft アカウント (MSA) は IWA でサポートされないため、機関の値に /common または /consumers を含めてはなりません。

同意の要件

IWA はサイレント フローであるため、次のようになります。

  • アプリケーションのユーザーが、アプリケーションの使用に事前に同意しておく必要があります。

    OR

  • テナント管理者が、テナント内のすべてのユーザーによるアプリケーションの使用に事前に同意しておく必要があります。

いずれかの要件を満たすには、次のいずれかの操作が完了している必要があります。

  • アプリケーション開発者が Azure portal で自分自身に対して[許可]を選択しておきます。
  • テナント管理者が Azure portal のアプリ登録の [API のアクセス許可] タブにある [{テナント ドメイン} の管理者の同意を付与/取り消す] を選択しておきます (「Web API にアクセスするためのアクセス許可を追加する」を参照)。
  • ユーザーがアプリケーションに同意する方法を指定しておきます (「ユーザーの同意」を参照)。
  • テナント管理者がアプリケーションに同意する方法を指定しておきます (管理者の同意に関するセクションを参照)。

同意の詳細については、アクセス許可と同意に関するページを参照してください。

次のステップ

これらのフローで使われるトークンの取得とキャッシュについて説明します。

Microsoft Authentication Library (MSAL) を使用してトークンを取得し、キャッシュする