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

Authorization code flow

The Authorization code has a different flow than the rest of the grant types defined in the standard (except the Implicit grant type that it's a version of this type).

While all work making requests directly to the access token handler, the Authorization code grant type will use an additional 3rd party that will store the access credentials while calling to the OAuth2 server for, first, an Authorization request, and then, with this authorization request code, for an Authorization Token.

For more information about how Authorization code flow works, please refer to the Glossary

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_uri (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_lifetime (integer) Lifetime in seconds of the Access code generated in the access code request step.

Step 1. Access code request default parameters

This are the required parameters that can be sent into the access code request step of your OAuth2 server.

This step will return an Access Code that the client will hold in order to get in the near future an Access Token that will grant

• response_type: "code"

• client_id: A valid client string id in your system. Will load all the data related to him.

• state: Optional. May be sent to improve security of the credentials sent into he system. State Security

• redirect_uri Optional. A URI that will redirect the system after the access code request. Remember that if the client has a redirect_uri defined in the system, both will be compared and, if they are different, the system will throw an exception.

• scope Optional. Checks if the client_id passed has assigned the scope passed in this parameter.

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

Step 2. Access token request default parameters

This are the required parameters that the client that holds the Access code should send to your OAuth2 Access Token dispatcher.

This step is he same to the rest of granting types.

• grant_type "authorization_code"

• code The access code sent in the previous step.

• 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 two different database tables:

oauth_authorization_codes

This table will hold the authorization codes dispatched in the authorization code request step until they are used by the client in the access token request step.

• authorization_code: (string, required) String that holds the authorization code.

• client_id: (string, required) Client that has this authorization code assigned.

• user_id: (integer, optional) User id linked to the Client id.

• expires: (date time, required) Time in which the authorization code will expire and will be rendered unusable.

• scope (string, optional) Scope defined for this authorization code, will be returned in the authorization token request process.

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.

• redirect_uri (string, optional) Will be used to check the redirect_uri parameter passed in the Access code request step or to redirect to this URL in case it's not null and no parameter has been passed.

• grant_types (string, required) Granting types that the system will allow for that client separated by the space char. Must have the authorization_code 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.

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.

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

• RESPONSE_TYPE_CODE Set as code, it's the response type that the authorization code request step will accept to make the access code.

• array getAuthorizationCode($code): This method will check if the access code passed as parameter still has not expired and will return the data associated with it.

return array(
    "client_id"    => CLIENT_ID,      // REQUIRED Stored client identifier
    "user_id"      => USER_ID,        // REQUIRED Stored user identifier
    "expires"      => EXPIRES,        // REQUIRED Stored expiration in unix timestamp
    "redirect_uri" => REDIRECT_URI,   // REQUIRED Stored redirect URI
    "scope"        => SCOPE,          // OPTIONAL Stored scope values in space-separated string
);

• void setAuthorizationCode($code, $client_id, $user_id, $redirect_uri, $expires, $scope = null): Take the provided authorization code values and store them somewhere. This function should be the storage counterpart to getAuthCode().

• array expireAuthorizationCode($code): Once the authorization code is used, must be dealt with (expired, deleted, whatever, but should not be possible to reuse it).

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

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 Authorizacion Code Request

This should be a GET method call.

https://api.example.com/authorize?response_type=code&client_id=testclient&redirect_uri=https://myredirecturi.com/cb

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=authorization_code&code=7cc8567f57a22f9751964ed38a64fb3f84a66f89

Using POST BODY

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

A successful token request will return a standard access token:

{"access_token":"9fe0927a228f84317d3d21c42ded61cffce86fc4","expires_in":3600,"token_type":"Bearer","scope":"scope_name","refresh_token":"0d464e5e28c6a918319a45fc8a6c51e1794e084c"}