auth-assistant

Provides assistance for setting up an auth solution using devise and cancan auth frameworks.

Installation and configuration

This gem has been designed for Rails 3 only.

Insert gem 'auth-assistant' in your Gemfile Run $ bundle install

The gem should automatically configure itself with Rails after you run the config generator (see below).

$ rails g auth_assist:config NAME where NAME is the name of the role strategy to be used.

To make the extra authentication view helpers accessible from your views

app/helpers/application_helper.rb

module ApplicationHelper
auth_assist_helpers end

Permits

Authorization is setup by designing permits for each can of role to do certain actions. The config generator generates a default permits.rb file in /lib

Please see "cancan 1.1 wiki":http://wiki.github.com/ryanb/cancan/upgrading-to-11 for more options you can use in designing your Permits. The 'owns' convenience method provided, now uses the new hash option so it is also available in the controller using fx:

Book.accessible_by(current_ability)

Example:


module RolePermit
  class Moderator
    def initialize(ability)
      super
    end

    def permit?(user)
      super
      return if !user.role?(:moderator)
      can :read, :all    
      # can manage comment instance if 'user' field on instance points to this user, marking ownership
      user.owns(Comment) 

      # override default 'user_id' field to use 'owner' as foreign key to user.id  
      user.owns(Book, :author)       
    end  
  end
end

View helpers

Currently the view helpers only target use with devise and cancan. The default labels are always loaded from the auth_assist locale file, which is generated by the config generator.

Rest link helpers

Display a link (anchor tag) for a given object only if the current user has permission to execute that action.

show_link or read_link
edit_link or update_link
create_link or new_link
destroy_link or delete_link

Each Rest helper method takes an object for which to create the link. Optionally provide a label as the second argument.

Example usage:

<%= create_link project %> <%= create_link project, 'Create new project' %>

Session link helpers

Show links for performing user authentication and registration actions

log_out_link or sign_out_link
log_in_link or sign_in_link

Each of these methods take an optional options hash. If no role option given, they default to create link for basic 'user' role.

Example usage:

<%= log_out_link %> <%= log_out_link :label => 'Log me out' %> <%= log_out_link :role => 'admin', :label => 'Log me out' %>

Registration link helpers

Show links for performing user authentication and registration actions

register_link or sign_up_link
edit_profile_link or edit_registration_link

Each of these methods take an optional options hash. If no role option given, they default to create link for basic 'user' role.

Example usage:

<%= register_link %> <%= register_link :label => 'Register me' %> <%= register_link :role => 'admin', :label => 'Register me' %>

Show menu links for registration conditionally

edit_user_menu_item or edit_registration_menu_item
register_menu_item or sign_up_menu_item

1) only shown if user is currently logged in 2) only shown if user is NOT currently logged in (and hence already registered)

Example usage:

ul.menu <%= register_menu_item %>

Show menu links for session operations conditionally

logout_menu_item or sign_out_menu_item
login_menu_item or sign_in_menu_item

1) only shown if user is currently logged in 2) only shown if user is NOT currently logged in

ul.menu <%= login_menu_item %> <%= logout_menu_item %>

Block helpers

Execute block if user is logged in (or not logged in)

user_block
not_user_block

Execute block if user is logged and is admin (or not admin)

admin_block
not_admin_block

Execute block if ip is localhost (or not localhost)

localhost_block
not_localhost_block

Execute block if role is included in list of roles (or not)

roles_block
not_roles_block

Block area helpers

Create div.user 'area' and execute block if user is logged in as a user (or not)

user_area
not_user_area

Create div.admin 'area' and execute block if user is admin (or not admin)

admin_area
not_admin_area

Example:


<% admin_area do %> 
  ul.admin_menu
  ...

If logged in as admin, results in:

div.admin
  ul.admin_menu  
   ...

Roles block area helpers

Creates are if role is one included in list of roles (or not)

roles_area
not_roles_area

Example:


<% roles_area 'admin, 'editor', :class => 'special' do %> 
  ul.admin_menu
  ...
  
If logged in as either 'editor' or 'admin', results in:

div.special
  ul.admin_menu  
   ...

Misc helpers

user? -
admin?
role?
localhost?

Examples

     
<%= current_user.username if user? %>
<%= "Admin: #{current_user.username}" if admin? %>  
<%= "Special user!" if role?('admin', 'reviewer') %>  
<%= "Running on localhost!" if localhost? %>

Generators

The following generators are available

config - configure with new strategy
clear - clear existing strategy
views - generate partials for use in views

Config Generator

The config generator generates a configuration initializer file for setting up auth_assistant to use a particular role strategy.

$ rails g auth_assistant:config NAME

NAME is the name of a role strategy.

Strategies with a single role for each user

admin_field
role_field
role_assignment

Strategies with multiple roles for each user

roles_field
roles_mask
multi_role_assignment

Currently role groups are not supported. Feel free to provide an add-on to support this or integrate with an existing 'role group' solution.

Example usage:

$ rails g auth_assist:config admin_field

Also ensure devise is setup and configured

$ rails g auth_assist:config roles_mask --devise

To also create an administrator model using STI to inherit and override the basic user strategies

$ rails g auth_assist:config roles_field --administrator

To ensure a user model migration is generated

$ rails g auth_assist:config role_field --migration

Clear Generator

The clear generator removes any existing strategy file and optionally generates a migration to remove any tables and fields related to the existing role strategy. This allows you to easily change role strategy by first running the clear generator and then the config generator with a new strategy.

$ rails g auth_assist:clear NAME

Example usage:

$ rails g auth_assist:clear role_field

Views Generator

The views generator generates views (partials) for use with Menus.

$ rails g auth_assistant:views

Create HAML views

`$ rails g auth_assist:views --template_engine haml'

Example usage:


  ul.menu
    render 'auth_assist/login_items'                              
    render 'auth_assist/registration_items'

  ul.admin_menu_
    render 'auth_assist/admin_login_items'

== Note on Patches/Pull Requests

Fork the project.
Make your feature addition or bug fix.
Add tests for it. This is important so I don't break it in a future version unintentionally.
Commit, do not mess with rakefile, version, or history. (if you want to have your own version, that is fine but bump version in a commit by itself I can ignore when I pull)
Send me a pull request. Bonus points for topic branches.

auth-assistant

Installation and configuration

app/helpers/application_helper.rb

Permits

View helpers

Rest link helpers

Session link helpers

Registration link helpers

Registration Menu item helpers

Session Menu item helpers

Block helpers

Block area helpers

Roles block area helpers

Misc helpers

Generators

Config Generator

Clear Generator

Views Generator