Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Newer
Older
100755 95 lines (61 sloc) 3.837 kb
c5552cd some started RDOC. detailled API still todo.
Henning authored
1 = Aegis - A complete authorization solution for Rails
1b04f3d expanded README.rdoc
makandra authored
2
c5552cd some started RDOC. detailled API still todo.
Henning authored
3 Aegis is an authorization solution for Ruby on Rails that supports roles and a RESTish, resource-style declaration of
4 permission rules. Getting started with Aegis is easy and requires very little integration. As your authorization
5 requirements become more complex, Aegis will grow with you.
1b04f3d expanded README.rdoc
makandra authored
6
85ab2dc expanded documentation
makandra authored
7
27d9829 shorthand definitions, updated RDoc
Henning authored
8 == Getting started
85ab2dc expanded documentation
makandra authored
9
27d9829 shorthand definitions, updated RDoc
Henning authored
10 All your permissions live in a single class <tt>Permissions</tt>.
11 Permissions are described using <tt>resources</tt>, similiar to your routes.
12 Your permission resources can match those in your routes, but don't have to.
1b04f3d expanded README.rdoc
makandra authored
13
c5552cd some started RDOC. detailled API still todo.
Henning authored
14 Access to resources or individual actions can be granted or denied to specific roles.
1b04f3d expanded README.rdoc
makandra authored
15
27d9829 shorthand definitions, updated RDoc
Henning authored
16 class Permissions < Aegis::Permissions
1b04f3d expanded README.rdoc
makandra authored
17
27d9829 shorthand definitions, updated RDoc
Henning authored
18 role :user
19 role :admin
c5552cd some started RDOC. detailled API still todo.
Henning authored
20
27d9829 shorthand definitions, updated RDoc
Henning authored
21 resources :projects do
22 allow :everyone
23 end
1b04f3d expanded README.rdoc
makandra authored
24
27d9829 shorthand definitions, updated RDoc
Henning authored
25 resources :users do
26 allow :admin
1b04f3d expanded README.rdoc
makandra authored
27 end
28
27d9829 shorthand definitions, updated RDoc
Henning authored
29 end
1b04f3d expanded README.rdoc
makandra authored
30
27d9829 shorthand definitions, updated RDoc
Henning authored
31 To give your user model a role, it needs to have an attribute +role_name+. The <tt>has_role</tt> macro wires everything together:
1b04f3d expanded README.rdoc
makandra authored
32
27d9829 shorthand definitions, updated RDoc
Henning authored
33 class User < ActiveRecord::Base
34 has_role
35 end
1b04f3d expanded README.rdoc
makandra authored
36
27d9829 shorthand definitions, updated RDoc
Henning authored
37 You can now check if a user has permission to access a given action in your controllers and views:
1b04f3d expanded README.rdoc
makandra authored
38
27d9829 shorthand definitions, updated RDoc
Henning authored
39 <% if current_user.may_update_project? @project %>
40 <%= link_to 'Edit', edit_project_path(@project) %>
41 <% end %>
1b04f3d expanded README.rdoc
makandra authored
42
c5552cd some started RDOC. detailled API still todo.
Henning authored
43 You can protect all actions in a controller through an Aegis resource with a single line:
e47e2e9 @kratob updated README
kratob authored
44
fd534d2 @henning-koch fixed an example in the README
henning-koch authored
45 class ProjectsController < ApplicationController
27d9829 shorthand definitions, updated RDoc
Henning authored
46 permissions :projects
47 end
61c4d8d subsections for README
makandra authored
48
85ab2dc expanded documentation
makandra authored
49
27d9829 shorthand definitions, updated RDoc
Henning authored
50 == Further reading
30c9ecb @henning-koch clarified our stance on multiple roles per user
henning-koch authored
51
27d9829 shorthand definitions, updated RDoc
Henning authored
52 You are now familiar with the basic use case. Aegis can do a *lot* more than that.
f7f288b @henning-koch fixed typo in rdoc
henning-koch authored
53 There is an awesome {documentation wiki}[http://wiki.github.com/makandra/aegis/] with detailed information on many basic and advanced topics, including:
30c9ecb @henning-koch clarified our stance on multiple roles per user
henning-koch authored
54
27d9829 shorthand definitions, updated RDoc
Henning authored
55 * {Defining roles and basic permissions}[http://wiki.github.com/makandra/aegis/defining-roles-and-basic-permissions]
56 * {Checking permissions}[http://wiki.github.com/makandra/aegis/checking-permissions]
57 * {Giving your user model a role}[http://wiki.github.com/makandra/aegis/giving-your-user-model-a-role]
58 * {Defining permissions with resources}[http://wiki.github.com/makandra/aegis/defining-permissions-with-resources]
59 * {Controller integration}[http://wiki.github.com/makandra/aegis/controller-integration]
60 * {Giving default access to superusers}[http://wiki.github.com/makandra/aegis/giving-default-access-to-superusers]
61 * {Distinguishing between reading and writing actions}[http://wiki.github.com/makandra/aegis/distinguishing-between-reading-and-writing-actions]
62 * {Aliasing actions}[http://wiki.github.com/makandra/aegis/aliasing-actions]
63 * {Checking permissions when no user is signed in}[http://wiki.github.com/makandra/aegis/checking-permissions-when-no-user-is-signed-in]
64 * {Handling denied permissions in your controllers}[http://wiki.github.com/makandra/aegis/handling-denied-permissions-in-your-controllers]
65 * {Changing behavior when a permission is undefined}[http://wiki.github.com/makandra/aegis/changing-behavior-when-a-permission-is-undefined]
66 * {Multiple roles per user}[http://wiki.github.com/makandra/aegis/multiple-roles-per-user]
2c038b5 @henning-koch new be_allowed_to matcher, specs for matchers
henning-koch authored
67 * {Testing permissions}[http://wiki.github.com/makandra/aegis/testing-permissions]
27d9829 shorthand definitions, updated RDoc
Henning authored
68 * {Upgrading to Aegis 2}[http://wiki.github.com/makandra/aegis/upgrading-to-aegis-2]
30c9ecb @henning-koch clarified our stance on multiple roles per user
henning-koch authored
69
70
c5552cd some started RDOC. detailled API still todo.
Henning authored
71 == Installation
72
e322205 @henning-koch updated installation instructions, gemspec
henning-koch authored
73 Aegis is a gem, which you can install with
74 sudo gem install aegis
75
76 In Rails 2, add the following to your <tt>environment.rb</tt>:
fd356ae removed gemcutter references from rdoc
Henning authored
77 config.gem 'aegis'
c5552cd some started RDOC. detailled API still todo.
Henning authored
78
e322205 @henning-koch updated installation instructions, gemspec
henning-koch authored
79 In Rails 3, add the following to your <tt>Gemfile</tt>:
80 gem 'aegis'
c5552cd some started RDOC. detailled API still todo.
Henning authored
81
3af9727 @henning-koch updated README
henning-koch authored
82
83 == Rails 3 compatibility
84
8db1b1c @henning-koch updated README
henning-koch authored
85 We cannot guarantee Rails 3 compatibility at this point, but we will upgrade the gem when Rails 3 is released.
86
c5552cd some started RDOC. detailled API still todo.
Henning authored
87
88 == Credits
07749f7 updated README
makandra authored
89
90 Henning Koch, Tobias Kraze
91
5d1ed7d @henning-koch changed link in the README
henning-koch authored
92 {makandra.com}[http://makandra.com/]
c5552cd some started RDOC. detailled API still todo.
Henning authored
93
5d1ed7d @henning-koch changed link in the README
henning-koch authored
94 {gem-session.com}[http://gem-session.com/]
Something went wrong with that request. Please try again.