Reference pages

Use these pages as reference documentation when implementing the password credentials grant flow in your application. Adapted from The OAuth 2.0 Authorization Framework specification [RFC 6749].

An overview of the resource owner password credentials grant

Figure 5 from RFC 6749

The steps are as follows:

• A: The user provides the client application with their username and password.

• B: The client requests an access token from the service provider's token endpoint using the credentials received from the user. During this step, the client application authenticates with the service provider as well.

• C: The service provider authenticates the client and validates the user credentials received, and if valid, issues an access token.

Authorization request and response

The method through which the client obtains the user's credentials is beyond the scope of the specification. Once an access token has been obtained, these credentials must then be discarded.

Access token request

The client makes a POST request to the service provider's token endpoint passing in the following parameters encoded using the application/x-www-form-urlencoded format as described in Appendix B of the specification:

• grant_type: (Required) This is the value that must be set to password

• username: (Required) This is the user's username

• password: (Required) This is the user's password

• scope: (Optional) A list of space-delimited, case-sensitive strings which represent the scope of the access request

As part of this request, the client application must also authenticate with the service provider. This is typically done using the HTTP basic authentication scheme [RFC 2617], but other authentication schemes may be supported by the service provider as well, such as HTTP digest authentication or public/private key authentication

An example access token request using HTTP basic authentication looks like:

     POST /token HTTP/1.1
     Host: server.example.com
     Authorization: Basic czZCaGRSa3F0MzpnWDFmQmF0M2JW
     Content-Type: application/x-www-form-urlencoded

     grant_type=password&username=johndoe&password=A3ddj3w

Access token response

If the access token request is valid and authorized, the response will contain an access token, an optional refresh token, and other parameters, described as follows:

• access_token: (Required) The access token issued by the service provider.

• token_type: (Required) The type of the token issued. This value is case-insensitive.

• expires_in: (Optional) The lifetime of the access token given in seconds. If omitted, the service provider should communicate the expiration time via other means.

• refresh_token: (Optional) A refresh token, which can be used to obtain new access tokens using the refresh token workflow.

• scope: (Conditionally required) A list of space-delimited, case-sensitive strings which represent the scope of the access granted. Required only if the scope granted is different from the scope requested.

An example access token response looks like this:

     HTTP/1.1 200 OK
     Content-Type: application/json;charset=UTF-8
     Cache-Control: no-store
     Pragma: no-cache

     {
       "access_token":"2YotnFZFEjr1zCsicMWpAA",
       "token_type":"bearer",
       "expires_in":3600,
       "refresh_token":"tGzv3JOkF0XG5Qx2TlKWIA",
       "example_parameter":"example_value"
     }

Error response

If the access token request fails for any reason, the server will respond with an HTTP 400 (Bad Request) status code including the following properties:

• error: (Required) This is a single error code representing the condition that caused the request to fail. The value must be one of the following:

  • invalid_request: The request is missing a required parameter, includes an unsupported parameter value (other than the grant type), repeats a parameter, includes multiple credentials, utilizes more than one mechanism for authenticating the client, or is otherwise malformed.

  • invalid_client: The client authentication failed for some reason (for example, an unknown client, no client authentication included, or an unsupported authentication method).

  • invalid_grant: The provided authorization grant or the refresh token is invalid, expired, revoked, does not match the redirection URI used in the authorization request, or was issued to another client.

  • unauthorized_client: The authenticated client is not authorized to use this authorization grant type.

  • unsupported_grant_type: The authorization grant type is not supported by the authorization server.

  • invalid_scope: The requested scope is invalid, unknown, malformed, or exceeds the scope granted by the user.

• error_description: (Optional) Human-readable ASCII message providing additional information regarding the error.

• error_uri: (Optional) A URI identifying a human-readable web page providing additional information regarding the error.

An example error response looks like this:

     HTTP/1.1 400 Bad Request
     Content-Type: application/json;charset=UTF-8
     Cache-Control: no-store
     Pragma: no-cache

     {
       "error":"invalid_request"
     }