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

  • [アーティクル]

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

Authentication flow 可能になること サポートされているアプリケーションの種類
承認コード ユーザーに代わって、ユーザーのサインインと Web API へのアクセスを行います。 デスクトップ
Mobile
シングルページ アプリ (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) ドメインまたは Azure Active Directory (Azure AD) に参加しているコンピューターのアプリケーションは、サイレントで (ユーザーからの UI 操作なしで) トークンを取得できます。 デスクトップ、モバイル

トークン

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

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

対話型と非対話型の認証

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

  • 対話型 - ユーザーに対して、承認サーバーから入力を求めるプロンプトが出される場合があります。 たとえば、サインインを要求したり、多要素認証 (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 クライアントの資格情報フローにより、アプリケーションの ID を使って Web でホストされているリソースにアクセスできます。 この種類の許可は、バックグラウンドでの実行が必要なサーバー間の相互作用に使用され、ユーザーとの即時の相互動作は必要ありません。 これらのアプリケーションは、デーモンまたはサービス アカウントと呼ばれます。

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

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

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

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

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

証明書

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

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

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

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

  • Azure AD に登録されている。
  • コード内の機密クライアント アプリケーションのオブジェクトの構築時に渡される。

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

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

デバイス コード

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

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

次の図で説明します。

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

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

デバイス コードの制約

  • デバイス コード フローは、パブリック クライアント アプリケーションでのみ使用できます。
  • MSAL でパブリック クライアント アプリケーションを初期化する場合は、次のいずれかの形式の機関を使用します。
    • テナント: https://login.microsoftonline.com/{tenant}/, ここで、{tenant} は、テナント ID を表す GUID またはテナントに関連付けられているドメイン名です。
    • 職場または学校のアカウント: 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 の暗黙的な許可のフローでは、バックエンド サーバーとの資格情報交換を実行しなくても、アプリによって Microsoft ID プラットフォームからアクセス トークンを取得できます。 暗黙的な許可フローを使用すると、アプリで、ユーザーのサインイン、セッションの維持、ユーザー エージェント (通常は Web ブラウザー) によってダウンロードおよび実行される JavaScript コード内からの他の Web API のトークンの取得が可能になります。

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

暗黙的な許可の制約

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

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

On-behalf-of (OBO)

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

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

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

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

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

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

ROPC の制約

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

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

統合 Windows 認証 (IWA)

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

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

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

統合 Windows 認証の図。

IWA の制約

互換性

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

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

多要素認証 (MFA)

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

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

機関 URI の制限

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

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

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

同意の要件

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

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

    OR

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

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

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

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

次のステップ

MSAL でサポートされている認証フローを確認したので、次のフローで使用されるトークンの取得とキャッシュについて確認します。

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