Password - Patroklo/yii2-oauth2-server GitHub Wiki

Overview

This grant type also called User Credentials, is used when the user has a trusted relationship with the client, and so can supply credentials directly. In this method we will exchange a username, password and client authentication for an Access Token.

This grant should be used by apps or clients created by the service itself, for example the Twitter App could use this gran type to log in on mobile or desktop apps.

Use Cases

  • Machines or cronjobs performing maintenance tasks over API.
  • Specific Apps.

Default configuration

Default related variables:

  • allow_credentials_in_request_body: By default it's TRUE. Will define if the system will look for credentials in the POST body in addition to the Authorize HTTP Header.

  • allow_public_clients: By default its TRUE. Will define if the system lets the use of public clients (clients without a password) in the Token requests.

Default parameters:

  • grant_type: "password"

  • username: The defined username o use alongside this client.

  • password: The password required to log in with the username passed along.

  • client_id: The defined client string id in your system.

  • client_secret: Optional, password only required if client it's not public.

You can use this parameters in the body of a POST method call or send the "client_id" and "client_secret" in the authentication header (if so, please read first the Apache Modrewrite section).

As you can see, in this grant type, even having an username and password, keep in mind that it's necessary to also pass the client id and secret in the Token request.

Default Storage

By default the library will use the main module PDO storage which will be pointing two different database tables:

oauth_users

This table will hold the username and password credentials used by the Token requests.

  • username: (string, required) String that will be used to identify the username.

  • password: (string, required) String that stores in SHA1 the user's password.

  • first_name: (string, optional) String that holds the user's first name.

  • last_name: (string, optional) String that holds the user's last name.

oauth_clients

This table will store the client and client secret credentials needed in the Token requests.

  • client_id: (string, required) String credentials that will be used to identify the client.

  • client_secret (string, optional) Field that, if not null, will mark that client as a "non public" and make its use as required. This serves as a password field to improve the security access for specific tasks in the resource servers, like CRUD or accessing vital information.

  • grant_types (string, required) Granting types that the system will allow for that client separated by the space char. Must have the client_credentials string if you want to be able to use this granting type for this client.

  • scope (string, optional) Scopes in which the client will have access in the resource servers. There can be several defined at the same time, each of one must be separated by the space char.

  • user_id (integer, optional) Id linked to the user id of your system (in case you have a defined user management application). This way it's a simple task to link Clients with their respective users.

There are more fields in the table, but they are used by other granting types.

Extending the storage behavior

It's also possible to extend or change the behavior of the library by changing the default storage associated with the grant. This will let you the use of another table than the defined by default, to add more security or extra behavior than checking the client id, secret and the username and password.

To do so you must create a class implementing the UserCredentialsInterface which has the defined methods:

  • boolean checkUserCredentials($client_id, $client_secret = null): This method will check if the credentials passed in the POST method call match any username and password from your system.

  • array getUserDetails($client_id): Will return the data related to the username passed in the parameter.

    The array must have this structure:

return array(
    "user_id"  => USER_ID,    // REQUIRED user_id to be stored with the authorization code or access token
    "scope"    => SCOPE       // OPTIONAL space-separated list of restricted scopes
);

Since this granting method also uses a client id and client secret, you can also extend the Client default storage in order to change the default functionality of the client credentials. This is covered in he Client Credentials granting section.

Once all this methods are properly defined you will have to change your OAuth2 configuration definition as it follows:

'oauth2' => [
   'class' => 'filsh\yii2\oauth2server\Module',
    'storageMap' => [
         'user_credentials' =>  '\app\models\MyUserStorage',
     ],
]

Remember that you can have more than one storage map defined at the same time, one for each grant type, so you can have more than one entry in the storageMap array.

Example Token Request

To make a token request you must send a POST method call.

Using HTTP Authentication

curl -u testclient:testpass https://api.example.com/token -d 'grant_type=password&username=user1&password=pass1'

Using POST BODY

curl https://api.example.com/oauth2/token -d 'grant_type=password&username=user1&password=pass1&client_id=testclient&client_secret=testpass'

Or you can pass the body as Json (remember to send Content-Type:application/json header) to POST request to https://api.example.com/oauth2/token as follows

{
    "grant_type":"password",
    "username":"user1",
    "password":"pass1",
    "client_id":"testclient",
    "client_secret":"testpass"
}

A successful token request will return a standard access token:

{
    "access_token":"cf6404bc148f3682bd807fd13bc5da78d7a8a8c1",
    "expires_in":3600,
    "token_type":"Bearer",
    "scope":null,
    "refresh_token":"45bd27d720cdac232457e694b7348bbe67c4e00f"
}