Kohana 3 auth: the auth module functionality

The Kohana 3 Auth model implements a set of basic functionality for authentication (login) and authorization (user rights based on roles). In this series of posts, I will discuss:

Setting up the basic Auth in KO3 (part 1)
An overview of the functionality provided by the Auth module (part 2; this part)
Tips on implementing Auth in a custom application (part 3)

In this second post in the series I will discuss the different functionality provided by the Auth module.

An overview of the files in the KO3 Auth module:

modules/auth/classes/kohana/auth/file.php - contains the file driver for Auth.
modules/auth/classes/kohana/auth/orm.php - contains the ORM driver for Auth.
modules/auth/classes/kohana/auth.php - implements the Auth singleton.
modules/auth/classes/model/auth/user.php - User model (Model_Auth_User).
modules/auth/classes/model/auth/role.php - Role model (Model_Auth_Role).
modules/auth/classes/model/auth/user/token.php - User_token model (Model_Auth_User_Token).
modules/auth/config/auth.php - Auth module configuration.

Different drivers: File and ORM

There are two different drivers for Auth. The ORM driver is most commonly used, and it stores and retrieves data in the database. The File driver is the alternative, which stores credentials in the auth module config file.

ORM functionality vs. Auth functionality

It is important to note that the Auth class models (user, role, token) extend the ORM base class. This means that all the ORM methods can be used e.g. to retrieve users using different conditions in the same way as other ORM models would.

Have a look at the ORM documentation for specifics. The Auth functionality for the ORM driver is built upon the ORM, and it uses the existing functionality such as relationships ($_has_many), validation rules ($_rules, $_ignored_columns), callbacks ($_callbacks).

Much of what you will be doing with the users model will be adding extended information such as new relationships and new fields. As long as you keep the default relationships, rules and field names, you will be able to flexibly extend the user model to suit your needs.

The Auth singleton

Auth class (/modules/auth/classes/kohana/auth/orm.php):

Auth::instance(). Retrieves the instance of the Auth singleton.
logged_in($role = NULL). If called without arguments, checks whether the user is logged in. If an argument is given, then checks whether the logged in user has the given role (string/Role object) or roles (array of strings / Role objects).
get_user(). Retrieves the user model for the user who is currently logged in (or FALSE).
login(array & $array, $redirect = FALSE). The array should contain the password and username. If the redirect parameter is set, then the login will be redirected to the given URL.
logout(). Logs the current user out.
force_login($username). Forces the username given as the first argument to log in - without a password.
auto_login(). Logs in the user automatically.

The User model

Model_Auth_User defines two relationships:

// Relationships
protected $_has_many = array
(
    'user_tokens' =&gt; array('model' =&gt; 'user_token'),
    'roles'       =&gt; array('model' =&gt; 'role', 'through' =&gt; 'roles_users'),
);

These relationships connect the user to Roles and tokens. Roles are particular sets of rights, such as "admin". Tokens are used for two purposes: automatic login using cookies and password reset using password reset tokens. A user can have multiple tokens.

Model_Auth_User defines additional rules and callbacks for the username, email and password fields.

    // Rules
    protected $rules = array
    (
        'username'            =&gt; array
        (
            'not_empty'        =&gt; NULL,
            'min_length'        =&gt; array(4),
            'max_length'        =&gt; array(32),
            'regex'            =&gt; array('/^[-pLpN.]++$/uD'),
        ),
        'password'            =&gt; array
        (
            'not_empty'        =&gt; NULL,
            'min_length'        =&gt; array(5),
            'max_length'        =&gt; array(42),
        ),
        'password_confirm'    =&gt; array
        (
            'matches'        =&gt; array('password'),
        ),
        'email'                =&gt; array
        (
            'not_empty'        =&gt; NULL,
            'min_length'        =&gt; array(4),
            'max_length'        =&gt; array(127),
            'validate::email'    =&gt; NULL,
        ),
    );

It also provides a number of functions:

login(). First argument is an array containing username and password, the second argument is an optional URL to redirect to.
change_password(). Allows the password to be changed. First argument is an array containing password and password_confirm, second is an optional URL which if given causes the value to be saved immediately and redirected to the given URL.
username_available(). A callback used in the validation process which checks that the username is available when creating a user.
email_available(). A callback used in the validation process which checks that the email address is unique.
save(). A save() function that causes the password to be hashed before saving if it was changed.

The Role model

Roles have a name and a description (a line of text). They are associated with users through the roles_users table. The model does not implement any functions, only a number of rules stored in $_rules.

The User_token model

User_tokens have a unique token and an expiry date. The token can be generated by using create_token() and housekeeping (removing the expired tokens) can be performed using delete_expired(). When the token is saved, the user agent of the current request is saved.

Tokens are essentially unique authorizations either related to password resets or to auto login.

Comments

codeho: Hey thanks for your explanation. i was wondering if you know how i can get a users role into the user object, so that i can check for it in the controller.

thanks

Jasper: Hi, I really love your tutorial over here. I cant wait to experiment with it, so I hope the 3rd part will be online soon. Thanks!

Diwant Vaidya: Mixu, ty for the article.

codeho, try doing Auth::instance()->get_user()->roles->find_all() which you can do from inside your controller. It will get you all the roles the user has.

Kostas: Hello, How can I change the password for a user when using the file driver?