Resource Owner Password Credentials Grant

class oauthlib.oauth2.ResourceOwnerPasswordCredentialsGrant(request_validator=None, **kwargs)[source]

Resource Owner Password Credentials Grant

The resource owner password credentials grant type is suitable in cases where the resource owner has a trust relationship with the client, such as the device operating system or a highly privileged application. The authorization server should take special care when enabling this grant type and only allow it when other flows are not viable.

This grant type is suitable for clients capable of obtaining the resource owner’s credentials (username and password, typically using an interactive form). It is also used to migrate existing clients using direct authentication schemes such as HTTP Basic or Digest authentication to OAuth by converting the stored credentials to an access token:

+----------+
| Resource |
|  Owner   |
|          |
+----------+
     v
     |    Resource Owner
    (A) Password Credentials
     |
     v
+---------+                                  +---------------+
|         |>--(B)---- Resource Owner ------->|               |
|         |         Password Credentials     | Authorization |
| Client  |                                  |     Server    |
|         |<--(C)---- Access Token ---------<|               |
|         |    (w/ Optional Refresh Token)   |               |
+---------+                                  +---------------+

Figure 5: Resource Owner Password Credentials Flow

The flow illustrated in Figure 5 includes the following steps:

  1. The resource owner provides the client with its username and
    password.
  2. The client requests an access token from the authorization
    server’s token endpoint by including the credentials received from the resource owner. When making the request, the client authenticates with the authorization server.
  3. The authorization server authenticates the client and validates
    the resource owner credentials, and if valid, issues an access token.
add_token(token, token_handler, request)
Parameters:
  • token –
  • token_handler – A token handler instance, for example of type oauthlib.oauth2.BearerToken.
  • request (oauthlib.common.Request) – OAuthlib request.
create_authorization_response(request, token_handler)
Parameters:
  • request (oauthlib.common.Request) – OAuthlib request.
  • token_handler – A token handler instance, for example of type oauthlib.oauth2.BearerToken.
create_token_response(request, token_handler)[source]

Return token or error in json format.

Parameters:
  • request (oauthlib.common.Request) – OAuthlib request.
  • token_handler – A token handler instance, for example of type oauthlib.oauth2.BearerToken.

If the access token request is valid and authorized, the authorization server issues an access token and optional refresh token as described in Section 5.1. If the request failed client authentication or is invalid, the authorization server returns an error response as described in Section 5.2.

prepare_authorization_response(request, token, headers, body, status)

Place token according to response mode.

Base classes can define a default response mode for their authorization response by overriding the static default_response_mode member.

Parameters:
  • request (oauthlib.common.Request) – OAuthlib request.
  • token –
  • headers –
  • body –
  • status –
validate_grant_type(request)
Parameters:request (oauthlib.common.Request) – OAuthlib request.
validate_scopes(request)
Parameters:request (oauthlib.common.Request) – OAuthlib request.
validate_token_request(request)[source]
Parameters:request (oauthlib.common.Request) – OAuthlib request.

The client makes a request to the token endpoint by adding the following parameters using the “application/x-www-form-urlencoded” format per Appendix B with a character encoding of UTF-8 in the HTTP request entity-body:

grant_type
REQUIRED. Value MUST be set to “password”.
username
REQUIRED. The resource owner username.
password
REQUIRED. The resource owner password.
scope
OPTIONAL. The scope of the access request as described by Section 3.3.

If the client type is confidential or the client was issued client credentials (or assigned other authentication requirements), the client MUST authenticate with the authorization server as described in Section 3.2.1.

The authorization server MUST:

o require client authentication for confidential clients or for any
client that was issued client credentials (or with other authentication requirements),

o authenticate the client if client authentication is included, and

o validate the resource owner password credentials using its
existing password validation algorithm.

Since this access token request utilizes the resource owner’s password, the authorization server MUST protect the endpoint against brute force attacks (e.g., using rate-limitation or generating alerts).