Authorization Code

Overview

This is the grant type most often associated with OAuth; its basically used when the client wants to request access to protected resources on behalf of another user (i.e. a 3rd party).

If you have ever signed into a website of application with your Twitter/Facebook/Google account, then you'll have used this grant type.

This grant type is used to obtain both access tokens and refresh tokens and is optimized for confidential clients. Since this is a redirection-based flow, the client must be capable of interacting with the resource owner's user agent and also capable of receiving incoming requests from the authorization server.

In this grant type, the access token is kept private from the resource owner.

Use Cases

• Mobile applications
• Websites

Default configuration

Default variables:

• enforce_state (boolean) Default TRUE, defines if the module should require the "state" parameter in the call for a code authorization.

• enforce_redirect (boolean) Default FALSE, enforces the use of the redirect_uri parameter.

• require_exact_redirect_ur (boolean) Default TRUE, defines if the module should require an exact match on the "redirect_uri" parameter.

• redirect_status_code (integer) Default 302, states the HTTP status code to use for redirect responses.

Access code request default parameters:

http://yii.zoltan.es/basic/oauth2/authorize?response_type=code&client_id=testclient&state=123

• response_type: "code"

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

• state: Optional.

• redirect_uri Optional.

You will have to use this parameters in a GET method call.

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}