MSAL 中的驗證流程支援

  • 發行項

Microsoft 驗證連結庫 （MSAL） 支援數個授權授與和相關聯的令牌流程，以供不同的應用程式類型和案例使用。

驗證流程 使 支援的應用程式類型
授權碼 使用者代表使用者登入和存取 Web API。 Desktop (電腦)
行動
單頁應用程式 （SPA） （需要 PKCE）
Web
用戶端認證 使用應用程式本身的身分識別來存取 Web API。 通常用於伺服器對伺服器通訊，以及不需要用戶互動的自動化腳本。 守護進程
裝置代碼 使用者代表輸入限制裝置上的使用者登入和存取 Web API，例如智慧型手機電視與 IoT 裝置。 命令行介面 （CLI） 應用程式也使用。 桌面電腦、行動裝置版
隱含授與 使用者代表使用者登入和存取 Web API。 不再建議使用隱含授與流程 - 請改用授權碼搭配 PKCE。 * 單頁應用程式 （SPA）
* Web
代表 （OBO） 代表使用者從「上游」Web API 存取「下游」Web API。 使用者的身分識別和委派許可權會從上游 API 傳遞至下游 API。 Web API
使用者名稱/密碼 （ROPC） 允許應用程式直接處理其密碼來登入使用者。 不建議使用 ROPC 流程。 桌面電腦、行動裝置版
綜合 Windows 驗證（IWA） 允許網域或已加入 Microsoft Entra 的電腦上的應用程式以無訊息方式取得令牌（不需要使用者的任何 UI 互動）。 桌面電腦、行動裝置版

語彙基元

您的應用程式可以使用一或多個驗證流程。 每個流程都會使用特定令牌類型來進行驗證、授權和令牌重新整理，有些也會使用授權碼。

驗證流程或動作 需要 標識元令牌 存取權杖 重新整理令牌 授權碼
授權碼流程 驗證流程適用於標識碼令牌 驗證流程適用於存取令牌 驗證流程適用於重新整理令牌 授權碼可運作
用戶端認證 驗證流程適用於存取令牌 （僅限 app）
裝置程式代碼流程 驗證流程適用於標識碼令牌 驗證流程適用於存取令牌 驗證流程適用於重新整理令牌
隱含流程 驗證流程適用於標識碼令牌 驗證流程適用於存取令牌
代理者流程 存取權杖 驗證流程適用於標識碼令牌 驗證流程適用於存取令牌 驗證流程適用於重新整理令牌
使用者名稱/密碼 （ROPC） 使用者名稱、密碼 驗證流程適用於標識碼令牌 驗證流程適用於存取令牌 驗證流程適用於重新整理令牌
混合式 OIDC 流程 驗證流程適用於標識碼令牌 授權碼可運作
重新整理權杖兌換 重新整理權杖 驗證流程適用於標識碼令牌 驗證流程適用於存取令牌 驗證流程適用於重新整理令牌

互動式和非互動式驗證

其中數個流程同時支援互動式和非互動式令牌擷取。

  • 互動式 - 授權伺服器可能會提示使用者輸入。 例如，若要登入、執行多重要素驗證 （MFA），或授與同意更多資源訪問許可權。
  • 非互動式 （無提示） - 使用者可能不會提示輸入。 也稱為「無訊息」令牌擷取，應用程式會嘗試使用授權伺服器 可能無法 提示使用者輸入的方法來取得令牌。

您的 MSAL 型應用程式應該先嘗試以無訊息方式取得令牌，只有在非互動式嘗試失敗時，才回到互動式方法。 如需此模式的詳細資訊，請參閱 使用 Microsoft 驗證連結庫 （MSAL） 取得和快取令牌。

授權碼

Web 應用程式、單頁應用程式（SPA）和原生（行動裝置和桌面）應用程式可以使用 OAuth 2.0 授權碼授與，以存取受保護的資源，例如 Web API。

當使用者登入 Web 應用程式時，應用程式會收到可兌換存取令牌以呼叫 Web API 的授權碼。

在下圖中，應用程式：

  1. 要求已兌換存取令牌的授權碼
  2. 使用存取令牌來呼叫 Web API Microsoft Graph

授權碼流程的圖表。

授權碼的條件約束

  • 使用授權碼授與流程時，單頁應用程式需要 Code Exchange 的證明金鑰（PKCE）。 MSAL 支援 PKCE。

  • OAuth 2.0 規格要求您只 使用授權碼來兌換存取令牌一次。

    如果您嘗試使用相同的授權碼多次取得存取令牌，Microsoft 身分識別平台 會傳回類似下列的錯誤。 某些連結庫和架構會自動為您要求授權碼，而且在這種情況下手動要求程式代碼也會導致此錯誤。

    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 用戶端認證流程可讓您使用應用程式的身分識別來存取 Web 裝載的資源。 這類型的授與通常用於必須在背景中執行 (不需與使用者直接互動) 的伺服器對伺服器互動。 這些類型的應用程式通常稱為精靈或服務帳戶。

客戶端認證授與流程允許 Web 服務（機密用戶端）使用自己的認證，而不是模擬使用者，以在呼叫另一個 Web 服務時進行驗證。 在此案例中，用戶端通常是仲介層 Web 服務、精靈服務或網站。 為了獲得更高的保證層級，Microsoft 身分識別平台 也允許呼叫服務使用憑證（而不是共用密碼）作為認證。

應用程式秘密

在下圖中，應用程式：

  1. 使用應用程式密碼或密碼認證取得令牌
  2. 使用令牌提出資源的要求

具有密碼的機密用戶端圖表。

憑證

在下圖中，應用程式：

  1. 使用憑證認證取得令牌
  2. 使用令牌提出資源的要求

具有憑證的機密用戶端圖表。

這些客戶端認證必須是：

  • 向 Microsoft Entra 識別元註冊
  • 在程式代碼中建構機密用戶端應用程式物件時傳入

用戶端認證的條件約束

Android、iOS 或 UWP 等行動平台不支援機密用戶端流程。 行動應用程式被視為無法保證其認證機密性的公用用戶端應用程式。

裝置代碼

OAuth 2.0 裝置程式代碼流程可讓使用者登入輸入限制的裝置，例如智慧型手機電視、IoT 裝置和印表機。 使用 Microsoft Entra ID 進行互動式驗證需要網頁瀏覽器。 當裝置或作業系統未提供網頁瀏覽器時，裝置程式代碼流程可讓使用者使用另一部裝置，例如計算機或行動電話以互動方式登入。

透過使用裝置程式代碼流程，應用程式會透過針對這些裝置和作業系統設計的雙步驟程式來取得令牌。 這類應用程式的範例包括那些在IoT裝置上執行的應用程式，以及命令行介面 （CLI） 工具。

在下圖中：

  1. 每當需要使用者驗證時，應用程式會提供程式碼，並要求使用者使用另一部裝置，例如因特網連線的智慧型手機來瀏覽 URL（例如）。 https://microsoft.com/devicelogin 然後，系統會提示使用者輸入程序代碼，並視需要繼續進行一般驗證體驗，包括同意提示和 多重要素驗證。
  2. 成功驗證後，命令行應用程式會透過後端通道接收所需的令牌，並使用它們來執行所需的 Web API 呼叫。

裝置程式代碼流程的圖表。

裝置程式代碼的條件約束

  • 裝置程式代碼流程僅適用於公用用戶端應用程式。
  • 當您以 MSAL 初始化公用用戶端應用程式時，請使用下列其中一種授權單位格式：
    • 租使用者： https://login.microsoftonline.com/{tenant}/, 其中 {tenant} 是租用戶標識碼或與租使用者相關聯的功能變數名稱。
    • 公司與學校帳戶： https://login.microsoftonline.com/organizations/。

隱含授與

隱含授與流程已由 授權碼流程取代為 PKCE ，作為用戶端單頁應用程式 （SPA） 慣用且更安全的令牌授與流程。 不建議再使用隱含授與流程。 如果您要建置 SPA，請改用授權碼流程搭配 PKCE。

以 JavaScript 撰寫的單頁 Web 應用程式（包括 Angular、Vue.js 或 React.js 等架構）會從伺服器下載，而且其程式代碼會直接在瀏覽器中執行。 由於其用戶端程式代碼會在瀏覽器中執行，而不是在網頁伺服器上執行，因此其安全性特性與傳統伺服器端 Web 應用程式不同。 在授權碼流程的 Proof Key for Code Exchange （PKCE） 可用性之前，SPA 會使用隱含授與流程來改善存取令牌的回應性和效率。

OAuth 2.0 隱含授與流程可讓應用程式從 Microsoft 身分識別平台 取得存取令牌，而不需要執行後端伺服器認證交換。 隱含授與流程可讓應用程式登入使用者、維護會話，並從使用者代理程式下載和執行的 JavaScript 程式代碼中取得其他 Web API 的令牌（通常是網頁瀏覽器）。

隱含授與流程的圖表

隱含授與的條件約束

隱含授與流程不包含使用電子或 React Native 等跨平臺 JavaScript 架構的應用程式案例。 這類跨平台架構需要進一步的功能，才能與其執行所在的原生桌面和行動平台互動。

透過隱含流程模式發出的令牌有 長度限制 ，因為它們會依URL傳回瀏覽器（其中 response_mode 為 query 或 fragment）。 有些瀏覽器會限制瀏覽器列中 URL 的長度，而且當 URL 太長時就會失敗。 因此，這些隱含流程令牌不包含 groups 或 wids 宣告。

代表 （OBO）

當應用程式叫用服務或 Web API 時，會使用 OAuth 2.0 代理驗證流程流程，而應用程式接著需要呼叫另一個服務或 Web API。 其概念是透過要求鏈傳播委派的使用者身分識別和權限。 若要讓仲介層服務對下游服務提出已驗證的要求，它必須代表用戶保護來自 Microsoft 身分識別平台的存取令牌。

在下圖中：

  1. 應用程式會取得 Web API 的存取令牌。
  2. 用戶端（Web、桌面、行動裝置或單頁應用程式）會呼叫受保護的 Web API，並將存取令牌新增為 HTTP 要求的驗證標頭中的持有人令牌。 Web API 會驗證使用者。
  3. 當用戶端呼叫 Web API 時，Web API 會代表使用者要求另一個令牌。
  4. 受保護的 Web API 會使用此令牌來代表使用者呼叫下游 Web API。 Web API 也可以稍後要求其他下游 API 的令牌（但仍代表相同的使用者）。

代表流程的圖表。

使用者名稱/密碼 （ROPC）

警告

不建議使用資源擁有者密碼認證 （ROPC） 流程。 ROPC 需要高度的信任和認證暴露。 只有在無法使用更安全的流程時，才使用 ROPC。 如需詳細資訊，請參閱 如何解決日益嚴重的密碼問題？。

OAuth 2.0 資源擁有者密碼認證 （ROPC） 授與可讓應用程式直接處理其密碼來登入使用者。 在您的傳統型應用程式中，您可以使用使用者名稱/密碼流程以無訊息方式取得令牌。 使用應用程式時不需要UI。

某些應用程式案例，例如 DevOps 可能會發現 ROPC 很有用，但您應該避免在提供互動式 UI 供使用者登入的任何應用程式中使用。

在下圖中，應用程式：

  1. 將使用者名稱和密碼傳送至識別提供者，以取得令牌
  2. 使用令牌呼叫 Web API

用戶名稱/密碼流程的圖表。

若要在已加入網域的計算機上以無訊息方式取得令牌，建議您整合 Windows 驗證 （IWA），而不是 ROPC。 在其他案例中，請使用裝置程序 代碼流程。

ROPC 的條件約束

下列條件約束適用於使用 ROPC 流程的應用程式：

  • 不支援單一登錄。
  • 不支援多重要素驗證 （MFA）。
    • 使用此流程之前，請先洽詢租用戶系統管理員 - MFA 是常用的功能。
  • 不支援條件式存取。
  • ROPC 僅適用於 工作和學校帳戶。
  • ROPC 不支援個人 Microsoft 帳戶 （MSA）。
  • .NET 桌面和 ASP.NET Core 應用程式中支援 ROPC。
  • 通用 Windows 平台 （UWP） 應用程式中不支援 ROPC。
  • Azure AD B2C 中的 ROPC 僅支援本機帳戶。
    • 如需 MSAL.NET 和 Azure AD B2C 中 ROPC 的相關信息，請參閱 搭配 Azure AD B2C 使用 ROPC。

綜合 Windows 驗證（IWA）

MSAL 支援在已加入網域或加入 Microsoft Entra 的 Windows 電腦上執行的桌面和行動應用程式整合式 Windows 驗證 （IWA）。 藉由使用 IWA，這些應用程式會以無訊息方式取得令牌，而不需要使用者進行 UI 互動。

在下圖中，應用程式：

  1. 使用整合式 Windows 驗證 取得令牌
  2. 使用令牌提出資源的要求

整合式 Windows 驗證 圖表。

IWA 的條件約束

相容性

已針對 .NET 桌面、.NET 和 Windows 通用平台應用程式啟用整合式 Windows 驗證 （IWA）。

IWA 僅支援 AD FS 同盟使用者 - 在 Active Directory 中建立且受 Microsoft Entra 識別碼支援的使用者。 在沒有 Active Directory 備份的 Microsoft Entra 識別碼中直接建立的使用者（受控使用者）無法使用此驗證流程。

多重要素驗證 （MFA）

如果在 Microsoft Entra 租使用者中啟用 MFA，且 Microsoft Entra 識別碼發出 MFA 挑戰，IWA 的非互動式（無訊息）驗證可能會失敗。 如果 IWA 失敗，您應該回復為 如先前所述的互動式驗證 方法。

Microsoft Entra ID 會使用 AI 來判斷何時需要雙因素驗證。 當使用者從不同的國家/地區登入、連線到公司網路而不使用 VPN 時，有時透過 VPN 連線時，通常需要雙因素驗證。 因為 MFA 的組態和挑戰頻率可能不是開發人員，因此您的應用程式應該正常處理 IWA 無訊息令牌擷取失敗。

授權單位 URI 限制

建構公用用戶端應用程式時傳入的授權單位必須是下列其中一項：

  • https://login.microsoftonline.com/{tenant}/ - 此授權單位指出單一租使用者應用程式，其登入物件僅限於指定 Microsoft Entra 租使用者中的使用者。 此值 {tenant} 可以是 GUID 格式的租使用者標識碼或與租使用者相關聯的功能變數名稱。
  • https://login.microsoftonline.com/organizations/ - 此授權單位指出多租使用者應用程式，其登入物件是任何 Microsoft Entra 租使用者中的使用者。

授權單位值不得包含 /common 或 /consumers ，因為 IWA 不支援個人 Microsoft 帳戶 （MSA）。

同意需求

因為 IWA 是無訊息流程：

  • 您應用程式的使用者先前必須已同意使用應用程式。

    OR

  • 租用戶系統管理員先前必須已同意租使用者中的所有使用者使用應用程式。

若要滿足任一需求，下列其中一項作業必須已完成：

  • 您身為應用程式開發人員已在 Azure 入口網站 中為您自己選取 [授與]。
  • 租用戶系統管理員已在 Azure 入口網站 中應用程式註冊的 [API 許可權] 索引標籤中選取 [授與/撤銷 {tenant domain} 的管理員同意;請參閱新增存取 Web API 的許可權。
  • 您提供了讓使用者同意應用程式的方式;請參閱 使用者同意。
  • 您提供了一種方式，讓租用戶系統管理員同意應用程式;請參閱 管理員 istrator 同意。

如需同意的詳細資訊，請參閱 許可權和同意。

後續步驟

瞭解如何取得和快取這些流程中使用的令牌：

使用 Microsoft 驗證連結庫取得和快取權杖 （MSAL）