= Simple permissions

Simple permissions aims to make available a simple way to check for roles in Rails. This gem has been tested on Rails 3 only. If you use :lib => false and include the modules correctly it should work fine on rails 2.3.

== Configuration

To configure you just need to change the config constants below:

SimplePermissions::Config.current_user_method = :current_user

This sets the method which will be used inside simple permissions to get the logged user and check for roles.

SimplePermissions::Config.permissions_method = :permissions

This sets the name of the method from the user model which will be called to get the permissions.

SimplePermissions::Config.permission_type = :role

This sets the type of permission which will be used to check the user roles. Allowed types are `:role` and `:read_write`. Both types will be described below.

== Setup

Include in your Gemfile:

gem 'simple_permissions'

Run:

bundle install

In the user model include methods for authorization like the code bellow:

class User < ActiveRecord::Base include SimplePermissions::UserModelMethods end

== How it works

=== Model methods

The model methods included by the gem to check the user authorization expect the user model to respond to a permissions method that will return the user permissions according to the permission type defined.

=== Permission types

==== :role

Using this permission type, the permissions method from the user model should return an array of strings containing the code of the permissions, like the example below:

['CRUD_USER', 'CRUD_PROFILE']

The suggested models for this approach are the following:

   ______          _________         _____________          ____________________
  | User |________| Profile |_______| Permission  |________| PermissionCategory |
  |______| N    1 |_________| N   M |_____________| N    1 |____________________|
                                    | code        |
                                    | description |
                                    |_____________|

==== :read_write

Using this permission type, the permissions method from the user model should return an hash having the permission code as key and the literal string r or w as value, like the example below:

{'CRUD_USER' => 'w', 'CRUD_PROFILE' => 'r'}

The suggested models for this approach are the following:

| User |____| Profile || ProfilePermission |____| Permission |____| PermissionCategory | |__| N 1 |__| 1 N |___| N 1 |_| N 1 |____| | read_write | | code | |___| | description | |_|

=== Controllers

After installing the gem there will be two methods available for authorization: has_permission and has_permission!. Both receiving an array of permission codes or a hash depending on the permission type configured.

At controllers it is recommended to put a has_permission! call as the first line of each action to validate the user credentials.

class SampleController < ApplicationController def index has_permission!('CRUD_COMPANY') ... end end

This credential check will raise an SimplePermissions::AccessDeniedException exception, so in order to capture nonauthorized actions it is recommended to include the following code in the application_controller.rb

class ApplicationController < ActionController::Base rescue_from SimplePermissions::AccessDeniedException do |exception| flash[:alert] = 'Access denied.' redirect_to :root end end

=== Helpers

Both methods available for controllers are also available for the helpers, so you can use has_permission to show/hide stuff on views.

== TODO

• Generators for models, migrations for both permission types
• Somehow authenticate routes

== Contributing to simple_permissions

• Check out the latest master to make sure the feature hasn't been implemented or the bug hasn't been fixed yet
• Check out the issue tracker to make sure someone already hasn't requested it and/or contributed it
• Fork the project
• Start a feature/bugfix branch
• Commit and push until you are happy with your contribution
• Make sure to add tests for it. This is important so I don't break it in a future version unintentionally.
• Please try not to mess with the Rakefile, version, or history. If you want to have your own version, or is otherwise necessary, that is fine, but please isolate to its own commit so I can cherry-pick around it.

== Copyright

Copyright (c) 2010 Thiago Nuic Vidigal. See LICENSE.txt for further details.