Client Credentials - Patroklo/yii2-oauth2-server GitHub Wiki

Overview

It's a grant type used when the client request access to the OAuth2 resource server using only the client credentials (Client id and client secret password in case it's not a public client) to request for an access token.

This grant it's adecuated for machine-to-machine authentication and should only accept trusted clients.

Use Cases

  • Machines or cronjobs performing maintenance tasks over API.
  • Service calls.
  • Calls on behalf of the user who created the client.

Default configuration

Default 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: "client_credentials"

  • 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).

Default Storage

By default the library will use the main module PDO storage which will be pointing to the database table oauth_clients accessing the following fields:

  • 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 only checking he client id and secret.

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

  • boolean checkClientCredentials($client_id, $client_secret = null): This method will check if the credentials passed in the POST method call match any client you have set on your system.

  • boolean isPublicClient($client_id): Determine if the client is a "public" client, and therefore does not require passing credentials for certain grant types.

  • array getClientDetails($client_id): Will return the data related to the Client Id passed in the parameter.

    The array must have this structure:

return array(
"redirect_uri" => REDIRECT_URI,      // REQUIRED redirect_uri registered for the client
"client_id"    => CLIENT_ID,         // OPTIONAL the client id
"grant_types"  => GRANT_TYPES,       // OPTIONAL an array of restricted grant types
"user_id"      => USER_ID,           // OPTIONAL the user identifier associated with this client
"scope"        => SCOPE,             // OPTIONAL the scopes allowed for this client
);

  • string getClientScope($client_id): Gets the scope associated with this Client.

  • boolean checkRestrictedGrantType($client_id, $grant_type): Checks if the selected granting type (in this case client_credentials) it's supported by this client identifier.

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' => [
                'client_credentials' =>  '\app\models\MyClientStorage',
            ],
        ]

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=client_credentials

Using POST BODY

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

A successful token request will return a standard access token:

{"access_token":"03807cb390319329bdf6c777d4dfae9c0d3b3c35","expires_in":3600,"token_type":"bearer","scope":null}