共用方式為

MSAL 中的驗證流程支援

  • 發行項

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

驗證流程 啟用 支援的應用程式類型
授權碼 代表使用者的 Web API 使用者登入和存取。 Desktop (電腦)
行動
單頁應用程式 (SPA)(需要 PKCE)
Web
用戶端認證 使用應用程式本身的身分識別來存取 Web API。 通常用於伺服器對伺服器通訊以及不需要使用者互動的自動化指令碼。 精靈
裝置代碼 輸入受限裝置 (例如智慧型電視和 IoT 裝置) 上代表使用者的 Web API 使用者登入和存取。 也供命令列介面 (CLI) 應用程式使用。 傳統型、行動
隱含授與 代表使用者的 Web API 使用者登入和存取。 請勿使用此流程 - 請改用具有 PKCE 的授權碼。 * 單頁應用程式 (SPA)
* Web
代理者 (OBO) 代表使用者從「上游」Web API 存取「下游」Web API。 使用者的身分識別和委派的權限會從上游 API 傳遞至下游 API。 Web API
使用者名稱/密碼 (ROPC) 可讓應用程式直接處理其密碼來登入使用者。 請勿使用此流程。 傳統型、行動
整合式 Windows 驗證 (IWA) 允許已加入網域或 Microsoft Entra 電腦上的應用程式以無訊息方式取得權杖 (使用者不需要進行任何 UI 互動)。 傳統型、行動

語彙基元

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

驗證流程或動作 需要 識別碼權杖 存取權杖 重新整理權杖 授權碼
授權碼流程 驗證流程適用於標識碼權杖 驗證流程適用於存取權杖 驗證流程適用於重新整理權杖 授權碼流程
用戶端認證 驗證流程適用於存取權杖 (僅限應用程式)
裝置碼流程 驗證流程適用於標識碼權杖 驗證流程適用於存取權杖 驗證流程適用於重新整理權杖
隱含流程 驗證流程適用於標識碼權杖 驗證流程適用於存取權杖
代理者流程 存取權杖 驗證流程適用於標識碼權杖 驗證流程適用於存取權杖 驗證流程適用於重新整理權杖
使用者名稱/密碼 (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.0 用戶端認證流程可讓您使用應用程式的身分識別來存取裝載於 Web 的資源。 這類型的授與通常用於必須在背景中執行 (不需與使用者直接互動) 的伺服器對伺服器互動。 這些類型的應用程式通常稱為精靈或服務帳戶。

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

應用程式祕密

在下圖中，應用程式：

  1. 使用應用程式秘密或密碼認證來取得權杖
  2. 使用權杖來提出資源的要求

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

憑證

在下圖中，應用程式：

  1. 使用憑證認證來取得權杖
  2. 使用權杖來提出資源的要求

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

這些用戶端認證必須：

  • 使用 Microsoft Entra ID 註冊
  • 在程式碼中建構機密用戶端應用程式物件時傳入

用戶端認證的條件約束

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 應用程式不同。 在授權碼流程的代碼交換證明金鑰 (PKCE) 可供使用之前，SPA 使用隱含授與流程來改善取得存取權杖的回應性和效率。

OAuth 2.0 隱含授與流程可讓應用程式從 Microsoft 身分識別平台取得存取權杖，而不需要執行後端伺服器認證交換。 隱含授與流程允許應用程式登入使用者、維護工作階段，以及從使用者代理程式 (通常是網頁瀏覽器) 所下載並執行的 JavaScript 程式碼內取得其他 Web API 的權杖。

隱含授與流程的圖表

隱含授與的條件約束

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

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

代理者 (OBO)

當應用程式叫用服務或 Web API，而後者又需要呼叫另一個服務或 Web API 時，會使用 OAuth 2.0 代理者驗證流程。 其概念是透過要求鏈傳播委派的使用者身分識別和權限。 若中介層服務要向下游服務提出已驗證的要求，其需要「代表」使用者保護來自 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)

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

警告

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

在下圖中，應用程式：

  1. 藉由將使用者名稱和密碼傳送給識別提供者來取得權杖
  2. 使用權杖來呼叫 Web API

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

若要在已加入 Windows 網域的機器上以無訊息方式取得權杖，建議使用整合式 Windows 驗證 (IWA)，而非 ROPC。 針對其他案例，請使用裝置代碼流程。

ROPC 的條件約束

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

  • 「不支援」單一登入。
  • 「不支援」多重要素驗證 (MFA)。
    • 請先洽詢您的租用戶管理員，再使用此流程 - MFA 是常用的功能。
  • 「不支援」條件式存取。
  • ROPC「僅」適用於公司和學校帳戶。
  • ROPC「不支援」個人 Microsoft 帳戶 (MSA)。
  • .NET 傳統型和 ASP.NET Core 應用程式「支援」ROPC。
  • 通用 Windows 平台 (UWP) 應用程式「不支援」ROPC。
  • 「只」有本機帳戶才支援 Azure AD B2C 中的 ROPC。

整合式 Windows 驗證 (IWA)

針對已加入網域或已加入 Microsoft Entra 的 Windows 電腦上執行的傳統型和行動應用程式，MSAL 支援整合式 Windows 驗證 (IWA)。 這些應用程式使用 IWA，即可以無訊息方式取得權杖，而不需要使用者與 UI 互動。

在下圖中，應用程式：

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

整合式 Windows 驗證的圖表。

IWA 的條件約束

相容性

已針對 .NET 傳統型、.NET 和 Windows 通用平台應用程式啟用整合式 Windows 驗證 (IWA)。

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 來判斷何時需要雙重要素驗證。 使用者從不同的國家/地區登入時、在未使用 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。
  • 您已為使用者提供同意應用程式的方式：請參閱 使用者同意。
  • 您也已為租用戶系統管理員提供同意應用程式的方式；請參閱 管理員同意。

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

後續步驟

了解如何取得和快取用在這些流程裡的權杖：

使用 Microsoft 驗證程式庫 (MSAL) 取得及快取權杖