How to implement the Resource Owner Password Grant
In this tutorial, we will go through the steps required to implement the Resource Owner Password Grant.
You should use this flow only if the following apply:
- The application is absolutely trusted with the user's credentials. For Single-Page Apps and Native/Mobile Apps, we recommend using web flows instead.
- Using a redirect-based flow is not possible. If this is not the case and redirects are possible in your application, you should use the Authorization Code Flow instead.
Before you start
- Check that your application's grant type property is set appropriately
- Register the API with Auth0
- Check that the Default Audience and/or Default Directory has been set appropriately
- Update or disable any rules, such as rules that deny access based on an email domain whitelist, so they only impact specific connections. If you get an
'access_denied'error when testing the Password Grant, this could be due to an access control rule.
Configure your tenant
The Password Grant relies on a connection capable of authenticating users via username and password. In order to indicate which connection the Password Grant should use you need to set the value of the
default_directory tenant setting.
- Open the Dashboard and browse to your Tenant Settings.
- Scroll down to the Settings section and locate the Default Directory setting.
- Enter the name of the connection you would like to use. Keep in mind that only connections capable of authenticating users via username and password can be used (such as database connections, AD, LDAP, Windows Azure AD, ADFS)
Ask for a Token
In order to execute the flow the application needs to acquire the Resource Owner's credentials, usually this will be through the use of an interactive form. Once the application has the credentials it needs to forward them to Auth0 with a
POST to the /oauth/token endpoint of Auth0's Authentication API.
grant_type: This must be
username: The end user's identifier.
password: The end user's password.
audience: The Identifier value on the Settings tab for the API you created as part of the prerequisites for this tutorial.
client_id: Your application's Client ID. You can find this value at the Settings tab of the Machine to Machine Application.
client_secret: Your application's Client Secret. You can find this value at the Settings tab of the Machine to Machine Application. This is required when the Token Endpoint Authentication Method field at your Application Settings is
Basic. Do not set this parameter if your application is not highly trusted (for example, SPA).
scope: String value of the different scopes the application is asking for. Multiple scopes are separated with whitespace.
In case the scopes issued to the application differ from the scopes requested, a
scope parameter will be included in the response JSON, listing the issued scopes.
Password grant and standard scopes
If no API scopes (such as
read:notes) are included in the request, all API scopes (such as
create:notes, and so on.) are included in the Access Token.
If only the
openid scope is included in the request, all
openid standard scopes will be returned, such as
openid profile email address phone.
In these cases, the
scope parameter will be included in the response, listing the issued scopes. This happens because a password is equal to full access and hence any password-based exchange gives access to all scopes.
How to get the user's claims
If you need the user's claims you can include the scope
openid to your request. If the API uses
RS256 as the signing algorithm, the Access Token will now also include
/userinfo as a valid audience. You can use this Access Token to invoke the /userinfo endpoint and retrieve the user's claims.
A extension grant that offers similar functionality with the Resource Owner Password Grant, including the ability to indicate a specific realm, is the
Realms allow you to keep separate user directories and specify which one to use to the token endpoint.
To use this variation you will have to change the following request parameters:
- Set the
- Set the new request parameter
realmto the realm the user belongs. This maps to a connection in Auth0. For example, if you have configured a database connection for your internal employees and you have named the connection
employees, then use this value.
Auth0 Connections as Realms
Use the token
Once the Access Token has been obtained it can be used to make calls to the Resource Server by passing it as a Bearer Token in the
Authorization header of the HTTP request:
Verify the token
Once your API receives a request with a Bearer Access Token, the first thing to do is to validate the token. This consists of a series of steps, and if any of these fails then the request must be rejected.
For details on the validations that should be performed by the API, refer to Verify Access Tokens.
Optional: Customize the Tokens
You can use Rules to change the returned scopes of the Access Token and/or add claims to it (and the ID Token) with a script like this:
Namespacing Custom Claims
Auth0 returns profile information in a structured claim format as defined by the OIDC specification. This means that in order to add custom claims to ID Tokens or Access Tokens, they must conform to a namespaced format to avoid possible collisions with standard OIDC claims. For example, if you choose the namespace
https://foo.com/ and you want to add a custom claim named
myclaim, you would name the claim
https://foo.com/myclaim, instead of
myclaim. You can add namespaced claims using Rules.
If you wish to execute special logic unique to the Password exchange, you can look at the
context.protocol property in your rule. If the value is
oauth2-password, then the rule is running during the password exchange.
Optional: Configure MFA
In case you need stronger authentication, than username and password, you can configure Multi- Factor Authentication (MFA) using the Resource Owner Password Grant. For details on how to implement this refer to Multi-factor Authentication and Resource Owner Password.
Optional: Configure Anomaly Detection
When using this flow from server-side applications, some anomaly detection features might fail because of the particularities of this scenario. For details on how to implement this, while avoiding some common issues, refer to Using Resource Owner Password from Server side.