身份验证流Authentication flows

Microsoft 身份验证库 (MSAL) 支持在不同的应用程序场景中使用多种身份验证流。The Microsoft Authentication Library (MSAL) supports several authentication flows for use in different application scenarios.

流向Flow 说明Description 适用范围Used in
授权代码Authorization code 在设备上安装的应用中使用,以访问受保护的资源,例如 Web API。Used in apps that are installed on a device to gain access to protected resources, such as web APIs. 使你能够添加对移动应用和桌面应用的登录与 API 访问权限。Enables you to add sign-in and API access to your mobile and desktop apps. 桌面应用移动应用Web 应用Desktop apps, mobile apps, web apps
客户端凭据Client credentials 允许你使用应用程序的标识访问 Web 托管的资源。Allows you to access web-hosted resources by using the identity of an application. 通常用于必须在后台运行的服务器间交互,不需要立即与用户交互。Commonly used for server-to-server interactions that must run in the background, without immediate interaction with a user. 守护程序应用Daemon apps
设备代码Device code 允许用户登录到智能电视、IoT 设备或打印机等输入受限的设备。Allows users to sign in to input-constrained devices such as a smart TV, IoT device, or printer. 桌面/移动应用Desktop/mobile apps
隐式授权Implicit grant 允许应用在不执行后端服务器凭据交换的情况下获取令牌。Allows the app to get tokens without performing a back-end server credential exchange. 使应用能够让用户登录、维护会话,并获取客户端 JavaScript 代码中所有其他 Web API 的令牌。Enables the app to sign in the user, maintain session, and get tokens to other web APIs, all within the client JavaScript code. 单页应用程序 (SPA)Single-page applications (SPA)
代理On-behalf-of 应用程序调用某个服务或 Web API,而后者又需要调用另一个服务或 Web API。An application invokes a service or web API, which in turn needs to call another service or web API. 思路是通过请求链传播委托用户标识和权限。The idea is to propagate the delegated user identity and permissions through the request chain. Web APIWeb APIs
用户名/密码Username/password 允许应用程序通过直接处理用户密码来登录用户。Allows an application to sign in the user by directly handling their password. 不建议使用此流。This flow isn't recommended. 桌面/移动应用Desktop/mobile apps
Windows 集成身份验证Integrated Windows Authentication 允许已加入域或已加入 Azure Active Directory (Azure AD) 的计算机上的应用程序以静默方式获取令牌(无需用户进行任何 UI 交互)。Allows applications on domain or Azure Active Directory (Azure AD) joined computers to acquire a token silently (without any UI interaction from the user). 桌面/移动应用Desktop/mobile apps

每个流如何发出令牌和代码How each flow emits tokens and codes

客户端应用程序根据其生成方式的不同,可以使用 Microsoft 标识平台支持的一种或多种身份验证流。Depending on how your client application is built, it can use one or more of the authentication flows supported by the Microsoft identity platform. 这些流可以生成多种类型的令牌以及授权代码,并需要不同的令牌使其正常工作。These flows can produce several types of tokens as well as authorization codes, and require different tokens to make them work.

流向Flow 需要Requires id_tokenid_token 访问令牌access token 刷新令牌refresh token 授权代码authorization code
授权代码流Authorization code flow xx xx xx xx
客户端凭据Client credentials x(仅限应用)x (app-only)
设备代码流Device code flow xx xx xx
隐式流Implicit flow xx xx
代理流On-behalf-of flow 访问令牌access token xx xx xx
用户名/密码 (ROPC)Username/password (ROPC) 用户名和密码username & password xx xx xx
混合 OIDC 流Hybrid OIDC flow xx xx
刷新令牌兑换Refresh token redemption 刷新令牌refresh token xx xx xx

交互式和非交互式身份验证Interactive and non-interactive authentication

上面的其中一些流既支持交互式令牌获取,又支持非交互式令牌获取。Several of these flows support both interactive and non-interactive token acquisition.

  • 交互式是指用户可以按提示输入信息。Interactive means that the user can be prompted for input. 例如,提示用户登录、执行多重身份验证 (MFA) 或向资源授予其他许可。For example, prompting the user to login, perform multi-factor authentication (MFA), or to grant additional consent to resources.
  • 非交互式(或静默式)身份验证尝试以登录服务器无法提示用户提供其他信息的方式获取令牌 。Non-interactive, or silent, authentication attempts to acquire a token in a way in which the login server cannot prompt the user for additional information.

基于 MSAL 的应用程序应该会先尝试以静默方式获取令牌,然后仅在非交互式方法失败时才采用交互方式。Your MSAL-based application should first attempt to acquire a token silently, and then interactively only if the non-interactive method fails. 若要详细了解此模式,请参阅使用 Microsoft 身份验证库 (MSAL) 获取和缓存令牌For more information about this pattern, see Acquire and cache tokens using the Microsoft Authentication Library (MSAL).

授权代码Authorization code

OAuth 2.0 授权代码授权可用于设备上安装的应用,以获取受保护资源(如 Web API)的访问权限。The OAuth 2 authorization code grant can be used in apps that are installed on a device to gain access to protected resources like web APIs. 这样,就可以添加对移动应用和桌面应用的登录与 API 访问权限。This allows you to add sign-in and API access to your mobile and desktop apps.

当用户登录到 Web 应用程序(网站)时,Web 应用程序会收到授权代码。When users sign in to web applications (websites), the web application receives an authorization code. 兑换该授权代码可获取用于调用 Web API 的令牌。The authorization code is redeemed to acquire a token to call web APIs.

授权代码流示意图

在上图中,应用程序:In the preceding diagram, the application:

  1. 请求授权代码,该代码将兑换为访问令牌。Requests an authorization code, which is redeemed for an access token.
  2. 使用访问令牌调用 Web API。Uses the access token to call a web API.

注意事项Considerations

  • 只能使用授权代码兑换令牌一次。You can use the authorization code only once to redeem a token. 请勿尝试使用同一个授权代码多次获取令牌(因为协议标准规范明确禁止此行为)。Don't try to acquire a token multiple times with the same authorization code because it's explicitly prohibited by the protocol standard specification. 如果你多次用该代码兑换令牌(有意地或者由于你没有意识到框架也在为你兑换令牌),则会收到以下错误:If you redeem the code several times, either intentionally or because you're unaware that a framework also does it for you, you'll get the following error:

    AADSTS70002: Error validating credentials. AADSTS54005: OAuth2 Authorization code was already redeemed, please retry with a new valid code or use an existing refresh token.

客户端凭据Client credentials

利用 OAuth 2 客户端凭据流,可通过使用应用程序的标识来访问 Web 托管资源。The OAuth 2 client credentials flow allows you to access web-hosted resources by using the identity of an application. 这种授予通常用于必须在后台运行的服务器间交互,不需要立即与用户交互。This type of grant is commonly used for server-to-server interactions that must run in the background, without immediate interaction with a user. 此类应用程序通常称为守护程序或服务帐户。These types of applications are often referred to as daemons or service accounts.

客户端凭据授权流允许 Web 服务(机密客户端)在调用其他 Web 服务时使用它自己的凭据(而不是模拟用户)进行身份验证。The client credentials grant flow permits a web service (a confidential client) to use its own credentials, instead of impersonating a user, to authenticate when calling another web service. 在这种情况下,客户端通常是中间层 Web 服务、后台程序服务或网站。In this scenario, the client is typically a middle-tier web service, a daemon service, or a website. 为了进行更高级别的保证,Microsoft 标识平台还允许调用服务将证书(而不是共享机密)用作凭据。For a higher level of assurance, the Microsoft identity platform also allows the calling service to use a certificate (instead of a shared secret) as a credential.

备注

机密客户端流不适用于移动平台(如 UWP、Xamarin.iOS 和 Xamarin.Android),因为它们仅支持公共客户端应用程序。The confidential client flow isn't available on mobile platforms like UWP, Xamarin.iOS, and Xamarin.Android because they support only public client applications. 公共客户端应用程序不知道如何向标识提供者证明应用程序的身份。Public client applications don't know how to prove the application's identity to the identity provider. 可以通过部署证书在 Web 应用或 Web API 后端上实现安全连接。A secure connection can be achieved on web app or web API back-ends by deploying a certificate.

应用程序密钥Application secrets

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

在上图中,应用程序:In the preceding diagram, the application:

  1. 使用应用程序机密或密码凭据获取令牌。Acquires a token by using application secret or password credentials.
  2. 使用令牌发出资源请求。Uses the token to make requests of the resource.

证书Certificates

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

在上图中,应用程序:In the preceding diagram, the application:

  1. 使用证书凭据获取令牌。Acquires a token by using certificate credentials.
  2. 使用令牌发出资源请求。Uses the token to make requests of the resource.

这些客户端凭据需要:These client credentials need to be:

  • 注册到 Azure AD。Registered with Azure AD.
  • 在代码中构造机密客户端应用程序对象时传入。Passed in when constructing the confidential client application object in your code.

设备代码Device code

利用 OAuth 2 设备代码流,用户可以登录到输入受限的设备,如智能电视、IoT 设备和打印机。The OAuth 2 device code flow allows users to sign in to input-constrained devices like smart TVs, IoT devices, and printers. 使用 Azure AD 的交互式身份验证需要 Web 浏览器。Interactive authentication with Azure AD requires a web browser. 如果设备或操作系统不提供 Web 浏览器,设备代码流可让用户使用另一台设备(例如计算机或手机)以交互方式登录。Where the device or operating system doesn't provide a web browser, the device code flow lets the user use another device like a computer or mobile phone to sign in interactively.

应用程序使用设备代码流通过为这些设备和操作系统设计的双步过程获取令牌。By using the device code flow, the application obtains tokens through a two-step process designed for these devices and operating systems. 此类应用程序的示例包括 IoT 设备上运行的应用程序和命令行接口 (CLI) 工具。Examples of such applications include those running on IoT devices and command-line interface (CLI) tools.

设备代码流示意图

在上图中:In the preceding diagram:

  1. 每当需要用户身份验证时,应用都将提供一个代码,并要求用户使用另一台设备(如已连接到 Internet 的智能手机)访问某个 URL(例如 https://microsoft.com/devicelogin)。Whenever user authentication is required, the app provides a code and asks the user to use another device like an internet-connected smartphone to visit a URL (for example, https://microsoft.com/devicelogin). 然后,系统会提示用户输入该代码,并转到完成正常身份验证的体验,包括许可提示和多重身份验证(如果需要)。The user is then prompted to enter the code, and proceeding through a normal authentication experience including consent prompts and multi-factor authentication, if necessary.
  2. 成功完成身份验证后,命令行应用会通过传回通道收到所需的令牌,并使用这些令牌执行所需的 Web API 调用。Upon successful authentication, the command-line app receives the required tokens through a back channel, and uses them to perform the web API calls it needs.

约束Constraints

  • 设备代码流仅在公共客户端应用程序中可用。Device code flow is available only in public client applications.
  • 构造公共客户端应用程序时传入的颁发机构必须是下列其中一项:The authority passed in when constructing the public client application must be one of the following:
    • 租户化(采用 https://login.partner.microsoftonline.cn/{tenant}/, 格式,其中,{tenant} 为表示租户 ID 的 GUID 或与该租户关联的域名)。Tenanted, in the form https://login.partner.microsoftonline.cn/{tenant}/, where {tenant} is either the GUID representing the tenant ID or a domain name associated with the tenant.
    • 对于工作和学校帐户,采用 https://login.partner.microsoftonline.cn/organizations/ 格式。For work and school accounts in the form https://login.partner.microsoftonline.cn/organizations/.

隐式授权Implicit grant

利用 OAuth 2 隐式授权流,应用无需执行后端服务器凭据交换即可从 Microsoft 标识平台获取令牌。The OAuth 2 implicit grant flow allows the app to get tokens from the Microsoft identity platform without performing a back-end server credential exchange. 此流使应用能够让用户登录、维护会话,并获取客户端 JavaScript 代码中所有其他 Web API 的令牌。This flow allows the app to sign in the user, maintain a session, and get tokens for other web APIs, all within the client JavaScript code.

隐式授权流示意图

许多新式 Web 应用程序都是使用 Angular、Vue.js 和 React.js 等 JavaScript 或 SPA 框架编写的客户端单页应用程序 (SPA)。Many modern web applications are built as client-side, single page-applications (SPA) written in JavaScript or an SPA framework such as Angular, Vue.js, and React.js. 这些应用程序在 Web 浏览器中运行,与传统的服务器端 Web 应用程序相比,它们具有不同的身份验证特征。These applications run in a web browser, and have different authentication characteristics than traditional server-side web applications. Microsoft 标识平台可让单页应用程序使用隐式授权流将用户登录,并获取用于访问后端服务或 Web API 的令牌。The Microsoft identity platform enables single page applications to sign in users, and get tokens to access back-end services or web APIs, by using the implicit grant flow. 隐式流允许应用程序获取 ID 令牌来表示已经过身份验证的用户以及调用受保护 API 所需的访问令牌。The implicit flow allows the application to get ID tokens to represent the authenticated user, and also access tokens needed to call protected APIs.

此身份验证流不包括使用 Electron 或 React-Native 之类的跨平台 JavaScript 框架的应用程序场景,因为它们需要使用其他功能才能与本机平台交互。This authentication flow doesn't include application scenarios that use cross-platform JavaScript frameworks like Electron or React-Native because they require further capabilities for interaction with the native platforms.

通过隐式流模式颁发的令牌具有长度限制,因为它们是通过 URL 返回给浏览器的(其中 response_modequeryfragment)。Tokens issued via the implicit flow mode have a length limitation because they're returned to the browser by URL (where response_mode is either query or fragment). 某些浏览器会限制浏览器栏中 URL 长度,如果 URL 过长则会失败。Some browsers limit the length of the URL in the browser bar and fail when it's too long. 因此,这些隐式流令牌不包含 groupswids 声明。Thus, these implicit flow tokens don't contain groups or wids claims.

代理On-behalf-of

当应用程序调用服务或 Web API(该服务或 Web API 继而又需要调用另一个服务或 Web API)时,会使用 OAuth 2 代理身份验证流The OAuth 2 on-behalf-of authentication flow flow is used when an application invokes a service or web API that in turn needs to call another service or web API. 思路是通过请求链传播委托用户标识和权限。The idea is to propagate the delegated user identity and permissions through the request chain. 要使中间层服务向下游服务发出身份验证请求,该服务需要代表用户保护 Microsoft 标识平台提供的访问令牌。For the middle-tier service to make authenticated requests to the downstream service, it needs to secure an access token from the Microsoft identity platform on behalf of the user.

代理流示意图

在上图中:In the preceding diagram:

  1. 应用程序获取 Web API 的访问令牌。The application acquires an access token for the web API.
  2. 客户端(Web、桌面、移动或单页应用程序)调用受保护的 Web API,在 HTTP 请求的身份验证标头中添加访问令牌作为持有者令牌。A client (web, desktop, mobile, or single-page application) calls a protected web API, adding the access token as a bearer token in the authentication header of the HTTP request. Web API 对用户进行身份验证。The web API authenticates the user.
  3. 当客户端调用 Web API 时,Web API 代表用户请求另一个令牌。When the client calls the web API, the web API requests another token on-behalf-of the user.
  4. 受保护的 Web API 使用此令牌代表用户调用下游 Web API。The protected web API uses this token to call a downstream web API on-behalf-of the user. 以后,Web API 也可以请求其他下游 API 的令牌(仍代表同一用户)。The web API can also later request tokens for other downstream APIs (but still on behalf of the same user).

用户名/密码Username/password

利用 OAuth 2 资源所有者密码凭据 (ROPC) 授权,应用程序可以通过直接处理用户的密码来让用户登录。The OAuth 2 resource owner password credentials (ROPC) grant allows an application to sign in the user by directly handling their password. 在桌面应用程序中,可以使用用户名/密码流以静默方式获取令牌。In your desktop application, you can use the username/password flow to acquire a token silently. 使用应用程序时无需 UI。No UI is required when using the application.

用户名/密码流示意图

在上图中,应用程序:In the preceding diagram, the application:

  1. 通过向标识提供者发送用户名和密码来获取令牌。Acquires a token by sending the username and password to the identity provider.
  2. 使用该令牌调用 Web API。Calls a web API by using the token.

警告

不建议使用此流。This flow isn't recommended. 它需要较高级别的信任,并且会透露凭据信息。It requires a high degree of trust and credential exposure. 仅当无法使用更安全的流时,才使用此流。You should use this flow only when more secure flows can't be used. 有关详细信息,请参阅如何解决不断增多的密码问题?For more information, see What's the solution to the growing problem of passwords?.

在已加入 Windows 域的计算机上以静默方式获取令牌的首选流是 Windows 集成身份验证The preferred flow for acquiring a token silently on Windows domain-joined machines is Integrated Windows Authentication. 在其他情况下,请使用设备代码流In other cases, use the device code flow.

尽管用户名/密码流在某些场景(如 DevOps)中可能有用,但如果要在交互式场景中(需要提供自己的 UI)使用用户名/密码,请避免使用它。Although the username/password flow might be useful in some scenarios like DevOps, avoid it if you want to use username/password in interactive scenarios where you provide your own UI.

使用用户名/密码:By using username/password:

  • 需要执行多重身份验证的用户将无法登录(因为没有交互)。Users that need to perform multi-factor authentication won't be able to sign in because there is no interaction.
  • 用户无法执行单一登录。Users won't be able to do single sign-on.

约束Constraints

除了 集成 Windows 身份验证约束以外,还存在以下约束:Apart from the Integrated Windows Authentication constraints, the following constraints also apply:

  • 用户名/密码流与条件访问和多重身份验证不兼容。The username/password flow isn't compatible with Conditional Access and multi-factor authentication. 因此,如果应用在租户管理员要求多重身份验证的 Azure AD 租户中运行,则无法使用此流。As a consequence, if your app runs in an Azure AD tenant where the tenant admin requires multi-factor authentication, you can't use this flow. 许多组织都会要求多重身份验证。Many organizations do that.
  • ROPC 仅适用于工作帐户和学校帐户。ROPC works only for work and school accounts.
  • 可在 .NET Desktop 和 .NET Core 中使用该流,但不能在通用 Windows 平台中使用。The flow is available on .NET desktop and .NET Core, but not on Universal Windows Platform.
  • 在 Azure AD B2C 中,ROPC 流仅适用于本地帐户。In Azure AD B2C, the ROPC flow works only for local accounts. 若要了解 MSAL.NET 和 Azure AD B2C 中的 ROPC,请参阅将 ROPC 与 Azure AD B2C 配合使用For information about ROPC in MSAL.NET and Azure AD B2C, see Using ROPC with Azure AD B2C.

Windows 集成身份验证Integrated Windows Authentication

对于已加入域和已加入 Azure AD 的 Windows 计算机上运行的桌面或移动应用程序,MSAL 支持 Windows 集成身份验证 (IWA)。MSAL supports Integrated Windows Authentication (IWA) for desktop and mobile applications that run on a domain-joined or Azure AD-joined Windows computer. 这些应用程序可以使用 IWA 以静默方式获取令牌(无需要求用户进行任何 UI 交互)。Using IWA, these applications can acquire a token silently without requiring UI interaction by user.

Windows 集成身份验证示意图

在上图中,应用程序:In the preceding diagram, the application:

  1. 使用 Windows 集成身份验证获取令牌。Acquires a token by using Integrated Windows Authentication.
  2. 使用令牌发出资源请求。Uses the token to make requests of the resource.

约束Constraints

集成 Windows 身份验证 (IWA) 仅支持联合用户 - 在 Active Directory 中创建的并由 Azure AD 支持的用户。Integrated Windows Authentication (IWA) supports federated users only - users created in Active Directory and backed by Azure AD. 直接在 Azure AD 中创建的但不是由 Active Directory 支持的用户(托管用户)不能使用此身份验证流。Users created directly in Azure AD without Active Directory backing (managed users) can't use this authentication flow. 此项限制不影响用户名/密码流This limitation doesn't affect the username/password flow.

IWA 适用于 .NET Framework、.NET Core 和通用 Windows 平台应用程序。IWA is for .NET Framework, .NET Core, and Universal Windows Platform applications.

IWA 不会绕过多重身份验证。IWA doesn't bypass multi-factor authentication. 如果配置了多重身份验证,需要多重身份验证质询时,IWA 可能会失败。If multi-factor authentication is configured, IWA might fail if a multi-factor authentication challenge is required. 多重身份验证需要用户交互。Multi-factor authentication requires user interaction.

你无法控制标识提供者何时请求执行双重身份验证,You don't control when the identity provider requests two-factor authentication to be performed. 租户管理员可以对此进行控制。The tenant admin does. 通常,在以下情况下需要双因素身份验证:当你从不同国家/地区登录时;未通过 VPN 连接到公司网络时;有时甚至通过 VPN 连接也会需要双因素身份验证。Typically, two-factor authentication is required when you sign in from a different country/region, when you're not connected via VPN to a corporate network, and sometimes even when you are connected via VPN. Azure AD 使用 AI 来持续了解是否需要双重身份验证。Azure AD uses AI to continuously learn if two-factor authentication is required. 如果 IWA 失败,你将回退到交互式用户提示If IWA fails, you should fall back to an interactive user prompt.

构造公共客户端应用程序时传入的颁发机构必须为以下其中一项:The authority passed in when constructing the public client application must be one of:

  • 租户化(采用 https://login.partner.microsoftonline.cn/{tenant}/, 格式,其中,{tenant} 为表示租户 ID 的 GUID 或与该租户关联的域名)。Tenanted, in the form https://login.partner.microsoftonline.cn/{tenant}/, where {tenant} is either the GUID representing the tenant ID or a domain name associated with the tenant.
  • 适用于任何工作和学校帐户 (https://login.partner.microsoftonline.cn/organizations/)。For any work and school accounts (https://login.partner.microsoftonline.cn/organizations/).

由于 IWA 是一个静默流,因此必须符合以下条件之一:Because IWA is a silent flow, one of the following must be true:

  • 应用程序的用户必须已事先许可使用该应用程序。The user of your application must have previously consented to use the application.
  • 租户管理员必须已事先许可租户中的所有用户使用该应用程序。The tenant admin must have previously consented to all users in the tenant to use the application.

这意味着需要符合以下条件之一:This means that one of the following is true:

  • 开发人员已在 Azure 门户中自行选择“授权”。You as a developer have selected Grant in the Azure portal for yourself.
  • 租户管理员已在 Azure 门户中的应用注册的“API 权限”选项卡中选择了“授予/撤销 {租户域} 的管理员许可”(请参阅添加用于访问 Web API 的权限) 。A tenant admin has selected Grant/revoke admin consent for {tenant domain} in the API permissions tab of the app registration in the Azure portal (see Add permissions to access web APIs).
  • 你已提供某种方式让用户同意应用程序(请参阅请求个人用户同意)。You've provided a way for users to consent to the application; see Requesting individual user consent.
  • 你已提供某种方式让租户管理员同意应用程序(请参阅管理员同意)。You've provided a way for the tenant admin to consent for the application; see admin consent.

已针对 .NET Desktop、.NET Core 和 Windows 通用平台应用启用 IWA 流。The IWA flow is enabled for .NET desktop, .NET Core, and Windows Universal Platform apps. 在 .NET Core 上,必须向 IWA 提供用户名,因为 .NET Core 无法从操作系统获取用户名。On .NET Core you must provide the username to IWA, because .NET Core can't obtain usernames from the operating system.

有关同意的详细信息,请参阅 v2.0 权限和同意For more information on consent, see v2.0 permissions and consent.

后续步骤Next steps

现在,你已经了解了 Microsoft 身份验证库 (MSAL) 支持的身份验证流,接下来了解有关获取和缓存在这些流中使用的令牌的信息:Now that you've reviewed authentication flows supported by the Microsoft Authentication Library (MSAL), learn about acquiring and caching the tokens used in these flows:

使用 Microsoft 身份验证库 (MSAL) 获取和缓存令牌Acquire and cache tokens using the Microsoft Authentication Library (MSAL)