Better restful authentication and authorization with groups and permissions
Ruby
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Failed to load latest commit information.
app
config/locales
generators
lib
rails
.gitignore
CHANGELIST
MIT-LICENSE
README.rdoc
Rakefile
TODO
authentasaurus.gemspec

README.rdoc

Authentasaurus

Authentasaurus is a dynamic group/permission based authentication and authorization engine plugin, its simple to use and easy to setup.

Most helpers are inspired by Devise.

Installation

To start using Authentasaurus follow these simple steps :

  1. install authentasaurus gem by running the following command

    gem install authentasaurus
  2. add authentasaurus to your application environment; in config/environment.rb

    config.gem "authentasaurus"
  3. generate authentasaurus configuration and tasks in your application

    script/generate authentasaurus
  4. setup your migrations using the migration helpers

    in the migration up method just use
      authentasaurus_tables
    in the migration down method
      authentasaurus_drop_tables
  5. migrate your database and setup your default data

    rake authentasaurus:setup_defaults
  6. add your routes

    map.authentasaurus_routes :authorizable, :validatable, :invitable

that's the most basic and quick setup, you can now test your application by running script/server in your project root directory and going to localhost:3000/sessions/sign-in

Authentasaurus is modular, you can install modules as you need them (the previous setup contains all modules), refer to the documentation for more information.

Under the hood

Authentasaurus takes advantage of rails' before_filter; it checks for the appropriate permissions before every action that requires a login, a write or read permission.

At login, authentasaurus would load the user's group permissions into a session hash and then attempts to read that hash when it meets a require helper on a controller.

Authentasaurus uses the following terms:

Area

An area is in plain english the controller's name, so if you have a controller named “PostsController”, the corresponding area name would be “posts” (just as you type it in the generator command)

Group

A group is as the name suggests, each group contains a number of users, and each user inherits the group permissions, also note that at any given time, the user can only belong to one group

Permission

A permission is one of two, either read or write, but take care, read or write is only a naming, and though it doesn't make sense, you could treat a read permission as a write permission and vice versa, but as i said it makes no sense !

Generators

There are two generators in Authentasaurus, the default generator

authentasaurus

and the views generator

authentasaurus_views

The default generator generates configurations and tasks needed by Authentasaurus, while the views generator generates the views used by Authentasaurus in your application, this is useful for customizing authentasaurus and is totally optional.

Authentasaurus views generator takes the name of the user controller, by default it's users

script/generate authentasaurus_views users

You can also use namespaces:

script/generate authentasaurus_views admin/users

Also you can use some options with the Authentasaurus views generator to add the modules you need:

--authorizable

generates the views necessary for authorization (groups, areas and permissions)

--invitable

generates the views necessary for invitable users

--validatable

generates the views necessary for validatable users

You can use a combination of those options like the following example:

script/generate authentasaurus_views users --authorizable --invitable --validatable

Controller Authorization Helpers

There are four main authorization helpers in Authentasaurus for use on controllers:

require_login

requires the user to login before accessing the actions specified

ex: Tells Authentasaurus that the action destroy requires login and that Authentasaurus shouldn't store the request in the session (typically for logout actions)

  • :skip_request - skips saving the original request (to redirect to after login)

  • :user_model - if defined, authentasaurus will use that model instead of the default “User”

  • :if - specifies a method, proc or string to call to determine if the authorization should occur

  • :unless - specifies a method, proc or string to call to determine if the authorization should not occur

    require_login :destroy, :skip_request => true

require_write

requires the user to have a write permission to that area to access the actions specified

ex: Tells Authentasaurus that the actions create_user and delete_user requires login and write permission.

  • :skip_request - skips saving the original request (to redirect to after login)

  • :user_model - if defined, authentasaurus will use that model instead of the default “User”

  • :if - specifies a method, proc or string to call to determine if the authorization should occur

  • :unless - specifies a method, proc or string to call to determine if the authorization should not occur

    require_write :create_user, :delete_user

require_read

requires the user to have a read permission to that area to access the actions specified

ex: Tells Authentasaurus that the action show_user requires login and read permission.

  • :skip_request - skips saving the original request (to redirect to after login)

  • :user_model - if defined, authentasaurus will use that model instead of the default “User”

  • :if - specifies a method, proc or string to call to determine if the authorization should occur

  • :unless - specifies a method, proc or string to call to determine if the authorization should not occur

    require_read :show_user, :if api_key.nil?

You can use any of those class methods on you controllers to restrict access levels like so:

class PostsController < ApplicationController
  require_login :index
  require_read :show
  require_write :new, :create, :edit, :update, :destroy

  def index
    # your code here
  end

  def show
    # your code here
  end

  def new
    # your code here
  end

  def create
    # your code here
  end

  def edit
    # your code here
  end

  def update
    # your code here
  end

  def destroy
    # your code here
  end
end

In addition there is also the has? helper which is available in both Controllers and Views

has?(permission, area=nil)

Checks if the current user has the appropriate permissions for the area specified

ex: has?(:write) or has?(:read, :users)

Copyright © 2010 Mash, Ltd., released under the MIT license