vigetlabs / Simplest_auth

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

session_key

:user_id

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:

$ sudo gem install bcrypt-ruby

Configure for the gem:

config.gem 'simplest_auth'

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 @[email protected] columns in your database:

$ ./script/generate model User email:string crypted_password:string

To get started, just use the @SimplestAuth::[email protected] mix-in, and tell it how you want to identify, in your User class:

    class User < ActiveRecord::Base
      include SimplestAuth::Model
      
      authenticate_by :email
    end

The module provides accessors for both @password@ and @[email protected], but you will need to provide the validations required for your application. A @[email protected] method is defined, as well. Some sane defaults:

    validates_presence_of :email
    validates_uniqueness_of :email
    
    validates_presence_of :password, :on => :create
    validates_confirmation_of :password, :if => :password_required?

Before creating new records, the password is crypted before storing the User in the database.

The full model class:

    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

h3. Controller

To initialize the Controller functionality for use in your application, you need to include it in your @[email protected]:

    class ApplicationController < ActionController::Base
      include SimplestAuth::Controller
    end

The plugin defines the @[email protected] 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:

    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

h3. Helpers

The plug-in also defines some convenient helpers to use in your views:

• @[email protected]: The user object of the currently logged-in user (or nil if the user isn't logged-in)
• @[email protected]: Is there a user logged in?
• @authorized[email protected]: 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)