I’m tired of spending loads of time creating user authentication systems with permissions or swimming against the current to customize what’s available. There’s great open source stuff out there but until now, I haven’t gotten the full package with really easy customization.

The Devise and CanCan combo for user authentication and permissions in Rails is my combo of choice.

With Devise and CanCan, you can create a customized authentication and registration process in 15 minutes, and spend another 15 minutes implementing roles and permissions.

It’s pure beauty.

Note that the code here uses Rails 3. The difference in Rails 3 and Rails 2 code for this purpose should be minimal, but please refer to the documentation for differences.

Let’s start with authentication using devise.

Devise

Step 1 – Installation

$ gem install devise
$ rails generate devise:install
$ rails generate devise user

Step 2 – Configuration

Configuration is super easy with Devise. Just choose which of the 11 available modules you would like to include in your authentic model (most up-to-date list here):

  1. Database Authenticatable: encrypts and stores a password in the database to validate the authenticity of an user while signing in. The authentication can be done both through POST requests or HTTP Basic Authentication.
  2. Token Authenticatable: signs in an user based on an authentication token (also known as “single access token”). The token can be given both through query string or HTTP Basic Authentication.
  3. Oauthable: adds OAuth2 support
  4. Confirmable: sends emails with confirmation instructions and verifies whether an account is already confirmed during sign in.
  5. Recoverable: resets the user password and sends reset instructions.
  6. Registerable: handles signing up users through a registration process, also allowing them to edit and destroy their account.
  7. Rememberable: manages generating and clearing a token for remembering the user from a saved cookie.
  8. Trackable: tracks sign in count, timestamps and IP address.
  9. Timeoutable: expires sessions that have no activity in a specified period of time.
  10. Validatable: provides validations of email and password. It’s optional and can be customized, so you’re able to define your own validations.
  11. Lockable: locks an account after a specified number of failed sign-in attempts. Can unlock via email or after a specified time period.

I chose 5 of the 11 modules and configured with the following code:

# In your model
class User < ActiveRecord::Base
  devise :database_authenticatable, :confirmable, :recoverable,
         :rememberable, :trackable, :validatable
end

# In your migration
create_table :users do |t|
  t.database_authenticatable
  t.confirmable
  t.recoverable
  t.rememberable
  t.trackable
  t.timestamps
end

# In your routes
devise_for :users

Step 3 – Use It!

# In your controllers
before_filter :authenticate_user!, :except => [:some_action_without_auth]
# Access Current User
def index
  @things = current_user.things
end

This simple modular approach to authentication is hot. Devise also makes it really easy for you to customize views. The out-of-the-box views are great for prototyping, but if you need more, just generate the views and edit them:

$ rails generate devise:views

Devise will generate all of the views it is using and place them in an app/views/devise directory. Now you have complete control over your views.

The next thing you might want to do is customize your controllers. This is a bit more tricky with devise and we’ll get to that in a minute. Right now I want to touch on permissions and then I’ll tie it all together.

Let’s consider an example where your website is in Alpha/Beta or maybe an internal tool. You want to restrict user registration to only an administrator. Enter CanCan created by Ryan Bates.

CanCan

CanCan is a great gem for implementing model permissions. The main reasons I chose CanCan are:

  • The code written to check permissions is very readable
  • The code written to declare permissions is very concise and readable
  • It keeps permission logic in a single location so it is not duplicated across controllers, views, etc.
  • Aliasing actions (read = index and show) creates more concise and readable code

Ryan Bates has a great screen cast on using CanCan here, but I do not recommend using his roles mask method (mentioned in the screen cast). It certainly works but it’s bad database design and you will feel the pain later.

After you install CanCan (instructions here), I recommend you set up a typical users HABTM roles relationship. So you end up with migrations that look like this:

class CreateRoles < ActiveRecord::Migration
  def self.up
    create_table :roles do |t|
      t.string :name
      t.timestamps
    end
  end

  def self.down
    drop_table :roles
  end
end

class UsersHaveAndBelongToManyRoles < ActiveRecord::Migration
  def self.up
    create_table :roles_users, :id => false do |t|
      t.references :role, :user
    end
  end

  def self.down
    drop_table :roles_users
  end
end

And your models look like this:

# User Model
class User < ActiveRecord::Base
  has_and_belongs_to_many :roles
end

# Role model
class Role < ActiveRecord::Base
  has_and_belongs_to_many :users
end

The next step is to create your Ability class that will define permissions. Mine looks like this:

class Ability
  include CanCan::Ability

  def initialize(user)
    user ||= User.new # guest user

    if user.role? :super_admin
      can :manage, :all
    elsif user.role? :product_admin
      can :manage, [Product, Asset, Issue]
    elsif user.role? :product_team
      can :read, [Product, Asset]
      # manage products, assets he owns
      can :manage, Product do |product|
        product.try(:owner) == user
      end
      can :manage, Asset do |asset|
        asset.assetable.try(:owner) == user
      end
    end
  end
end

Most of this is application specific but you can see some conveniences right away. For example, the super admin role “can manage all”. That line is saying “If the user has the super_admin role, he may perform any action on any model.” Easy enough. Also notice that the product team can “read” products and assets. This means that they can access the index or show action of either of those models. You can pass a block to the can method for more complicated permission checks, but that is beyond the scope of this post and pretty easy to figure out.

Let’s take a look at the role method. I store role names as CamelCase strings in the database but I access them with underscores which is more ruby like. The method looks like this:

def role?(role)
  return !!self.roles.find_by_name(role.to_s.camelize)
end

Tying it all together

Now let’s go back to the situation I mentioned earlier – you want to protect user registrations. This requires us to use CanCan to check for permissions but customize the Devise Registrations controller to restrict access.

One way to do this is to copy the devise controllers into your controllers directory and start customizing. That may be the best way to go and it’s certainly an obvious path, but all I want to do restrict registration. Should I really have to re-implement the registrations controller to do that? For now, I will not. It might make sense when there are more customizations. Instead I inherit from the Devise Registrations controller. Here are the steps:

Step 1 – Create the controller

$ mkdir app/controllers/users
$ touch app/controllers/users/registrations_controller.rb

Step 2 – Add the custom functionality

class Users::RegistrationsController < Devise::RegistrationsController
  before_filter :check_permissions, :only => [:new, :create, :cancel]
  skip_before_filter :require_no_authentication

  def check_permissions
    authorize! :create, resource
  end
end

The check permissions method is really simple. It calls the CanCan method, authorize!, and checks if the current user can create users. We use resource here because devise uses resource to refer to the model that can be authenticated. Also notice how I removed the require_no_authentication filter, a Devise filter which allows access to actions without authentication.

Step 3 – Tell your routes to go to the new controller

# replace devise_for :users with:
devise_for :users, :controllers => { :registrations => "users/registrations" }

Step 4 – Handle the CanCan::AccessDenied exception

At this point if you hit the users/sign_up page when not logged in, you will notice that a CanCan::AccessDenied is thrown. This exception is thrown anytime permission is denied so you should customize it to your liking. I put the handler in my ApplicationController:

class ApplicationController < ActionController::Base
  # ...
  rescue_from CanCan::AccessDenied do |exception|
    flash[:error] = exception.message
    redirect_to root_url
  end
  # ...
end

I realize I skipped some steps in here but this post + Devise documentation + CanCan documentation should help you set up authentication with roles and permissions very quickly. Let me know if you have any questions. Enjoy!