learn.microsoft.com Open in urlscan Pro
2a02:26f0:6c00:1b4::3544  Public Scan

Form analysis
0 forms found in the DOM

Text Content

Skip to main content


This browser is no longer supported.

Upgrade to Microsoft Edge to take advantage of the latest features, security
updates, and technical support.

Download Microsoft Edge More info about Internet Explorer and Microsoft Edge

Table of contents Exit focus mode

Read in English Save
Table of contents Read in English Save Edit Print

Twitter LinkedIn Facebook Email
Table of contents


MICROSOFT IDENTITY PLATFORM AND OAUTH 2.0 RESOURCE OWNER PASSWORD CREDENTIALS

 * Article
 * 01/27/2023
 * 18 contributors

Feedback



IN THIS ARTICLE

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. When possible, we recommend you use
the supported Microsoft Authentication Libraries (MSAL) instead to acquire
tokens and call secured web APIs. Also take a look at the sample apps that use
MSAL.

Warning

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 that are not present
in other flows. You should only use this flow when other more secure flows
aren't viable.

Important

 * The Microsoft identity platform only supports the ROPC grant within Azure AD
   tenants, not personal accounts. This means that you must use a
   tenant-specific endpoint
   (https://login.microsoftonline.com/{TenantId_or_Name}) or the organizations
   endpoint.
 * Personal accounts that are invited to an Azure AD tenant can't use the ROPC
   flow.
 * Accounts that don't have passwords can't sign in with ROPC, which means
   features like SMS sign-in, FIDO, and the Authenticator app won't work with
   that flow. If your app or users require these features, use a grant type
   other than ROPC.
 * If users need to use multi-factor authentication (MFA) to log in to the
   application, they will be blocked instead.
 * ROPC is not supported in hybrid identity federation scenarios (for example,
   Azure AD and ADFS used to authenticate on-premises accounts). If users are
   full-page redirected to an on-premises identity provider, Azure AD is not
   able to test the username and password against that identity provider.
   Pass-through authentication is supported with ROPC, however.
 * 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 an on-premises
   password is synced to the cloud. For more information, see Enable direct ROPC
   authentication of federated users for legacy applications.
 * Passwords with leading or trailing whitespaces are not supported by the ROPC
   flow.

Tip


Try executing this request and more in Postman -- don't forget to replace tokens
and IDs!


PROTOCOL DIAGRAM

The following diagram shows the ROPC flow.




AUTHORIZATION REQUEST

The ROPC flow is a single request; it sends the client identification and user's
credentials to the identity provider, and receives tokens in return. The client
must request the user's email address (UPN) and password before doing so.
Immediately after a successful request, the client should securely discard the
user's credentials from memory. It must never save them.

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

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

client_id=6731de76-14a6-49ae-97bc-6eba6914391e
&scope=user.read%20openid%20profile%20offline_access
&username=MyUsername@myTenant.com
&password=SuperS3cret
&grant_type=password


Parameter Condition Description tenant Required The directory tenant that you
want to log the user into. The tenant can be in GUID or friendly name format.
However, its parameter can't be set to common or consumers, but may be set to
organizations. client_id Required The Application (client) ID that the Azure
portal - App registrations page assigned to your app. grant_type Required Must
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 If your app is a public client, then the client_secret or
client_assertion can't be included. If the app is a confidential client, then it
must be included. client_assertion Sometimes required A different form of
client_secret, generated using a certificate. For more information, see
certificate credentials.

Warning

As part of not recommending this flow for use, the official SDKs do not support
this flow for confidential clients, those that use a secret or assertion. You
may find that the SDK you wish to use does not allow you to add a secret while
using ROPC.


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 Always 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 int Number of seconds that the
included access token is valid for. access_token Opaque string Issued for the
scopes that were requested. id_token JWT Issued if the original scope parameter
included the openid scope. refresh_token Opaque string Issued if the original
scope parameter included offline_access.

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.

Warning

Don't attempt to validate or read tokens for any API you don't own, including
the tokens in this example, in your code. Tokens for Microsoft services can use
a special format that will not validate as a JWT, and may also be encrypted for
consumer (Microsoft account) users. While reading tokens is a useful debugging
and learning tool, do not take dependencies on this in your code or assume
specifics about tokens that aren't for an API you control.


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. If the scopes aren't granted, a consent_required error will be returned.
To resolve this error, the client should send the user to an interactive prompt
using a webview or browser. invalid_request The request was improperly
constructed The grant type isn't supported on the /common or /consumers
authentication contexts. Use /organizations or a tenant ID instead.


LEARN MORE

For an example implementation of the ROPC flow, see the .NET Core console
application code sample on GitHub.






FEEDBACK

Submit and view feedback for

This product This page
View all page feedback

--------------------------------------------------------------------------------


ADDITIONAL RESOURCES





Theme
 * Light
 * Dark
 * High contrast

 * 
 * Previous Versions
 * Blog
 * Contribute
 * Privacy
 * Terms of Use
 * Trademarks
 * © Microsoft 2023


ADDITIONAL RESOURCES






IN THIS ARTICLE



Theme
 * Light
 * Dark
 * High contrast

 * 
 * Previous Versions
 * Blog
 * Contribute
 * Privacy
 * Terms of Use
 * Trademarks
 * © Microsoft 2023