Oauth2 Yii2 integration

This extension allow the developper to use Oauth2 server.

Installation

If you use Packagist for installing packages, then you can update your composer.json like this :

{
    "require": {
        "sweelix/yii2-oauth2-server": "~1.2.0"
    }
}

How to use it

Add extension to your configuration :

return [
    //....
    'bootstrap' => [
        //....
        'oauth2',
        //....
    ],
    'modules' => [
        //....
        'oauth2' => [
            'class' => 'sweelix\oauth2\server\Module',
            'backend' => BACKEND,
            'db' => DB,
            'identityClass' => 'app\models\User', // only if you don't want to use the user identityClass
            //
            // Parameters
            //
        ],
        //....
    ],
    //....
];

You also need to enable PrettyUrl:

'components' => [
    //....
    'urlManager' => [
        'enablePrettyUrl' => true,
        'rules' => [
            // your rules go here
        ],
        // ....
    ]
    // ....
]

Migrations (MySql only)

All the migrations needed can be found inside src/migrations. Be sure to configure the database connection before applying them.

Grant types

You can find examples and explanations about every grant types here and here.

For the Jwt Bearer Grant, you will need to create a Jwt entry in your database for the given client and subject.

Configure Module

Basic module parameters

• backend : can be redis or mysql
• db : id of the component or connection or connection configuration
• identityClass : user class used to link oauth2 authorization system default to user component identityClass
• webUserParamId : allow separation between main app user (session) and module app user, (default to __oauth2)
• identityCookieName : allow separation between main app user (cookie) and module app user, (default to oauth2)
• webUser : allow full management of module web user, (default to [])
• baseEndPoint : base path for token and authorize endpoints default to ''
  • Token endpoint https://host.xxx/token
  • Authorize endpoint https://host.xxx/authorize
• overrideLayout : override module layout to use another one (ex: @app/views/layouts/oauth2)
• overrideViewPath : override view path to use specific one (ex: @app/views/oauth2)

Grants management

• allowImplicit : allow implicit grant (default to false)
• allowAuthorizationCode : allow authorization code grant (default to true)
• allowClientCredentials : allow client credentials grant (default to true)
• allowPassword : allow user credentials / password grant (default to true)
• allowCredentialsInRequestBody : allow credentials in request body (default to true)
• allowPublicClients : allow public clients (default to true)
• alwaysIssueNewRefreshToken : always issue refresh token (default to true)
• unsetRefreshTokenAfterUse : unset refresh token after use (default to true)

JWT parameters (:warning: Not sure about the implementation. Use at your own risk !)

• useJwtAccessToken : send access tokens as JWT (default : false)
• allowAlgorithm : available algorithm for JWT (default : ['RS256', 'RS384', 'RS512'])
• jwtAudience : default to token endpoint
• storeEncryptedTokenString : store encrypted token (default : true)

Time To Live

• idTTL : TTL of ID Token (default to 3600)
• accessTokenTTL : TTL of access token (default to 3600)
• refreshTokenTTL : TTL of refresh token (default to 14 24 3600)

Basic Oauth names

• realm : Realm value (default to Service)
• tokenQueryName : name of the access token parameter (default to access_token)
• tokenBearerName : name of authorization header (default to Bearer)

Enforce parameters

• enforceState : enforce state parameter (default to true)
• allowOnlyRedirectUri : need exact redirect URI (default to true)

OpenID

• allowOpenIdConnect : enable openId connect (default : false) // not implemented yet

Authorization Code parameters

• enforceRedirect : enforce redirect parameter (default to false)
• authorizationCodeTTL : TTL of authorization code (default to 30)

CORS

• cors : enable CORS on the token endpoint (default : false) the CORS part can be defined using an array as described in Yii documentation

 return [
     //....
     'bootstrap' => [
         //....
         'oauth2',
         //....
     ],
     'modules' => [
         //....
         'oauth2' => [
             'class' => 'sweelix\oauth2\server\Module',
             'backend' => 'redis',
             'db' => 'redis',
             'identityClass' => 'app\models\User', // only if you don't want to use the user identityClass
             //
             // Cors parameters example :
             //
             'cors' => [
                'Origin' => ['https://www.myowndomain.com'],
             ]
         ],
         //....
     ],
     //....
 ];

User identity and Web user

Configure the user component to link oauth2 system and user / identity management

return [
    //....
    'components' => [
        //....
        'user' => [
            'class' => 'sweelix\oauth2\server\web\User',
            'identityClass' => 'app\models\User', // Identity class must implement UserModelInterface
            //
            // Parameters
            //
        ],
        //....
    ],
    //....
];

IdentityClass must implements sweelix\oauth2\server\interfaces\UserModelInterface. You can use the trait sweelix\oauth2\server\traits\IdentityTrait to automagically implement

• public function getRestrictedScopes()
• public function setRestrictedScopes($scopes)
• public static function findIdentityByAccessToken($token, $type = null)

you will have to implement the remaining methods :

• public static function findByUsernameAndPassword($username, $password)
• public static function findByUsername($username)

Creating specific view for OAuth2

In order to use your own views (instead of the builtin ones), you can override

• layout : module parameter overrideLayout
• viewPath : module parameter overrideViewPath

Overriding layout

You should create a classic layout like :

<?php
/**
 * @app/views/layouts/newLayout.php
 * @var string $content
 */
use yii\helpers\Html;

$this->beginPage(); ?>
    <!DOCTYPE html>
    <head>
        <meta charset="utf-8">
        <meta http-equiv="X-UA-Compatible" content="IE=edge">
        <title><?php echo Html::encode($this->title); ?></title>

        <meta name="viewport" content="width=device-width, initial-scale=1">

        <?php $this->head(); ?>
    </head>
    <body>
        <?php $this->beginBody(); ?>
            <?php echo $content;?>
        <?php $this->endBody(); ?>
    </body>

</html>
<?php $this->endPage();

and link it to the module

return [
    //....
    'modules' => [
        //....
        'oauth2' => [
            'class' => 'sweelix\oauth2\server\Module',
            'overrideLayout' => '@app/views/layouts/newLayout',
            //
            // Additional Parameters
            //
        ],
        //....
    ],
    //....
];

Overriding views

You should create 3 views to allow oauth2 module to work as expected and link them to the module

return [
    //....
    'modules' => [
        //....
        'oauth2' => [
            'class' => 'sweelix\oauth2\server\Module',
            // use views in folder oauth2
            'overrideViewPath' => '@app/views/oauth2',
            //
            // Additional Parameters
            //
        ],
        //....
    ],
    //....
];

Error view

This view is used to display a page when an error occurs

<?php
/**
 * error.php
 *
 * @var string $type error type
 * @var string $description error description
 */
use yii\helpers\Html;
?>

    <h1 class="alert-heading"><?php echo ($type ? : 'Unkown error'); ?></h1>
    <p><?php echo ($description ? : 'Please check your request'); ?></p>

Login view

This view is used to display a login page when needed

<?php
/**
 * login.php
 *
 * @var \sweelix\oauth2\server\forms\User $user
 *
 */
use yii\helpers\Html;
?>
    <?php echo Html::beginForm('', 'post', ['novalidate' => 'novalidate']); ?>
        <label>Username</label>
        <?php echo Html::activeTextInput($user, 'username', [
            'required' => 'required',
        ]); ?>
        <br/>

        <label>Password</label>
        <?php echo Html::activePasswordInput($user, 'password', [
            'required' => 'required',
        ]); ?>
        <br/>
        <button type="submit">LOGIN</button>
    <?php echo Html::endForm(); ?>

Authorize view

This view is used to display an authorization page when needed

<?php
/**
 * authorize.php
 *
 * @var \sweelix\oauth2\server\interfaces\ScopeModelInterface[] $requestedScopes
 * @var \sweelix\oauth2\server\interfaces\ClientModelInterface $client
 *
 */
use yii\helpers\Html;
?>
    <h1><?php echo $client->name ?> <span>requests access</span></h1>

    <?php echo Html::beginForm(); ?>
        <?php if(empty($requestedScopes) === false) : ?>
        <ul>
            <?php foreach($requestedScopes as $scope): ?>
            <li>
                <h4><?php echo $scope->id; ?></h4>
                <p>
                    <?php echo $scope->definition; ?>
                </p>
            </li>
            <?php endforeach; ?>
        </ul>
        <?php endif; ?>
            <!-- name of decline button **must be** decline -->
            <button type="submit" name="decline">DECLINE</button>
            <!-- name of accept button **must be** accept -->
            <button type="submit" name="accept">AUTHORIZE</button>
    <?php echo Html::endForm(); ?>

Exposed Models overview

The Oauth2 Yii2 extension expose severall models which can be used in your application. All models can be overloaded using Yii2 DI.

For example, if you want to overload the Client model, you have to inject your own model in the DI using:

Yii::$container->set('sweelix\oauth2\server\interfaces\ClientModelInterface', [
    'class' => YourClientModel::className(),
]);

Client / ClientModelInterface

• Client::findOne($id) - Find client by ID
• Client::findAllByUserId($id) - Find all clients accepted by user (userId)
• Client::findAll() - Find all existing clients
• $client->save() - Save client
• $client->delete() - Delete client
• $client->hasUser($userId) - Check if user (userId) has accepted the client
• $client->addUser($userId) - Attach the user (userId) to the client
• $client->removeUser($userId) - Dettach the user (userId) from the client

AccessToken / AccessTokenModelInterface

• AccessToken::findOne($id) - Find accessToken by ID
• AccessToken::findAllByUserId($id) - Find all accessTokens for user (userId)
• AccessToken::findAllByClientId($id) - Find all accessTokens for client (clientId)
• AccessToken::deleteAllByUserId($id) - Delete all accessTokens for user (userId)
• AccessToken::deleteAllByClientId($id) - Delete all accessTokens for client (clientId)
• AccessToken::findAll() - Find all existing accessTokens
• AccessToken::deleteAllExpired() - Delete all expired accessTokens
• $accessToken->save() - Save accessToken
• $accessToken->delete() - Delete accessToken

RefreshToken / RefreshTokenModelInterface

• RefreshToken::findOne($id) - Find accessToken by ID
• RefreshToken::findAllByUserId($id) - Find all refreshTokens for user (userId)
• RefreshToken::findAllByClientId($id) - Find all refreshTokens for client (clientId)
• RefreshToken::deleteAllByUserId($id) - Delete all refreshTokens for user (userId)
• RefreshToken::deleteAllByClientId($id) - Delete all refreshTokens for client (clientId)
• RefreshToken::findAll() - Find all existing refreshTokens
• RefreshToken::deleteAllExpired() - Delete all expired refreshTokens
• $refreshToken->save() - Save refreshToken
• $refreshToken->delete() - Delete refreshToken

AuthCode / AuthCodeModelInterface

• AuthCode::findOne($id) - Find authCode by ID
• $authCode->save() - Save authCode
• $authCode->delete() - Delete authCode

Scope / ScopeModelInterface

• Scope::findOne($id) - Find scope by ID
• Scope::findAvailableScopeIds() - Find all scopes IDs
• Scope::findDefaultScopeIds() - Find default scopes IDs
• $scope->save() - Save scope
• $scope->delete() - Delete scope

CypherKey / CypherKeyModelInterface

• CypherKey::findOne($id) - Find cypherKey by ID
• $cypherKey->save() - Save cypherKey
• $cypherKey->delete() - Delete cypherKey
• $cypherKey->generateKeys() - Generate random keys for current cypherKey

Jti / JtiModelInterface (:warning: Not sure about the implementation. Use at your own risk !)

• Jti::findOne($id) - Find jti by ID
• Jti::findAllBySubject($id) - Find all jtis for user (userId)
• Jti::findAllByClientId($id) - Find all jtis for client (clientId)
• Jti::deleteAllBySubject($id) - Delete all jtis for user (userId)
• Jti::deleteAllByClientId($id) - Delete all jtis for client (clientId)
• Jti::findAll() - Find all existing jtis
• Jti::deleteAllExpired() - Delete all expired jtis
• Jti::getFingerprint($clientId, $subject, $audience, $expires, $jti) - Get a jti fingerprint for given params
• $jti->save() - Save jti
• $jti->delete() - Delete jti

Jwt / JwtModelInterface (:warning: Not sure about the implementation. Use at your own risk !)

• Jwt::findOne($id) - Find jwt by ID
• Jwt::getFingerprint($clientId, $subject) - Get jwt fingerprint for given clientId and subject
• $jwt->save() - Save jwt
• $jwt->delete() - Delete jwt

Linking RBAC and Scope systems

Using sweelix\oauth2\server\web\User class will automagically link rbac system and oauth2 system.

Permission system will be slightly modified to allow fine grained checks :

• Yii::$app->user->can('read') will check

  1. if scope read is allowed for current client
  2. if rbac permission read is allowed for current user

• Yii::$app->user->can('rbac:read') will check only if rbac permission read is allowed for current user

• Yii::$app->user->can('oauth2:read') will check only if scope read is allowed for current client

Running the tests

Before running the tests, you should edit the file tests/config/BACKEND.php and change the config to match your environment.

CLI System

Several commands are available to manage oauth2 system

• php protected/yii.php oauth2:client/create
• php protected/yii.php oauth2:client/update
• php protected/yii.php oauth2:client/delete
• php protected/yii.php oauth2:jwt/create
• php protected/yii.php oauth2:jwt/update
• php protected/yii.php oauth2:jwt/delete
• php protected/yii.php oauth2:key/create
• php protected/yii.php oauth2:key/update
• php protected/yii.php oauth2:key/delete
• php protected/yii.php oauth2:scope/create
• php protected/yii.php oauth2:scope/update
• php protected/yii.php oauth2:scope/delete
• php protected/yii.php oauth2:cronjob/remove-expired - Run this one with your cron manager
• php protected/yii.php oauth2:migrate-redis/migrate - Migration command for redis