README

= Role-based Authorization for MVC-based web applications in Ruby

Authorization is a mixin that implements role-based authorization for MVC-based web applications in Ruby. It is meant to be an extremely simple implementation.

== Features
 * Simple implementation of role-based authorization (~ 50 lines of code).
 * Uses a whitelist approach. Everything is unauthorized by default, you explicitly specify what is authorized.
 * Works with any authentication plugin (restful_authentication, authlogic, ...)
 * Works with any MVC-based Ruby web framework (I have used it with Rails and Merb)
 * Test suite using rspec

== Motivation

I've been using the role_requirement plugin in many Rails applications and it's an awesome plugin.
However, while using it I found that a whitelist approach was an easier way for me to think about authorization:

Using the Authorization mixin, everything is unauthorized by default, you explicitly specify which actions are authorized for each controller.

  class FooController < ApplicationController
    authorize :admin
    authorize :public, :except => [:edit, :update, :destroy]

    ...
  end

The role_requirement plugin is also specially tailored to Rails and restful_authentication. There are other awesome frameworks and authentication plugins out there.

However, if you need authorization for Rails and you already use restful_authentication, I recommend you to have a look at the role_requirement plugin, it can do a lot more for you (like generating your Role models with migrations).


== Install

Authorization is implemented as a single file (lib/authorization.rb), simply drop it into your lib/ folder or elsewhere.

== Getting Started (for Rails as an example)

1. Include the Authorization mixin into your application controller.

2. Set a before filter that calls the ensure_authorization! method. The method will throw a Authorization::Unauthorized exception if the authorization fails. Using rescue_for you can handle the exception.

3. The ensure_authorization! method expects a current_user method that returns the currently logged in user. It also expects to get the requested action from params[:action]. You could change those defaults by overriding the ensure_authorization! method, it is a one-liner method.

  class ApplicationController
    include Authorization
    before_filter :ensure_authorization!

    rescue_for Authorization::Unauthorized, :with => :render_401
  
    def current_user
      # Return logged in user.
    end
  
    ...

  end


Authorization also expects the class of the object returned from current_user (the User class) to have a has_role? method that checks whether the current user has the given role.

  class User
    def has_role?(role)
      self.role == role
    end

    ...
  end

  class FooController < ApplicationController
    authorize :admin
    authorize :public, :only => [:show, :index]

    ...
  end



== Examples

Authorize the admin for all actions of the controller:

  class FooController < ApplicationController
    authorize :admin

    ...
  end

You can authorize only specific actions:

  class FooController < ApplicationController
    authorize :manager, :only => [:index, :show]

    ...
  end

You can authorize all actions except specified ones:

  class FooController < ApplicationController
    authorize :manager, :except => [:new, :create]

    ...
  end

You can also specify multiple roles:

  class FooController < ApplicationController
    authorize [:admin, :manager]

    ...
  end

You can authorize actions for all users including unauthenticated users (current_user returns nil):

  class FooController < ApplicationController
    authorize :public

    ...
  end

You can combine authorization rules:

  class FooController < ApplicationController
    authorize :admin
    authorize :public, :except => [:new, :create, :edit, :update, :destroy]

    ...
  end


== Acknowledgements

Part of this mixin was inspired from the role_requirement plugin by Tim Charper: http://github.com/timcharper/role_requirement



Copyright (c) 2009 Jean-Sebastien Boulanger <jsboulanger@gmail.com>, released under the MIT license
 
http://jsboulanger.com