通过

MSAL 支持的身份验证流

  • 项目

Microsoft 身份验证库（MSAL）支持多种授权授予和关联的令牌流，供不同的应用程序类型和方案使用。

身份验证流 允许 支持的应用程序类型
授权代码 用户登录并代表用户访问 Web API。 * 桌面型
* Mobile
* 单页应用 (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 ID 的计算机上的应用程序以无提示方式获取令牌（无需用户进行任何 UI 交互）。 桌面型、移动型

令牌

应用程序可以使用一个或多个身份验证流。 每个流均使用特定的令牌类型进行身份验证、授权和令牌刷新，某些流还使用授权代码。

身份验证流或操作 需要 ID 令牌 访问令牌 刷新令牌 授权代码
授权代码流 ✅ ✅ ✅ ✅
客户端凭据 ✅（仅限应用）
设备代码流 ✅ ✅ ✅
隐式流 ✅ ✅
代理流 访问令牌 ✅ ✅ ✅
用户名/密码 (ROPC) 用户名、密码 ✅ ✅ ✅
混合 OIDC 流 ✅ ✅
刷新令牌兑换 刷新令牌 ✅ ✅ ✅

交互式和非交互式身份验证

上面的其中一些流既支持交互式令牌获取，又支持非交互式令牌获取。

  • 交互式 - 用户可以由授权服务器提示进行输入。 例如，“若要登录，请执行多重身份验证(MFA)”或“请对更多的资源访问权限授予同意”。
  • 非交互式 - 用户不可以被提示进行输入。 也称为无提示令牌获取，应用程序会尝试使用授权服务器可能无法提示用户输入的方法获取令牌。

基于 MSAL 的应用程序应该会先尝试以无提示方式获取令牌，然后仅在非交互式的尝试失败时才回退到交互式方法。 若要详细了解此模式，请参阅使用 Microsoft 身份验证库 (MSAL) 获取和缓存令牌。

授权代码

Web 应用、单页应用（SPA）和本机（移动和桌面）应用程序可以使用 OAuth 2.0 授权代码授予来访问受保护的资源（如 Web API）。

当用户登录到 Web 应用程序时，该应用程序将收到一个授权代码，此代码可兑换为用于调用 Web API 的访问令牌。

授权代码流示意图

在上图中，应用程序：

  1. 请求一个授权代码，该代码将兑换为访问令牌。
  2. 使用访问令牌调用 Web API，例如 Microsoft Graph。

授权代码的约束

  • 使用授权代码授予流时，单页应用程序需要 Proof Key for 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 客户端凭据流，可通过使用应用程序的标识来访问 Web 托管资源。 这种类型的授权通常用于必须在后台运行的服务器到服务器（S2S）交互，而无需用户立即交互。 这些类型的应用程序通常称为守护程序或服务。

客户端凭据授权流允许 Web 服务（机密客户端）在调用其他 Web 服务时使用它自己的凭据（而不是模拟用户）进行身份验证。 在这种情况下，客户端通常是中间层 Web 服务、后台程序服务或网站。 为了进行更高级别的保证，Microsoft 标识平台还允许调用服务将证书（而不是共享机密）用作凭据。

应用程序密钥

使用密码的机密客户端示意图

在上图中，应用程序：

  1. 使用应用程序机密或密码凭据获取令牌。
  2. 使用令牌发出资源请求。

证书

使用证书的机密客户端示意图

在上图中，应用程序：

  1. 使用证书凭据获取令牌。
  2. 使用令牌发出资源请求。

此类客户端凭据需要：

  • 注册到 Azure AD。
  • 在代码中构造机密客户端应用程序对象时传入。

客户端凭据的约束

在 Android、iOS 或 通用 Windows 平台（UWP）等移动平台上不支持机密客户端流。 移动应用程序被视为无法保证身份验证机密保密的公共客户端应用程序。

设备代码

OAuth 2 设备代码流允许用户登录到受输入约束的设备，例如智能电视、物联网（IoT）设备和打印机。 使用 Microsoft Entra ID 进行的交互式身份验证需要 Web 浏览器。 如果设备或操作系统不提供 Web 浏览器，则设备代码流允许使用其他设备（如计算机或移动电话）以交互方式登录。

应用程序使用设备代码流通过为这些设备和操作系统设计的双步过程获取令牌。

设备代码流示意图

在上图中：

  1. 每当需要用户身份验证时，应用都将提供一个代码，并要求用户使用另一台设备（如已连接到 Internet 的智能手机）访问某个 URL（例如 https://microsoft.com/devicelogin）。 然后，系统会提示用户输入代码，并在必要时继续执行常规身份验证体验，包括许可提示和多重身份验证。
  2. 身份验证成功后，请求的应用程序从Microsoft 标识平台接收所需的令牌，并使用这些令牌执行所需的 Web API 调用。

设备代码的约束

  • 设备代码流仅可用于公共客户端应用程序。
  • 在 MSAL 中初始化公共客户端应用程序时，请使用以下颁发机构格式之一：
    • 基于租户： https://login.microsoftonline.com/{tenant}/, 其中 {tenant} GUID 表示租户 ID 或与租户关联的域名。
    • 工作和学校帐户：https://login.microsoftonline.com/organizations/。

隐式授权

隐式授权已替换为带 PKCE 的授权代码流，后者是客户端单页应用程序 (SPA) 首选的且更安全的令牌授予流。 如果要构建 SPA，请改用带 PCKE 的授权代码流。

使用 JavaScript（包括 Angular、Vue.js 或 React.js 等框架）编写的单页 Web 应用是从服务器下载的，其代码直接在浏览器中运行。 由于其客户端代码在浏览器中运行，而不是在 Web 服务器上运行，因此它们的安全特征与传统服务器端 Web 应用程序不同。 在 Proof Key for Code Exchange (PKCE) 可用于授权代码流之前，SPA 使用隐式授权流来提高获取访问令牌时的响应能力和效率。

使用 OAuth 2 隐式授权流，应用无需执行后端服务器凭据交换即可从 Microsoft 标识平台获取访问令牌。 隐式授权流允许应用从由用户代理（通常是 Web 浏览器）下载并运行的 JavaScript 代码内将用户登录、维护会话，以及为其他 Web API 获取令牌。

隐式授权流示意图

隐式授权的约束

隐式授权流不包括使用跨平台 JavaScript 框架（如 Electron 或 React Native）的应用程序方案。 此类跨平台框架需要其他功能才能与运行本机桌面和移动平台的交互。

通过隐式流模式颁发的令牌存在长度限制，因为它们会返回到 URL 中的浏览器（其中或位置fragmentresponse_modequery）。 某些浏览器会限制浏览器栏中 URL 长度，如果 URL 过长则会失败。 因此，这些隐式流令牌不包含 groups 或 wids 声明。

代理 (OBO)

当应用程序调用服务或 Web API 时，将使用 OAuth 2 代理身份验证流，而服务或 Web API 又需要使用委托的用户标识和需要通过请求链传播的权限调用另一个服务或 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 资源所有者密码凭据 (ROPC) 授权，应用程序可以通过直接处理用户的密码来让用户登录。 在桌面应用程序中，可以使用用户名/密码流以静默方式获取令牌。 使用应用程序时无需 UI。

某些应用程序方案（如 DevOps）可能会发现 ROPC 很有用，但应在为用户登录提供交互式 UI 的任何应用程序中避免它。

用户名/密码流示意图

在上图中，应用程序：

  1. 通过向标识提供者发送用户名和密码来获取令牌。
  2. 使用该令牌调用 Web API。

若要在已加入 Windows 域的计算机上以无提示方式获取令牌，建议 使用 Web 帐户管理器（WAM） 而不是 ROPC。 对于其他方案，请使用设备代码流。

ROPC 的约束

以下约束适用于使用 ROPC 流的应用程序：

  • 单一登录不受支持。
  • 多重身份验证 (MFA) 不受支持。
    • 使用此流之前，请咨询租户管理员 - MFA 是一项常用的功能。
  • 条件访问不受支持。
  • ROPC 仅适用于工作和学校帐户。
  • 个人 Microsoft 帐户 (MSA) 不受 ROPC 支持。
  • .NET 桌面和 .NET 应用程序中支持 ROPC。
  • 通用 Windows 平台 (UWP) 应用程序不支持 ROPC。
  • Microsoft Entra 外部 ID中的 ROPC 仅支持本地帐户。
    • 有关 MSAL.NET 和 Microsoft Entra 外部 ID 中的 ROPC 的信息，请参阅具有 B2C 的资源所有者密码凭据（ROPC）。

集成 Windows 身份验证 (IWA)

注意

集成的 Windows 身份验证已替换为一种更可靠的方式，以无提示方式获取令牌 - WAM。 WAM 可以静默登录当前 Windows 用户。 此工作流不需要复杂的设置，甚至适用于个人帐户（Microsoft）帐户。 在内部，Windows 代理（WAM）将尝试多种策略来获取当前 Windows 用户的令牌，包括 IWA 和兑换 PRT。 这消除了 IWA 的大部分限制。

MSAL 支持在已加入域或已加入 Microsoft Entra ID 的 Windows 计算机上运行的桌面和移动应用程序的集成Windows 身份验证 （IWA）。 这些应用程序可以使用 IWA 以无提示方式获取令牌，无需用户进行任何 UI 交互。

集成 Windows 身份验证的示意图

在上图中，应用程序：

  1. 通过使用集成 Windows 身份验证获取令牌。
  2. 使用令牌发出资源请求。

IWA 的约束

  • 兼容性。 为 .NET 桌面、.NET 和 通用 Windows 平台 （UWP） 应用启用了集成Windows 身份验证 （IWA）。 IWA 仅支持 ADFS 联合用户 - 在 Active Directory 中创建并由 Microsoft Entra ID 提供支持的用户。 直接在 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 格式的租户 ID 或与租户关联的域名。
    • https://login.microsoftonline.com/organizations/ - 此颁发机构指示一个多租户应用程序，其登录受众是任何 Microsoft Entra ID 租户中的用户。
  • 个人帐户。 颁发机构值 不得 包含 /common 或 /consumers 因为 IWA 不支持个人 Microsoft 帐户（MSA）。
  • 同意要求。 由于 IWA 是一个无提示流，因此应用程序的用户必须事先同意使用该应用程序，或者租户管理员必须事先同意租户中的所有用户使用该应用程序。 若要满足任一要求，必须已完成以下任一操作：
    • 作为应用程序开发人员，你已在 Azure 门户中为自己选择了 “授予 ”。
    • 租户管理员已在 Azure 门户中的应用注册的“API 权限”选项卡中选择了“代表 {租户域} 授予/撤销管理员同意”；请参阅添加用于访问 Web API 的权限。
    • 你为用户提供了一种同意应用程序的方法;请参阅Microsoft 标识平台中的权限和同意概述。
    • 你为租户管理员提供了一种方法来同意应用程序;请参阅Microsoft 标识平台中的权限和同意概述。

后续步骤

现在，你已查看 MSAL 支持的身份验证流，了解如何 获取和缓存这些流中使用的令牌。