A Rails plugin to authorize controller action access based on user roles
Switch branches/tags
Nothing to show
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Failed to load latest commit information.
generators/role_fu
lib
tasks
test
MIT-LICENSE
README.markdown
Rakefile
init.rb
install.rb
uninstall.rb

README.markdown

RoleFu

RoleFu is a Rails plugin that enables role-base authorization via a generator script and simple controller configuration.

Installation

  1. Install the plugin

     script/plugin install git://github.com/brentmc79/role_fu.git
    
  2. Generate the migration

     script/generate role_fu
    

    If the model that you're adding roles to is something other than User, then you may want/need to change the :user_id column for RoleMapping to something else.

  3. Modify your model by adding 'has_role_fu'.

     class User < ActiveRecord::Base
     	has_role_fu
     end
    
     This does two things.  First it declares the associations with roles and role mappings.  Second, it provides boolean methods for each row in the Roles table.  So if there's a role with the name "author", then your model will have the method .author?
    
  4. Modify your controllers.

     class SomeController < ApplicationController
     	has_role_fu [options]
     
     	def	some_action
     		#do stuff
     	end
     end
    

    Just add the has_role_fu method call somewhere in you conroller. See the next section for configuration options.

Configuration

All of the configuration happens in the controllers. The has_role_fu method expects a hash where the keys are the action names, and the values can be one of three things:

  1. A symbol representing the accepted role.

  2. An array of role names, like [:admin, :author, :editor]. This will allow admins, authors, editors, OR any of their sub-roles to perform this action. Note that every Role can have a parent role, and/or one or more lesser roles.

  3. Another hash where the key is :only and the value is an array of role names. The difference here is that you are now explicitly specifying the acceptable roles. In other word, ONLY the specified roles, and not any of their sub-roles, will be authorized to perform the action.

RoleFu assumes that you're using some form of authorization that exposes the active user via a "current_user" method. You can override this by using the :user_alias option, where the value is the symbol representing the active role-owner.

Example

Given a set of roles:

system_admin  
	admin  
	editor  
		author  
		reader  

And a set of actions:

do_stuff  
do_editor_stuff  
do_admin_stuff  
do_system_stuff  

You can declare your action authorization like so:

has_role_fu :do_stuff => [:author, :reader], 
			:do_editor_stuff => :editor, 
			:do_admin_stuff => {:only => :admin}, 
			:do_system_stuff => :system_admin,
			:user_alias => :active_account

This allows authors, readers, or anyone with a higher role to do_stuff. Editors or higher can do_editor_stuff. Only admins can do_admin_stuff. Using the :only option explicity states the accepted role and DOESN'T take into account the role hierarchy. In other words, admins can do admin stuff, but the parent role system_admin can't. The :user_alias option tells role_fu to retrieve the "user" by calling the :active_account method, rather than the default :current_user.

Copyright (c) 2009 Brent Collier, released under the MIT license