First crack at userguide documentation.

Author: daveWid

guide/auth/config.md

@@ -0,0 +1,14 @@
+# Configuration
+
+The default config file is located in `MODPATH/auth/config/auth.php`. You should copy this file to `APPPATH/config/auth.php` and make changes there, in keeping with the [cascading filesystem](../kohana/files).
+
+[Config merging](../kohana/config#config-merging) allows the default config settings to apply if you don't overwrite them in your application configuration file.
+
+Name | Type | Default | Description
+-----|------|---------|------------
+driver | `string` | file | The name of the auth driver to use.
+hash_method | `string` | sha256 | The hashing function to use.
+hash_key | `string` | NULL | The key to use when hashing the password.
+lifetime | `int` | 1209600 | The time (in seconds) that the user session is valid without activity.
+session_type | `string` | [Session::$default] | The type of session to use to store the auth user.
+session_key | `string` | auth_user | The name of the session variable to save the user.

guide/auth/driver/develop.md

@@ -0,0 +1,79 @@
+# Developing Drivers
+
+[!!] We will be developing an `example` driver. In your own driver you will substitute `example` with your driver name.
+
+This example file would be saved at `APPPATH/classes/auth/example.php` (or `MODPATH` if you are creating a module).
+
+## Quick Example
+
+First we will show you a quick example and then break down what is going on.
+
+~~~
+class Auth_Example extends Auth
+{
+	protected function _login($username, $password, $remember)
+	{
+		// Do username/password check here
+	}
+
+	public function password($username)
+	{
+		// Return the password for the username
+	}
+
+	public function check_password($password)
+	{
+		// Check to see if the logged in user has the given password
+	}
+
+	public function logged_in($role = NULL)
+	{
+		// Check to see if the user is logged in, and if $role is set, has all roles
+	}
+
+	public function get_user($default = NULL)
+	{
+		// Get the logged in user, or return the $default if a user is not found
+	}
+}
+~~~
+
+## Extending Auth
+
+All drivers must extend the [Auth] class.
+
+	class Auth_Example extends Auth
+
+## Abstract Methods
+
+The `Auth` class has 3 abstract methods that must be defined in your new driver.
+
+~~~
+abstract protected function _login($username, $password, $remember);
+
+abstract public function password($username);
+
+abstract public function check_password($user);
+~~~
+
+## Extending Functionality
+
+Given that every auth system is going to check if users exist and if they have roles or not you will more than likely have to change some default functionality.
+
+Here are a few functions that you should pay attention to.
+
+~~~
+public function logged_in($role = NULL)
+
+public function get_user($default = NULL)
+~~~
+
+## Activating the Driver
+
+After you create your driver you will want to use it. It is a easy as setting the `driver` [configuration](config) option to the name of your driver (in our case `example`).
+
+## Real World Examples
+
+Sometimes the best way to learn is to just read the code. Here are a auth drivers that you can take a look at.
+
+* [ORM](https://github.com/kohana/orm/blob/3.2/master/classes/kohana/auth/orm.php)

guide/auth/driver/file.md

@@ -0,0 +1,23 @@
+# File Driver
+
+The [Auth::File] driver is the default driver when you activate the auth module.
+
+Below are additional configuration options that can be set for this driver.
+
+Name | Type | Default | Description
+-----|------|---------|-------------
+users | `array` | array() | A user => password (hashed) array of all the users in your application
+
+## Forcing Login
+
+[Auth_File::force_login] allows you to force a user login without a password.
+
+~~~
+// Force the admin user to be logged in
+Auth::instance()->force_login('admin');
+$user = Auth::instance()->get_user(); // Returns the user with the admin username.
+~~~
+
+## Roles
+
+The file driver does not have built in support for roles. If roles are important for your application you should look into a different driver or [develop](driver/develop) your own.

guide/auth/edit.md

@@ -0,0 +1,17 @@
+# Auth
+
+User authentication and authorization is provided by the auth module.
+
+The auth module is included with the Kohana 3.0 install, but needs to be enabled before you can use it. To enable, open your `application/bootstrap.php` file and modify the call to [Kohana::modules] by including the auth module like so:
+
+~~~
+Kohana::modules(array(
+	...
+	'auth' => MODPATH.'auth',
+	...
+));
+~~~
+
+Next, you will then need to [configure](config) the auth module.
+
+The auth module provides a [Auth::File] driver but [drivers](driver/develop) can be easily added to fit your needs.

guide/auth/index.md

@@ -0,0 +1,46 @@
+# Log in and out
+
+The auth module provides methods to help you log users in and out of your application.
+
+## Log in
+
+The [Auth::login] method with handle the login.
+
+~~~
+// Handled from a form with inputs of names email / password
+$post = $this->request->post();
+$success = Auth::instance()->login($post['email'], $post['password']);
+
+if ($success)
+{
+	// Login successful, send to app
+}
+else
+{
+	// Login failed, send back to form with error message
+}
+~~~
+
+## Logged in User
+
+To find the logged in use within you app you will call [Auth::get_user].
+
+~~~
+$user = Auth::instance()->get_user();
+
+// Check for a user (NULL if not user is found)
+if ($user !== null)
+{
+	 // User is found, continue on
+}
+else
+{
+	// User was not found, redirect to the login form
+}
+~~~
+
+## Log out
+
+The [Auth::logout] method will take care of logging out a user.
+
+	Auth::instance()->logout();

guide/auth/login.md

@@ -1,7 +1,5 @@
 ## [Auth]()
-- [Config](config)
-- [User Model](user)
-- [Register Users](register)
+- [Configuration](config)
 - [Log in and out](login)
-- [Edit User](edit)
-- [Using Roles](roles)
+- [File Driver](driver/file)
+- [Developing Drivers](driver/develop)