README.textile
h1. SimplestAuth
"!https://codeclimate.com/github/vigetlabs/simplest_auth.png!":https://codeclimate.com/github/vigetlabs/simplest_auth
simplest_auth is a gem to be used with Rails applications where RESTful Authentication is overkill - it handles authentication and nothing else (e.g. password resets, etc...)
simplest_auth is now compatible with both ActiveRecord and DataMapper (the README displays examples for AR)
h2. Changes!
Version 0.2.0 has a change to handle multiple Model session keys. If you are using User as your model class then you shouldn't have a problem. However, if you're using another
class, you will either need to override the <pre><code>session_key</code></pre> method to return <pre><code>:user_id</code></pre> or just accept that a few sessions will be lost.
If you don't care about losing sessions, just go ahead and ignore this message.
If you use this gem in Rails (like most, I suspect), the session_key method will return the model class underscored plus "_id" as a symbol. Otherwise, it's just #downcased (lame).
h2. Installation
SimplestAuth depends (for now) on the BCrypt gem, so install that first:
<pre><code>$ sudo gem install bcrypt-ruby</code></pre>
Configure for the gem:
<pre><code>config.gem 'simplest_auth'</code></pre>
h2. Usage
SimplestAuth is an extension to the existing models and controllers in your Rails application. It makes some decisions about how you structure your models, but will give you flexibility with naming and any ActiveRecord validations that you want to use.
h3. Model Integration
If you're starting out with a fresh User model, you just need an identifier such as @email@ and @crypted_password@ columns in your database:
<pre><code>$ ./script/generate model User email:string crypted_password:string</code></pre>
To get started, just use the @SimplestAuth::Model@ mix-in, and tell it how you want to identify, in your User class:
<pre><code>
class User < ActiveRecord::Base
include SimplestAuth::Model
authenticate_by :email
end
</code></pre>
The module provides accessors for both @password@ and @password_confirmation@, but you will need to provide the validations required for your application. A @password_required?@ method is defined, as well. Some sane defaults:
<pre><code>
validates_presence_of :email
validates_uniqueness_of :email
validates_presence_of :password, :on => :create
validates_confirmation_of :password, :if => :password_required?
</code></pre>
Before creating new records, the password is crypted before storing the User in the database.
The full model class:
<pre><code>
class User < ActiveRecord::Base
include SimplestAuth::Model
validates_presence_of :email
validates_uniqueness_of :email
validates_presence_of :password, :on => :create
validates_confirmation_of :password, :if => :password_required?
end
</code></pre>
h3. Controller
To initialize the Controller functionality for use in your application, you need to include it in your @ApplicationController@:
<pre><code>
class ApplicationController < ActionController::Base
include SimplestAuth::Controller
end
</code></pre>
The plugin defines the @user_class@ method so that it can find the appropriate object in your application, it defaults to User but can be Account or anything else. Once that is included, you can use the controller methods in your application - logging in, for example:
<pre><code>
class SessionsController < ApplicationController
def new; end
def create
if user = User.authenticate(params[:email], params[:password])
self.current_user = user
flash[:notice] = 'Welcome!'
redirect_to root_path
else
flash.now[:error] = "Couldn't locate a user with those credentials"
render :action => :new
end
end
end
</code></pre>
h3. Helpers
The plug-in also defines some convenient helpers to use in your views:
* *@current_user@*: The user object of the currently logged-in user (or nil if the user isn't logged-in)
* *@logged_in?@*: Is there a user logged in?
* *@authorized?@*: Is this user authorized? Defaults to simply checking for logged_in? Override for your authorization scheme.
h2. TODO
* Document the usage of helper methods (e.g. :logged_in? / :authorized?) in the controller
h2. Credits
Tony Pitale and Matt Swasey of Viget Labs (http://www.viget.com)