Microsoft 标识平台和 OAuth 2.0 资源所有者密码凭据Microsoft identity platform and OAuth 2.0 Resource Owner Password Credentials

Microsoft 标识平台支持 OAuth 2.0 资源所有者密码凭据 (ROPC) 授权,后者允许应用程序通过直接处理用户的密码来登录用户。The Microsoft identity platform supports the OAuth 2.0 Resource Owner Password Credentials (ROPC) grant, which allows an application to sign in the user by directly handling their password. 本文介绍如何在应用程序中直接针对协议进行编程。This article describes how to program directly against the protocol in your application. 如果可能,建议你改用受支持的 Microsoft 身份验证库 (MSAL) 来获取令牌并调用受保护的 Web APIWhen possible, we recommend you use the supported Microsoft Authentication Libraries (MSAL) instead to acquire tokens and call secured web APIs. 另请参阅使用 MSAL 的示例应用Also take a look at the sample apps that use MSAL.


Microsoft 建议不要使用 ROPC 流。Microsoft recommends you do not use the ROPC flow. 在大多数情况下,可以使用我们建议的更安全的替代方案。In most scenarios, more secure alternatives are available and recommended. 此流需要应用程序中存在很高程度的信任,并且带有在其他流中不存在的风险。This flow requires a very high degree of trust in the application, and carries risks which are not present in other flows. 仅当无法使用其他更安全的流时,才使用此流。You should only use this flow when other more secure flows can't be used.


  • Microsoft 标识平台仅支持 ROPC 供 Azure AD 租户使用。The Microsoft identity platform only supports ROPC for Azure AD tenants. 这意味着,必须使用特定于租户的终结点 ({TenantId_or_Name}) 或 organizations 终结点。This means that you must use a tenant-specific endpoint ({TenantId_or_Name}) or the organizations endpoint.
  • 没有密码的帐户不能通过 ROPC 登录。Accounts that don't have passwords can't sign in through ROPC. 对于这种情况,建议改用适合应用的其他流。For this scenario, we recommend that you use a different flow for your app instead.
  • 如果用户需使用多重身份验证 (MFA) 来登录应用程序,则系统会改为阻止用户。If users need to use multi-factor authentication (MFA) to log in to the application, they will be blocked instead.
  • 混合联合身份验证方案(例如,用于对本地帐户进行身份验证的 Azure AD 和 ADFS)不支持 ROPC。ROPC is not supported in hybrid identity federation scenarios (for example, Azure AD and ADFS used to authenticate on-premises accounts). 如果用户已整页重定向到本地标识提供者,则 Azure AD 将无法针对该标识提供者测试用户名和密码。If users are full-page redirected to an on-premises identity providers, Azure AD is not able to test the username and password against that identity provider.
  • 混合标识联合身份验证方案的一种例外是:将 AllowCloudPasswordValidation 设置为 TRUE 的 Home Realm Discovery 策略将在本地密码同步到云时使 ROPC 流对联合用户有效。An exception to a hybrid identity federation scenario would be the following: Home Realm Discovery policy with AllowCloudPasswordValidation set to TRUE will enable ROPC flow to work for federated users when on-premises password is synced to cloud. 有关详细信息,请参阅为旧版应用程序启用联合用户的直接 ROPC 身份验证For more information, see Enable direct ROPC authentication of federated users for legacy applications.

协议图Protocol diagram

下图显示了 ROPC 流。The following diagram shows the ROPC flow.


授权请求Authorization request

ROPC 流是单一请求:它将客户端标识和用户的凭据发送到 IDP,然后接收返回的令牌。The ROPC flow is a single request: it sends the client identification and user's credentials to the IDP, and then receives tokens in return. 在这样做之前,客户端必须请求用户的电子邮件地址 (UPN) 和密码。The client must request the user's email address (UPN) and password before doing so. 在成功进行请求之后,客户端应立即以安全方式释放内存中的用户凭据,Immediately after a successful request, the client should securely release the user's credentials from memory. 而不得保存这些凭据。It must never save them.


尝试在 Postman 中执行此请求!Try executing this request in Postman! 尝试在 Postman 中运行此请求Try running this request in Postman

// Line breaks and spaces are for legibility only.  This is a public client, so no secret is required.

POST {tenant}/oauth2/v2.0/token
Content-Type: application/x-www-form-urlencoded

参数Parameter 条件Condition 说明Description
tenant 必选Required 一个目录租户,用户需登录到其中。The directory tenant that you want to log the user into. 此参数可采用 GUID 或友好名称格式。This can be in GUID or friendly name format. 此参数不能设置为 commonconsumers,但可以设置为 organizationsThis parameter can't be set to common or consumers, but may be set to organizations.
client_id 必选Required Azure 门户 - 应用注册页分配给你的应用的应用程序(客户端)ID。The Application (client) ID that the Azure portal - App registrations page assigned to your app.
grant_type 必选Required 必须设置为 passwordMust be set to password.
username 必选Required 用户的电子邮件地址。The user's email address.
password 必选Required 用户的密码。The user's password.
scope 建议Recommended 以空格分隔的范围或权限的列表,这是应用需要的。A space-separated list of scopes, or permissions, that the app requires. 在交互式流中,管理员或用户必须提前同意这些作用域。In an interactive flow, the admin or the user must consent to these scopes ahead of time.
client_secret 有时必需Sometimes required 如果应用是公共客户端,则无法包括 client_secretclient_assertionIf your app is a public client, then the client_secret or client_assertion cannot be included. 如果应用是机密客户端,则它必须包括在内。If the app is a confidential client, then it must be included.
client_assertion 有时必需Sometimes required 使用证书生成的不同形式的 client_secretA different form of client_secret, generated using a certificate. 有关更多详细信息,请参阅证书凭据See certificate credentials for more details.

成功的身份验证响应Successful authentication response

以下示例显示了一个成功的令牌响应:The following example shows a successful token response:

    "token_type": "Bearer",
    "scope": "User.Read profile openid email",
    "expires_in": 3599,
    "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Ik5HVEZ2ZEstZnl0aEV1Q...",
    "refresh_token": "AwABAAAAvPM1KaPlrEqdFSBzjqfTGAMxZGUTdM0t4B4...",
    "id_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJub25lIn0.eyJhdWQiOiIyZDRkMTFhMi1mODE0LTQ2YTctOD..."
参数Parameter 格式Format 说明Description
token_type 字符串String 始终设置为 BearerAlways set to Bearer.
scope 空格分隔的字符串Space separated strings 如果返回了访问令牌,则此参数会列出该访问令牌的有效范围。If an access token was returned, this parameter lists the scopes the access token is valid for.
expires_in intint 包含的访问令牌的有效时间,以秒为单位。Number of seconds that the included access token is valid for.
access_token 不透明字符串Opaque string 针对请求的范围颁发。Issued for the scopes that were requested.
id_token JWTJWT 如果原始 scope 参数包含 openid 范围,则颁发。Issued if the original scope parameter included the openid scope.
refresh_token 不透明字符串Opaque string 如果原始 scope 参数包含 offline_access,则颁发。Issued if the original scope parameter included offline_access.

可以运行 OAuth 代码流文档中描述的同一个流,使用刷新令牌来获取新的访问令牌和刷新令牌。You can use the refresh token to acquire new access tokens and refresh tokens using the same flow described in the OAuth Code flow documentation.

错误响应Error response

如果用户未提供正确的用户名或密码,或者客户端未收到请求的许可,则身份验证会失败。If the user hasn't provided the correct username or password, or the client hasn't received the requested consent, authentication will fail.

错误Error 说明Description 客户端操作Client action
invalid_grant 身份验证失败The authentication failed 凭据不正确,或者客户端没有所请求范围的许可。The credentials were incorrect or the client doesn't have consent for the requested scopes. 如果没有授予范围,则会返回 consent_required 错误。If the scopes aren't granted, a consent_required error will be returned. 如果发生这种情况,客户端应通过 Webview 或浏览器向用户发送交互式提示。If this occurs, the client should send the user to an interactive prompt using a webview or browser.
invalid_request 请求的构造方式不正确The request was improperly constructed 授予类型在 /common/consumers 身份验证上下文中不受支持。The grant type isn't supported on the /common or /consumers authentication contexts. 请改用 /organizations 或租户 ID。Use /organizations or a tenant ID instead.

了解详细信息Learn more

有关使用 ROPC 的示例,请参阅 GitHub 上的 .NET 核心控制台应用程序代码示例。For an example of using ROPC, see the .NET Core console application code sample on GitHub.