MSAL 中支持的驗證流程

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

身份驗證流程 Enables 支援的應用程式類型
授權碼 使用者代表使用者登入和存取 Web API。 * 桌面
* 行動裝置
* 單頁應用程式 (SPA) ( 需要 PKCE)
* 網
用戶端認證 使用應用程式本身的身分識別來存取 Web API。 通常用於伺服器對伺服器通訊以及不需要使用者互動的自動化指令碼。 Daemon
裝置代碼 在輸入受限的裝置上,例如智慧電視和物聯網(IoT)裝置,使用者可以代表其他使用者登入並存取 Web API。 也供命令列介面 (CLI) 應用程式使用。 桌面、行動
隱含授與 使用者登入以及代表使用者存取 Web API。 不再建議使用隱含授與流程 - 請改用授權碼搭配 Code Exchange 證明金鑰 (PKCE)。 * 單頁應用程式 (SPA)
* 網
代表 (OBO) 代表使用者從「上游」Web API 存取「下游」Web API。 使用者的身分識別和委派的權限會從上游 API 傳遞至下游 API。 網路API
使用者名稱/密碼 (ROPC) 可讓應用程式直接處理其密碼來登入使用者。 不建議使用 ROPC 流程。 桌面、行動
整合式 Windows 驗證 (IWA) 允許域或 Microsoft Entra ID 加入的電腦上的應用程式,無需使用者介面互動即可靜默地獲取 Token。 桌面、行動

Tokens

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

驗證流程或動作 Requires 身份驗證憑證 存取憑證 重新整理權杖 授權碼
授權碼流程 ✅ ✅ ✅ ✅
用戶端認證 ✅ (僅限 app)
裝置程式代碼流程 ✅ ✅ ✅
隱含流程 ✅ ✅
以他者名義的流程 存取憑證 ✅ ✅ ✅
使用者名稱/密碼 (ROPC) 使用者名稱、密碼 ✅ ✅ ✅
混合式 OIDC 流程 ✅ ✅
更新令牌兌換 重新整理權杖 ✅ ✅ ✅

互動式與非互動式驗證

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

  • 互動式 - 授權伺服器可能會提示使用者輸入。 例如,若要登入、執行多重要素驗證(MFA)或授予更多資源存取權限。
  • 非互動式 - 使用者 可能不會 提示輸入。 也稱為 無訊息令牌擷取,應用程式會嘗試透過授權伺服器 可能不會 提示使用者輸入的方法來取得令牌。

MSAL 型應用程式應該會先嘗試以靜默方式取得權杖,並且只有在非互動式嘗試失敗時,才會退回到使用互動式方法。 如需此模式的詳細資訊,請參閱使用 Microsoft 驗證程式庫 (MSAL) 來獲取和快取權杖。

授權碼

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

使用者登入 Web 應用程式時,應用程式會接收到授權碼,而此授權碼可兌換存取權杖來呼叫 Web API。

授權碼流程圖

在上圖中,應用程式:

  1. 請求授權碼以兌換取得存取令牌。
  2. 使用存取令牌來呼叫 Web API,例如 Microsoft Graph。

授權碼的條件約束

  • 使用授權碼授與流程時,單頁應用程式需要代碼交換證明金鑰 (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 用戶端認證流程可讓您使用應用程式的身分識別來存取 Web 裝載的資源。 這種類型的授權通常用於伺服器對伺服器(S2S)必須在背景中執行的互動,且不需要使用者立即互動。 這些類型的應用程式通常稱為精靈或服務。

用戶端認證授與流程可允許 Web 服務 (機密用戶端) 在呼叫另一個 Web 服務時,使用自己的認證來進行驗證,而不是模擬使用者。 在此案例中,用戶端通常是中介層 Web 服務、精靈服務或網站。 對於較高層級的保證,Microsoft 身分識別平台也可讓呼叫服務使用憑證 (而非共用密碼) 做為認證。

應用程式祕密

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

在上圖中,應用程式:

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

Certificates

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

在上圖中,應用程式:

  1. 使用證書憑證來獲取令牌。
  2. 使用令牌來提出資源要求。

這種類型的用戶端認證必須是:

  • 向 Azure AD 註冊。
  • 在程式代碼中建構機密用戶端應用程式物件時傳入。

用戶端認證的條件約束

Android、iOS 或通用 Windows 平臺 (UWP) 等行動平台 不支援 機密用戶端流程。 行動應用程式被視為無法保證驗證秘密機密性的公用用戶端應用程式。

裝置代碼

OAuth 2 裝置程式碼流程可讓使用者登入輸入限制的裝置,例如智慧型手機電視、物聯網 (IoT) 裝置和印表機。 使用 Microsoft Entra ID 的互動式驗證需要網頁瀏覽器。 當裝置或作系統未提供網頁瀏覽器時,裝置程式代碼流程可讓您使用其他裝置,例如電腦或行動電話,以互動方式登入。

使用裝置驗證碼流程,應用程式就能透過針對這些裝置與作業系統所設計的雙步驟流程來取得權杖。

裝置程式代碼流程的圖表

在上圖中:

  1. 每當需要使用者驗證時,應用程式就會提供驗證碼,並要求使用者使用另一部裝置 (例如:網際網路連線的智慧型手機) 前往 URL (例如:https://microsoft.com/devicelogin)。 然後,系統會提示使用者輸入程序代碼,並視需要繼續進行一般驗證體驗,包括同意提示和多重要素驗證。
  2. 成功驗證后,要求的應用程式會從Microsoft身分識別平臺接收所需的令牌,並使用它們來執行所需的Web API呼叫。

裝置代碼的條件約束

  • 裝置代碼流程僅適用於公用用戶端應用程式。
  • 當您以 MSAL 初始化公用用戶端應用程式時,請使用下列其中一種授權單位格式:
    • 以租戶為基礎:https://login.microsoftonline.com/{tenant}/, 其中 {tenant} 是代表租戶 ID 的 GUID 或與租戶相關聯的網域名稱。
    • 公司和學校帳戶:https://login.microsoftonline.com/organizations/。

隱含授與

隱含授與已由 授權碼流程取代為 PKCE ,作為用戶端單頁應用程式 (SPA) 慣用且更安全的令牌授與流程。 如果您要建置 SPA,請改為使用 PKCE 的授權碼流程。

以 JavaScript 撰寫的單頁 Web 應用程式 (包括 Angular、Vue.js 或 React.js 這類架構) 下載自伺服器,而且其程式碼會直接在瀏覽器中執行。 因為其用戶端程式碼會在瀏覽器中執行,而不是在網頁伺服器上,所以其安全性特性與傳統伺服器端 Web 應用程式不同。 在授權碼流程的代碼交換證明金鑰 (PKCE) 可供使用之前,SPA 使用隱含授與流程來改善取得存取權杖的回應性和效率。

OAuth 2 隱含授與流程可讓應用程式從Microsoft身分識別平臺取得存取令牌,而不需要執行後端伺服器認證交換。 隱含授權流程允許應用程式登入使用者、維持會話,並從使用者代理程式(通常是網頁瀏覽器)下載並執行的 JavaScript 代碼中獲取其他網路 API 的權杖。

隱含授與流程的圖表

隱含授權的限制條件

隱含授與流程不包括使用 Electron 或 React Native 這類跨平台 JavaScript 架構的應用程式案例。 這類跨平台架構需要額外的功能,才能與其執行所在的原生桌面和行動平台互動。

透過隱含流程模式發出的令牌有 長度限制 ,因為它們會傳回URL中的瀏覽器(其中 response_mode 為 query 或 fragment)。 某些瀏覽器會限制瀏覽器列中的 URL 長度,而長度太長就會失敗。 因此,這些隱含流程權杖不包含 groups 或 wids 宣告。

代替 (OBO)

當應用程式叫用服務或 Web API 時,會使用 OAuth 2 代理驗證流程。此流程允許應用程式使用委派的使用者身分和需透過要求鏈結傳播的許可權,呼叫另一個服務或 Web API。 若要讓中介層服務向後端服務提出已驗證的要求,它必須代表要求的使用者從 Microsoft 身分識別平台取得存取令牌。

代表流程的圖表

在上圖中:

  1. 應用程式會取得 Web API 的存取權杖。
  2. 用戶端(網頁、桌面、行動或單頁應用程式)會呼叫受保護的網頁 API,並將存取權杖作為承載權杖新增到 HTTP 請求的驗證標頭中。 Web API 會驗證使用者。
  3. 當用戶端呼叫 Web API 時,Web API 會代表使用者要求另一個令牌。
  4. 受保護的 Web API 會使用此令牌代表使用者呼叫下游 Web API。 網路 API 稍後還可以代表同一位使用者,向其他下游 API 請求權杖。

使用者名稱/密碼 (ROPC)

Warning

不再建議使用資源擁有者密碼認證 (ROPC) 流程。 ROPC 需要高度的信任與認證公開程度。 只有在無法使用更安全的流程時,才使用 ROPC。 如需詳細資訊,請參閱持續增加的密碼問題有何解決方案?。

OAuth 2 資源擁有者密碼憑證(ROPC)授權可讓應用程式透過直接處理密碼來讓使用者登入。 在桌面應用程式中,您可以使用使用者名稱/密碼流程,以靜默方式取得權杖。 使用此應用程式時不需要 UI。

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

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

在上圖中,應用程式:

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

若要在已加入網域的 Windows 計算機上以無訊息方式取得令牌,建議您 使用 Web 帳戶管理員 (WAM) 而不是 ROPC。 針對其他案例,請使用裝置代碼流程。

ROPC 的條件約束

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

  • 「不支援」單一登入。
  • 不支援多重要素驗證 (MFA)。
    • 請先洽詢您的租用戶管理員,再使用此流程 - MFA 是常用的功能。
  • 「不支援」條件式存取。
  • ROPC「僅」適用於公司和學校帳戶。
  • ROPC「不支援」個人 Microsoft 帳戶 (MSA)。
  • ROPC 在 .NET 桌面應用程式和 .NET 應用程式中受到 支援。
  • 通用 Windows 平台 (UWP) 應用程式「不支援」ROPC。
  • 在 Microsoft Entra 外部 ID 中,ROPC 僅適用於本機帳戶。

整合式 Windows 驗證 (IWA)

Note

整合式 Windows 驗證已被以更可靠且無訊息方式取得令牌的 WAM 取代。 WAM 可以以無訊息方式登入目前的 Windows 使用者。 此工作流程不需要複雜的設定,甚至適用於個人 (Microsoft) 帳戶。 在內部,Windows Broker (WAM) 會嘗試數種策略來取得目前 Windows 使用者的令牌,包括 IWA 和兌換 PRT。 這可消除 IWA 的大部分限制。

MSAL 支援在已加入網域或 Microsoft Entra ID 加入的 Windows 電腦上運行的桌面和行動應用程式使用整合式 Windows 驗證 (IWA)。 這些應用程式透過使用 IWA,可在不需要使用者與使用者界面互動下,靜默地取得權杖。

整合式 Windows 驗證的圖表

在上圖中,應用程式:

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

IWA 的條件約束

  • 相容性。 整合式 Windows 驗證 (IWA) 已針對 .NET 桌面、.NET 和通用 Windows 平臺 (UWP) 應用程式啟用。 IWA 僅 支援 ADFS 同盟使用者 - 在 Active Directory 中建立且由 Microsoft Entra 識別碼所支援的使用者。 直接在 Microsoft Entra ID 中建立但不受 Active Directory 支援的使用者 (受管理的使用者),無法使用此驗證流程。
  • 多重要素驗證 (MFA) 。 如果在 Microsoft Entra ID 租戶中啟用 MFA,且 Microsoft Entra ID 發出 MFA 挑戰,IWA 非互動式(靜默)驗證可能會失敗。 如果 IWA 失敗,則您應該回復為先前所述的互動式驗證方法。 Microsoft Entra ID 使用 AI 來判斷何時需要雙重要素驗證。 當使用者從不同的國家/地區登入、連線到公司網路而不使用 VPN 時,有時透過 VPN 連線時,通常需要雙因素驗證。 由於 MFA 的組態和挑戰頻率可能不在您作為開發人員的控制範圍內,因此您的應用程式應該能夠正常處理 IWA 無訊息令牌擷取失敗的情況。
  • 授權單位 URI 限制。 建構公用用戶端應用程式時傳入的授權單位必須是下列其中一項:
    • https://login.microsoftonline.com/{tenant}/ - 此權限指出單一租戶應用程式,其登入對象僅限於指定的 Microsoft Entra ID 租戶中的用戶。 {tenant} 值可以是 GUID 形式的租用戶識別碼,或是與租用戶相關聯的網域名稱。
    • https://login.microsoftonline.com/organizations/ - 此授權單位意味著多租戶應用程式,其登入對象是任何 Microsoft Entra ID 租戶中的使用者。
  • 個人帳戶。 授權單位值 不得 包含 /common 或 /consumers ,因為 IWA 不支援個人Microsoft帳戶 (MSA)。
  • 同意要求。 由於 IWA 是靜默流程,因此應用程式的使用者先前必須已同意使用該應用程式,或者租戶系統管理員先前必須已同意租戶內所有使用者使用該應用程式。 若要滿足任一需求,下列其中一項作業必須已完成:

下一步

既然您已檢閱 MSAL 支援的驗證流程,請了解如何取得和快取這些流程中使用的令牌。