The documentation about the Auth module in Kohana 3.1 is severely lacking, and the module has changed sufficiently that existing tutorials and documentations are no longer relevant.

So below is a quick tutorial on how to setup and use the module:

1) Enable the modules

If not done already, enable the needed modules in bootstrap.php. In particular, auth, database and ORM need to be enabled:

<?php
Kohana::modules(array(
    'auth'       => MODPATH.'auth',       // Basic authentication
    // 'cache'      => MODPATH.'cache',      // Caching with multiple backends
    // 'codebench'  => MODPATH.'codebench',  // Benchmarking tool
    'database'   => MODPATH.'database',   // Database access
    // 'image'      => MODPATH.'image',      // Image manipulation
    'orm'        => MODPATH.'orm',        // Object Relationship Mapping
    // 'unittest'   => MODPATH.'unittest',   // Unit testing
    // 'userguide'  => MODPATH.'userguide',  // User guide and API documentation
    ));
?>

2) Setup the database

– Copy the configuration file from modules/database/config/database.php to application/config/database.php
– Open it and set username, password, etc.
– Create the database schema using the SQL file in modules/orm/auth-schema-mysql.sql

You should now have a working database with all the required tables.

3) Setup the Auth module

– Copy the Auth config file from modules\auth\config\auth.php to your config folder in application/config.
– Open this file and change the driver to “ORM” and set a hash key. It can be any random value such as those generated by WordPress.
– Your file should then look like this:

<?php defined('SYSPATH') or die('No direct access allowed.');

return array(

    'driver'       => 'ORM',
    'hash_method'  => 'sha256',
    'hash_key'     => "4b 8?((~FKnpD))>8kb!B |#-uXIO24G3rc:&MG+FR{x;r#Uq4k{Ef@F4E9^-qS!",
    'lifetime'     => 1209600,
    'session_key'  => 'auth_user',

    // Username/password combinations for the Auth File driver
    'users' => array(
        // 'admin' => 'b3154acf3a344170077d11bdb5fff31532f679a1919e716a02',
    ),

);

In order for the Auth module to work, you must also set the cookie salt variable. So add this at the end of your bootstrap.php file:

Cookie::$salt = 'somerandomstring';

4) How to register a user

Once the database and Auth are setup, it is relatively easy to add a user to the database, although there are some pitfalls (see comments below). Here is the minimum code required to add a user:

<?php
$client = ORM::factory('user');
$client->email = "my@email.com";

/* Note that the username cannot contain
   certain characters such as"." or "@".
   If it does "$client->save()" is going
   to crash, and the error message is not
   helpful */
$client->username = "laurent";

/* Auth is going to automatically hash
   the password when saving the user,
   so don't do it manually */
$client->password = "mypa55word";

$client->save();
?>

After saving the user, assign a role to him (see this post comments).

5) Example login

Once this is all done, login a user is straightforwards:

<?php
$r = Auth::instance()->login("laurent", "mypa55word");
?>

You can also check if a user is currently logged in and, if so, retrieve it from the database:

<?php
$loggedIn = Auth::instance()->logged_in();
if ($loggedIn) {
    $user = Auth::instance()->get_user();
} else {
    echo "User is not logged in";
}
?>

For more information, have a look at the Auth Module API documentation.