JiffAuth is an alternative (to popular restful_authentication) authentication plugin for Rails. It’s main goals are:

  * no code generators (unlike restful_authentication)
  * quick intergation into your existing application
  * simple and flexible configuration
  * login with any model field you would want

It’s still in active development, so there’s a couple of important features left unimplemented. Check out TODO to find out more.

Plugin contains unit tests written using rspec and rspec_rails 1.1.4 You can run them with ‘spec spec’ command. Make sure the plugin lies in vendor/plugins though — specs use rails environment and will fail to run outside the rails project.

QUICK INTEGRATION

Steps:

  1. Install
  2. Create migration
  3. Configure plugin
  4. Map routes

  (1) Put JiffAuth in your vendor/plugins dir

  (2) Create a new db migration adding the following fields:

      add_column :users, :password                :string  :limit => 40
      add_column :users, :password_token,         :string, :unique => true, :limit => 20
      add_column :users, :password_token_expires, :datetime

    I will assume below, that your model name is User, so please adjust if needed.

    There also should probably be an :email field, but since Mailer class should be written by the end user,
    you might design it in such way, that it just does nothing if there's no email.

  (3) Open your application.rb file and add this:

        JiffAuth.configure(:app_controller => self, :auth_controller => :users, :model => :user)

    This is were everything happens. JiffAuth.configure extends with its methods
    your ApplicationController, and controller and model, which you send to configure() as parameters.
    These three arguments are obligatory.

    There are also some other agruments you might want to pass to JiffAuth.configure. They are:

      :redirect_on => {
        :create => :to_resource
        :logout => '/login',
        :login  => :to_stored,
        :recover_password => '/change-password'
      },
      :render_on  => {
        :error        => "users/error",
        :message      => "users/system-message",
        :login_fail   => "users/login",
        :create_fail  => "users/new",
      }

     Quite self-descriptive, I think. Except maybe for :to_resource
     This options means jiff_auth will redirect user to his own profile after signing up.

     By the way, the urls and paths in this example are default,
     ('users' is your controller name by default). So use these
     arguments only if you want to change the defaults.

     Note :create_fail and :login_fail - they become very handy, when you have login/signup
     form all over your pages and want jiff_auth to render to user a particular template if he submitted
     invalid data.

     You may also provide as many additional elements for these two hashes, as you like,
     and use them for your own purposes. For example:

     :redirect_on => { :my_custom_action => '/this/is/where/you/are/redirected' }

  (4) Last step is to map all that stuff in routes.rb. Let me show you my project example:

      map.connect   'login',            :controller => 'users', :action => 'login'
      map.connect   'logout',           :controller => 'users', :action => 'logout'
      map.connect   'signup',           :controller => 'users', :action => 'new'
      map.connect   'lost-password',    :controller => 'users', :action => 'lost_password'
      map.connect   'recover-password', :controller => 'users', :action => 'recover_password'
      map.connect   'change-password',  :controller => 'users', :action => 'change_password'

   You may also use named routes here and pass them later to JiffAuth.configure
   in :redirect_on argument (see above, step 3).
   JiffAuth plugin also assumes, that your model is a resource (i.e. map.resource :user).

Okay, now we’re ready to run. Sorry, but since the whole idea was about not to generate any code, you will have to write the views yourself. I’ll explain a few things about it in the next section.

USAGE (WITH VIEWS EXAMPLES)

I assume, you will need views at least for:

  * login
  * new

So, each of these templates goes in ‘app/views/users’ dir. Let’s take a look at ‘new’ template first. Here’s how it might look:

  <% form_for @user, :method => "post", :html => {:multipart => true} do |f| %>
    <input type="text"      name="user[login]" />
    <input type="password"  name="user[password]" />
    <input type="password"  name="user[password_confirmation]" />
    <input type="text"      name="user[email]" />
  <% end %>

If password comes blank, the model will generate password. In any case, the password will be sent to the user (being more accurate, model will invoke UserMailer.deliver_signup(self) ), and it’s up to you what are you going to do with it in your UserMailer class. Just note, you must have a UserMailer class with at least to methods: ‘signup’ and ‘lost_password’.

Anyway, if the signup is successful, we’re redirected (if you didn’t change the defaults!) to the login action. Here’s how the view for login might look:

  <% form_for User.new, :url => 'login', :method => "post", :html => {:multipart => true} do |f| %>
    <input type="text"      name="user[login]" />
    <input type="password"  name="user[password]" />

    <!-- 'remember_me' is optional, of course -->
    <input value="true" type="checkbox" name="remember_me"/>
  <% end %>

It’s simple. But sometimes you might want to give your users an option to login with their ‘id’, ‘email’ or ‘openid’, and you still want to have only one field. Check out the next code:

  <% form_for User.new, :url => 'login', :method => "post", :html => {:multipart => true} do |f| %>
    <input type="text"      name="user[guess_me_field]" />
    <input type="password"  name="user[password]" />
    <input type="hidden"    name="guess_login" value="guess_me_field"/>
  <% end %>

The controller will try to guess, what kind of field the user is trying to login with. In fact, you might want to write your own guess rules for that. Just take a look at ‘jiff_auth/lib/auth_controller.rb:108’ and then redefine ‘login_type’ method in your controller.

Also make sure, that your ‘guess_me_field’ is allowed as field for authentication. You can set it in JiffAuth.configure:

  :auth_by => [:login, :email, :id, :openid]

Again, this example shows the defaults, so you don’t need this argument, unless you want to add or remove some.

What’s also important is that you can only pass a hash of 2 arguments to the model (user[email] and user[password] for example), when authenticating. Otherwise, it will raise error.

USEFUL METHODS IN YOUR CONTROLLERS

  in ApplicationController:

    current_logged_in     -- Returns current user.id or nil (also a helper)

    should_be_logged_in   -- Returns 'true' if the user current_logged_in is not nil.
                             By default used in some before_filters.

    should_be_logged_out  -- Returns true, if user is not logged.
                             By default used in some before_filters.

    jiff_auth_options     -- Takes symbol as a parameter and returns one of options,
                             that you set in JiffAuth.cofigure (also a helper)

  in UserController

    should_be_owner       -- Returns true, if params[:id] == current_logged_in.
                             By default used as before_filter to User#edit.

CAPTCHA USAGE

  If you want to have captcha support you need to install this plugin first:
  http://github.com/zendesk/captcha

  Then just add a new agrument to JiffAuth.configure call in application.rb, it might look like this:

    JiffAuth.configure(
        :app_controller   => self,
        :auth_controller  => :users,
        :model            => :user,
        :captcha_on       => ['login', 'create']
      )

  'captcha_on' should contain an array of action names (in your controller) you want
  to use captcha with. By default, it will validate actions only on post requests
  (overwrite 'should_be_captcha_validated' in your controller if you want a different behaviour).

  should_be_captcha_validated() method also uses :create_fail, :login_fail and
  any other :[method_name]_fail elements of :redirect_on hash and redirects to its values,
  if validation fails. If there's no corresponding _fail value for the method, it redirects back.

  If 'captcha_on' argument is not set, then captcha support is disabled.

  You will need to read 'captcha' plugin README first to generate .png files and set CAPTCHA_SALT.
  To intergrate captcha in views, just put <%= captcha_block %> in your template.

CONTRIBUTIONS

If you want to help and implement/enhance any feature or add documentation, please contact me.

CREDITS

Author: Roman Snitko My email and jabber id can be found at my homepage: http://snitko.ru