Authentication and Authorization

Authentication and authorization are required for a Web page that should be limited to certain users. Authentication is about verifying whether someone is who he claims he is. It usually involves a username and a password, but may include any other methods of demonstrating identity, such as a smart card, fingerprints, etc. Authorization is finding out if the person, once identified (authenticated), is permitted to manipulate specific resources. This is usually determined by finding out if that person is of a particular role that has access to the resources.

Yii has a built-in authentication/authorization (auth) framework which is easy to use and can be customized for special needs.

The central piece in the Yii auth framework is a pre-declared user application component which is an object implementing the IWebUser interface. The user component represents the persistent identity information for the current user. We can access it at any place using Yii::app()->user.

Using the user component, we can check if a user is logged in or not via CWebUser::isGuest; we can login and logout a user; we can check if the user can perform specific operations by calling CWebUser::checkAccess; and we can also obtain the unique identifier and other persistent identity information about the user.

1. Defining Identity Class ¶

In order to authenticate a user, we define an identity class which contains the actual authentication logic. The identity class should implement the IUserIdentity interface. Different classes may be implemented for different authentication approaches (e.g. OpenID, LDAP). A good start is by extending CUserIdentity which is a base class for the authentication approach based on username and password.

The main work in defining an identity class is the implementation of the IUserIdentity::authenticate method. An identity class may also declare additional identity information that needs to be persistent during the user session.

In the following example, we validate the given username and password against the user table in a database using Active Record. We also override the getId method to return the _id variable which is set during authentication (the default implementation would return the username as the ID). During authentication, we store the retrieved title information in a state with the same name by calling CBaseUserIdentity::setState.

class UserIdentity extends CUserIdentity
{
    private $_id;
    public function authenticate()
    {
        $record=User::model()->findByAttributes(array('username'=>$this->username));
        if($record===null)
            $this->errorCode=self::ERROR_USERNAME_INVALID;
        else if($record->password!==md5($this->password))
            $this->errorCode=self::ERROR_PASSWORD_INVALID;
        else
        {
            $this->_id=$record->id;
            $this->setState('title', $record->title);
            $this->errorCode=self::ERROR_NONE;
        }
        return !$this->errorCode;
    }
 
    public function getId()
    {
        return $this->_id;
    }
}

Information stored in a state (by calling CBaseUserIdentity::setState) will be passed to CWebUser which stores them in a persistent storage, such as session. These information can be accessed like properties of CWebUser. For example, we can obtain the title information of the current user by Yii::app()->user->title (This has been available since version 1.0.3. In prior versions, we should use Yii::app()->user->getState('title'), instead.)

Info: By default, CWebUser uses session as persistent storage for user identity information. If cookie-based login is enabled (by setting CWebUser::allowAutoLogin to be true), the user identity information may also be saved in cookie. Make sure you do not declare sensitive information (e.g. password) to be persistent.

2. Login and Logout ¶

Using the identity class and the user component, we can implement login and logout actions easily.

// Login a user with the provided username and password.
$identity=new UserIdentity($username,$password);
if($identity->authenticate())
    Yii::app()->user->login($identity);
else
    echo $identity->errorMessage;
......
// Logout the current user
Yii::app()->user->logout();

By default, a user will be logged out after a certain period of inactivity, depending on the session configuration. To change this behavior, we can set the allowAutoLogin property of the user component to be true and pass a duration parameter to the CWebUser::login method. The user will then remain logged in for the specified duration, even if he closes his browser window. Note that this feature requires the user's browser to accept cookies.

// Keep the user logged in for 7 days.
// Make sure allowAutoLogin is set true for the user component.
Yii::app()->user->login($identity,3600*24*7);

3. Access Control Filter ¶

Access control filter is a preliminary authorization scheme that checks if the current user can perform the requested controller action. The authorization is based on user's name, client IP address and request types. It is provided as a filter named as "accessControl".

Tip: Access control filter is sufficient for simple scenarios. For complex access control, you may use role-based access (RBAC) which is to be covered shortly.

To control the access to actions in a controller, we install the access control filter by overriding CController::filters (see Filter for more details about installing filters).

class PostController extends CController
{
    ......
    public function filters()
    {
        return array(
            'accessControl',
        );
    }
}

In the above, we specify that the access control filter should be applied to every action of PostController. The detailed authorization rules used by the filter are specified by overriding CController::accessRules in the controller class.

class PostController extends CController
{
    ......
    public function accessRules()
    {
        return array(
            array('deny',
                'actions'=>array('create', 'edit'),
                'users'=>array('?'),
            ),
            array('allow',
                'actions'=>array('delete'),
                'roles'=>array('admin'),
            ),
            array('deny',
                'actions'=>array('delete'),
                'users'=>array('*'),
            ),
        );
    }
}

The above code specifies three rules, each represented as an array. The first element of the array is either 'allow' or 'deny' and the rest name-value pairs specify the pattern parameters of the rule. These rules read: the create and edit actions cannot be executed by anonymous users; the delete action can be executed by users with admin role; and the delete action cannot be executed by anyone.

The access rules are evaluated one by one in the order they are specified. The first rule that matches the current pattern (e.g. username, roles, client IP, address) determines the authorization result. If this rule is an allow rule, the action can be executed; if it is a deny rule, the action cannot be executed; if none of the rules matches the context, the action can still be executed.

Tip: To ensure an action does not get executed under certain contexts, it is beneficial to always specify a matching-all deny rule at the end of rule set, like the following:

return array(
    // ... other rules...
    // the following rule denies 'delete' action for all contexts
    array('deny',
        'action'=>array('delete'),
    ),
);

The reason for this rule is because if none of the rules matches a context, an action will be executed.

An access rule can match the following context parameters:

• actions: specifies which actions this rule matches. This should be an array of action IDs. The comparison is case-insensitive.

• controllers: specifies which controllers this rule matches. This should be an array of controller IDs. The comparison is case-insensitive. This option has been available since version 1.0.4.

• users: specifies which users this rule matches. The current user's name is used for matching. The comparison is case-insensitive. Three special characters can be used here:

  • *: any user, including both anonymous and authenticated users.
  • ?: anonymous users.
  • @: authenticated users.

• roles: specifies which roles that this rule matches. This makes use of the role-based access control feature to be described in the next subsection. In particular, the rule is applied if CWebUser::checkAccess returns true for one of the roles. Note, you should mainly use roles in an allow rule because by definition, a role represents a permission to do something. Also note, although we use the term roles here, its value can actually be any auth item, including roles, tasks and operations.

• ips: specifies which client IP addresses this rule matches.

• verbs: specifies which request types (e.g. GET, POST) this rule matches. The comparison is case-insensitive.

• expression: specifies a PHP expression whose value indicates whether this rule matches. In the expression, you can use variable $user which refers to Yii::app()->user. This option has been available since version 1.0.3.

Handling Authorization Result

When authorization fails, i.e., the user is not allowed to perform the specified action, one of the following two scenarios may happen:

• If the user is not logged in and if the loginUrl property of the user component is configured to be the URL of the login page, the browser will be redirected to that page. Note that by default, loginUrl points to the site/login page.

• Otherwise an HTTP exception will be displayed with error code 403.

When configuring the loginUrl property, one can provide a relative or absolute URL. One can also provide an array which will be used to generate a URL by calling CWebApplication::createUrl. The first array element should specify the route to the login controller action, and the rest name-value pairs are GET parameters. For example,

array(
    ......
    'components'=>array(
        'user'=>array(
            // this is actually the default value
            'loginUrl'=>array('site/login'),
        ),
    ),
)

If the browser is redirected to the login page and the login is successful, we may want to redirect the browser back to the page that caused the authorization failure. How do we know the URL for that page? We can get this information from the returnUrl property of the user component. We can thus do the following to perform the redirection:

Yii::app()->request->redirect(Yii::app()->user->returnUrl);

4. Role-Based Access Control ¶

Role-Based Access Control (RBAC) provides a simple yet powerful centralized access control. Please refer to the Wiki article for more details about comparing RBAC with other more traditional access control schemes.

Yii implements a hierarchical RBAC scheme via its authManager application component. In the following ,we first introduce the main concepts used in this scheme; we then describe how to define authorization data; at the end we show how to make use of the authorization data to perform access checking.

Overview

A fundamental concept in Yii's RBAC is authorization item. An authorization item is a permission to do something (e.g. creating new blog posts, managing users). According to its granularity and targeted audience, authorization items can be classified as operations, tasks and roles. A role consists of tasks, a task consists of operations, and an operation is a permission that is atomic. For example, we can have a system with administrator role which consists of post management task and user management task. The user management task may consist of create user, update user and delete user operations. For more flexibility, Yii also allows a role to consist of other roles or operations, a task to consist of other tasks, and an operation to consist of other operations.

An authorization item is uniquely identified by its name.

An authorization item may be associated with a business rule. A business rule is a piece of PHP code that will be executed when performing access checking with respect to the item. Only when the execution returns true, will the user be considered to have the permission represented by the item. For example, when defining an operation updatePost, we would like to add a business rule that checks if the user ID is the same as the post's author ID so that only the author himself can have the permission to update a post.

Using authorization items, we can build up an authorization hierarchy. An item A is a parent of another item B in the hierarchy if A consists of B (or say A inherits the permission(s) represented by B). An item can have multiple child items, and it can also have multipe parent items. Therefore, an authorization hierarchy is a partial-order graph rather than a tree. In this hierarchy, role items sit on top levels, operation items on bottom levels, while task items in between.

Once we have an authorization hierarchy, we can assign roles in this hierarchy to application users. A user, once assigned with a role, will have the permissions represented by the role. For example, if we assign the administrator role to a user, he will have the administrator permissions which include post management and user management (and the corresponding operations such as create user).

Now the fun part starts. In a controller action, we want to check if the current user can delete the specified post. Using the RBAC hierarchy and assignment, this can be done easily as follows:

if(Yii::app()->user->checkAccess('deletePost'))
{
    // delete the post
}

Configuring Authorization Manager

Before we set off to define an authorization hierarchy and perform access checking, we need to configure the authManager application component. Yii provides two types of authorization managers: CPhpAuthManager and CDbAuthManager. The former uses a PHP script file to store authorization data, while the latter stores authorization data in database. When we configure the authManager application component, we need to specify which component class to use and what are the initial property values for the component. For example,

return array(
    'components'=>array(
        'db'=>array(
            'class'=>'CDbConnection',
            'connectionString'=>'sqlite:path/to/file.db',
        ),
        'authManager'=>array(
            'class'=>'CDbAuthManager',
            'connectionID'=>'db',
        ),
    ),
);

We can then access the authManager application component using Yii::app()->authManager.

Defining Authorization Hierarchy

Defining authorization hierarchy involves three steps: defining authorization items, establishing relationships between authorization items, and assigning roles to application users. The authManager application component provides a whole set of APIs to accomplish these tasks.

To define an authorization item, call one of the following methods, depending on the type of the item:

• CAuthManager::createRole
• CAuthManager::createTask
• CAuthManager::createOperation

Once we have a set of authorization items, we can call the following methods to establish relationships between authorization items:

• CAuthManager::addItemChild
• CAuthManager::removeItemChild
• CAuthItem::addChild
• CAuthItem::removeChild

And finally, we call the following methods to assign role items to individual users:

• CAuthManager::assign
• CAuthManager::revoke

Below we show an example about building an authorization hierarchy with the provided APIs:

$auth=Yii::app()->authManager;
 
$auth->createOperation('createPost','create a post');
$auth->createOperation('readPost','read a post');
$auth->createOperation('updatePost','update a post');
$auth->createOperation('deletePost','delete a post');
 
$bizRule='return Yii::app()->user->id==$params["post"]->authID;';
$task=$auth->createTask('updateOwnPost','update a post by author himself',$bizRule);
$task->addChild('updatePost');
 
$role=$auth->createRole('reader');
$role->addChild('readPost');
 
$role=$auth->createRole('author');
$role->addChild('reader');
$role->addChild('createPost');
$role->addChild('updateOwnPost');
 
$role=$auth->createRole('editor');
$role->addChild('reader');
$role->addChild('updatePost');
 
$role=$auth->createRole('admin');
$role->addChild('editor');
$role->addChild('author');
$role->addChild('deletePost');
 
$auth->assign('reader','readerA');
$auth->assign('author','authorB');
$auth->assign('editor','editorC');
$auth->assign('admin','adminD');

Info: While the above example looks long and tedious, it is mainly for demonstrative purpose. Developers usually need to develop some user interfaces so that end users can use to establish an authorization hierarchy more intuitively.

Using Business Rules

When we are defining the authorization hierarchy, we can associate a role, a task or an operation with a so-called business rule. We may also associate a business rule when we assign a role to a user. A business rule is a piece of PHP code that is executed when we perform access checking. The returning value of the code is used to determine if the role or assignment applies to the current user. In the example above, we associated a business rule with the updateOwnPost task. In the business rule we simply check if the current user ID is the same as the specified post's author ID. The post information in the $params array is supplied by developers when performing access checking.

Access Checking

To perform access checking, we first need to know the name of the authorization item. For example, to check if the current user can create a post, we would check if he has the permission represented by the createPost operation. We then call CWebUser::checkAccess to perform the access checking:

if(Yii::app()->user->checkAccess('createPost'))
{
    // create post
}

If the authorization rule is associated with a business rule which requires additional parameters, we can pass them as well. For example, to check if a user can update a post, we would do

$params=array('post'=>$post);
if(Yii::app()->user->checkAccess('updateOwnPost',$params))
{
    // update post
}

Using Default Roles

Note: The default role feature has been available since version 1.0.3

Many Web applications need some very special roles that would be assigned to every or most of the system users. For example, we may want to assign some privileges to all authenticated users. It poses a lot of maintenance trouble if we explicitly specify and store these role assignments. We can exploit default roles to solve this problem.

A default role is a role that is implicitly assigned to every user, including both authenticated and guest. We do not need to explicitly assign it to a user. When CWebUser::checkAccess is invoked, default roles will be checked first as if they are assigned to the user.

Default roles must be declared in the CAuthManager::defaultRoles property. For example, the following configuration declares two roles to be default roles: authenticated and guest.

return array(
    'components'=>array(
        'authManager'=>array(
            'class'=>'CDbAuthManager',
            'defaultRoles'=>array('authenticated', 'guest'),
        ),
    ),
);

Because a default role is assigned to every user, it usually needs to be associated with a business rule that determines whether the role really applies to the user. For example, the following code defines two roles, authenticated and guest, which effectively apply to authenticated users and guest users, respectively.

$bizRule='return !Yii::app()->user->isGuest;';
$auth->createRole('authenticated', 'authenticated user', $bizRule);
 
$bizRule='return Yii::app()->user->isGuest;';
$auth->createRole('guest', 'guest user', $bizRule);