aegis
aegis copied to clipboard
Complete authorization solution for Rails that supports roles and a RESTish, resource-style declaration of permission rules.
= Aegis - A complete authorization solution for Rails
Aegis is an authorization solution for Ruby on Rails that supports roles and a RESTish, resource-style declaration of permission rules. Getting started with Aegis is easy and requires very little integration. As your authorization requirements become more complex, Aegis will grow with you.
== End of life notice!
The authors of this gem have moved on to create {Consul}[https://github.com/makandra/consul], our next-gen authorization solution. While Aegis remains a stable solution for Rails 2, this gem is not being developed further.
If you are looking for Rails 3+ support you might want to browse through {forks of Aegis}[https://github.com/bitcababy/aegis/network].
If you are interested in taking over future maintenance of Aegis, write to [email protected] regarding transfer of gem ownership. Please attach links to work you did on Aegis in a fork, so we can know you are serious about this.
== Getting started
All your permissions live in a single class Permissions. Permissions are described using resources, similiar to your routes. Your permission resources can match those in your routes, but don't have to.
Access to resources or individual actions can be granted or denied to specific roles.
class Permissions < Aegis::Permissions
role :user
role :admin
resources :projects do
allow :everyone
end
resources :users do
allow :admin
end
end
To give your user model a role, it needs to have an attribute +role_name+. The has_role macro wires everything together:
class User < ActiveRecord::Base has_role end
You can now check if a user has permission to access a given action in your controllers and views:
<% if current_user.may_update_project? @project %> <%= link_to 'Edit', edit_project_path(@project) %> <% end %>
You can protect all actions in a controller through an Aegis resource with a single line:
class ProjectsController < ApplicationController permissions :projects end
== Further reading
You are now familiar with the basic use case. Aegis can do a lot more than that. There is an awesome {documentation wiki}[http://wiki.github.com/makandra/aegis/] with detailed information on many basic and advanced topics, including:
- {Defining roles and basic permissions}[http://wiki.github.com/makandra/aegis/defining-roles-and-basic-permissions]
- {Checking permissions}[http://wiki.github.com/makandra/aegis/checking-permissions]
- {Giving your user model a role}[http://wiki.github.com/makandra/aegis/giving-your-user-model-a-role]
- {Defining permissions with resources}[http://wiki.github.com/makandra/aegis/defining-permissions-with-resources]
- {Controller integration}[http://wiki.github.com/makandra/aegis/controller-integration]
- {Giving default access to superusers}[http://wiki.github.com/makandra/aegis/giving-default-access-to-superusers]
- {Distinguishing between reading and writing actions}[http://wiki.github.com/makandra/aegis/distinguishing-between-reading-and-writing-actions]
- {Aliasing actions}[http://wiki.github.com/makandra/aegis/aliasing-actions]
- {Checking permissions when no user is signed in}[http://wiki.github.com/makandra/aegis/checking-permissions-when-no-user-is-signed-in]
- {Handling denied permissions in your controllers}[http://wiki.github.com/makandra/aegis/handling-denied-permissions-in-your-controllers]
- {Changing behavior when a permission is undefined}[http://wiki.github.com/makandra/aegis/changing-behavior-when-a-permission-is-undefined]
- {Multiple roles per user}[http://wiki.github.com/makandra/aegis/multiple-roles-per-user]
- {Testing permissions}[http://wiki.github.com/makandra/aegis/testing-permissions]
- {Upgrading to Aegis 2}[http://wiki.github.com/makandra/aegis/upgrading-to-aegis-2]
== Installation
Aegis is a gem, which you can install with sudo gem install aegis
In Rails 2, add the following to your environment.rb: config.gem 'aegis'
In Rails 3, add the following to your Gemfile: gem 'aegis'
== Compatibility
Aegis was tested in Rails 2 only. If you are looking for Rails 3+ support you might want to browse through {forks of Aegis}[https://github.com/bitcababy/aegis/network].
== Credits
Henning Koch, Tobias Kraze
{makandra.com}[http://makandra.com/]
{gem-session.com}[http://gem-session.com/]