Step-by-step guide to Kohana 3 auth

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; this part)
An overview of the functionality provided by the Auth module (part 2)
Tips on implementing Auth in a custom application (part 3)

This first post in the series I will discuss setting up KO3 Auth.

UPDATED March 2011: now covers the steps for Kohana 3.1

1. Enable the Auth module in Kohana3

Open application/bootstrap.php and uncomment the auth, database and orm modules:

Kohana::modules(array(
     'auth'       =&gt; MODPATH.'auth',       // Basic authentication
    'database'   =&gt; MODPATH.'database',   // Database access
    'orm'        =&gt; MODPATH.'orm',        // Object Relationship Mapping
    ));

You don't have to use ORM with Auth (the default driver is "file"), but many people do.

2. If you haven't done it earlier, setup the database

Copy modules/database/config/database.php to application/config/. Set the username, password, database and host on in the file.

3. Create the database tables

You can find the database schema on the Kohana wiki or from modules/orm/auth-schema-mysql.sql.

Note that the password column should be CHAR(64) for sha256.

4. Configure the hash_key for Kohana 3.1.x

Copy modules/auth/config/auth.php to application/config/. This will override the default settings.

In Kohana 3.1, the default hash method is now sha256 instead of sha1. This means that there is no salt_pattern; and that old KO 3.x passwords are not compatible with KO 3.1! See the discussion on this bug for more information. TL;DR: the salt pattern is weak, so if someone steals your database but does not know your salt_key, they can deduce it easily and perform a dictionary attack.

Instead, you need to configure your hash_key which gets passed to http://php.net/manual/en/function.hash-hmac.php. You can also use any of the hast_hmac() supported algorithms if you want to.

Use a random hash_key, for example from: https://www.grc.com/passwords.htm

return array

(
    'driver' =&gt; 'ORM',
    'hash_method' =&gt; 'sha256',
    'hash_key' =&gt; NULL, // replace with random string
    'lifetime' =&gt; 1209600,
    'session_key' =&gt; 'auth_user',
    'users' =&gt; array(),
);

5. Next steps: implement login, logout, user role checking and so on...

Now you have enabled the basic auth functionality. Next you have to actually perform the checks for whether the user is logged in and whether they have the correct rights. You will also want to implement functionality for the user to log in and log out as well as to view/edit/delete their profile, change/reset their password and for administrative functionality.

I have provided my own implementation for this functionality, which I will look into in part 3 of this series. You can download the implementation and use it as a basis of your work - please leave a comment and send improvements back if possible.

If you want to implement the functionality yourself, I have discussed the main functionality provided by Auth in part 2 of this series.

Other Kohana Auth tutorials (NOTE Kohana 3.x):

Kohana 3: AUTH, A2 & ACL (nanodocumet.com)
Spanish (?) tutorial on Auth

Comments

Christher: Nice. But what have happend to the Auth module? There is now ORM or salt_pattern?

Andrzej Ośmiałowski: It's now part of the ORM. Check it our: /ORM/classes/kohana/auth/orm.php.

@author - Depending on your needs, you should consider using sha512 instead of sha256.

Ilyas Kazi: Have u checked with Kohana 3.2 framework. It's seem to be quite different from what you are explaining here..

Do u hv any plan for kohana 3.2 authentication example ?

jturo: Well the post is based on 3.1, i, have you tried installing the 3.2 if so what was your experience like? from what i understand this is pretty much the same, the hash method is using a hash_hmac concatenating the string with the hash_key using the hash method defined in the configuration file.

jturo: @lyas Kazi: Well the post is based on 3.1, i, have you tried installing the 3.2 if so what was your experience like? from what i understand this is pretty much the same, the hash method is using a hash_hmac concatenating the string with the hash_key using the hash method defined in the configuration file.

Arte: And what if you want to rename your user table into something different? instead of users, you want to have "admins"?

Pad: Nice series of tuto.

I will use this as a basis to my learning of Kohana, i appreciate your work and how you present it.

Thanks, i'll put a link when my website will be on back to your work. I'll tell you when it comes..

See ya.

William Murray: I'm using Kohana 3.2 and setting up the Auth module using ORM. I was having trouble with the login and found that the Auth SQL on the wiki (linked to from this page) is setting the password field in the user table to have a length of 50. However, the sha256 hashed password will generate a 64 character string. The Auth SQL needs to be fixed to set the password field length to 64 characters.

William Murray: Sorry, I just noticed that step 3 says to change the password to char(64). Ignore my previous post.

Antoine Lépée: Ok ! You just saved me a lot time with your comments :)