authorization 1.0.11

data/CHANGELOG.txt

@@ -0,0 +1,170 @@
+TO DO
++ Add Right model generator and DB-backed way of handling rights in addition to inlined "permit" checks
++ Added namespacing to @options instance variable to prevent possible name clashes
++ Add test generator instead of handling tests in test apps
++ Add support for groups
++ Extend grammar to allow "(admin or moderator or some_role) of some_model" (?) [Chris Hapgood]
++ Extend coverage to models. Look at Bruce Perens's ModelSecurity and access with_scope. (9/3006 - Recently investigated extension to model and the most programmer-friendly DSLs may require too much hacking on ActiveRecord.)
+
+
+CHANGES (from most recent to oldest)
+
+
+=== 1.0.10 release (February 27, 2008)
+
+* Patch Series : Granular redirection configuration submitted by Thomas Weibel
+
+  WARNING : If you are upgrading from a previous install you may need
+  to change some configuration settings in your environment.rb file.
+
+  Remove DEFAULT_REDIRECTION_HASH config
+  Added granular LOGIN_REQUIRED_REDIRECTION hash or path config
+  Added granular PERMISSION_DENIED_REDIRECTION hash or path config
+  Added STORE_LOCATION_METHOD config
+  Support custom flash messages for each redirection type
+  Updated README.txt to provide instructions.
+  Enhanced support for integration with restful_authentication plugin.
+
+=== 1.0.9 release (February 26, 2008)
+
+* Patch #8571 : Add type argument to is_role_of_what submitted by Aslak Hellesøy (aslak_hellesoy)
+
+  In my RESTful index views for an AR type I often want to list all of the records *for a given type* for which the current
+  user has the role "show". (As opposed to getting *any* record for which the user has the role)
+
+  In order to achieve this, I have patched identity.rb so tht I can do this:
+
+  def index
+    if current_user.permit? 'admin'
+      # show all projects
+      @projects = Project.find(:all)
+    else
+      @projects = current_user.is_show_for_what(Project)
+    end
+  end
+
+=== 1.0.8 release (February 26, 2008)
+
+* Patch #11352 : Fixes a bug with role_regex and simple quoted roles submitted by 'a French RoR developer'
+
+  Documentation says:
+
+  <role> ::= /\w+/ | /'.*'/
+
+  But the next permission string isn't well parsed: "  'abcd:efgh' or 'abcd:ijkl'  "
+  You get an error because the role_regex defined in parser.rb eats every simple quote between the first and the last
+  simple quote in the string.
+
+  So i patched the two instances of role_regex in parser.rb, from this:
+  role_regex = '\s*(\'\s*(.+)\s*\'|([A-Za-z]\w*))\s*'
+
+  to this (the question mark ends the first pattern as soon as possible, avoiding the inner simple quotes to be eaten):
+  role_regex = '\s*(\'\s*(.+?)\s*\'|([A-Za-z]\w*))\s*'
+
+=== 1.0.7 release (February 25, 2008)
+
+* Patch #9431 : Fixes a bug in identity.rb submitted by Michel Martens (blaumag)
+
+  If some authorizable instance accepts a role, then it responds true when queried for has_[role_name]?
+
+  Example:
+  country.has_kings? #=> false
+
+  user.has_role "king", country
+  country.has_kings? #=> true
+
+  user.has_no_role "king", country
+  country.has_kings? #=> true
+
+  The last time, country.has_kings? should be false.
+
+=== 1.0.6 release (February 25, 2008)
+
+* Patch #12170 : Additional HABTM options for acts_as_authorized_user
+  A very simple patch that allows options to be passed to the has_and_belogs_to_many relationship. This seems necessary
+  if the "User" object has a different name from the table name. has_and_belong_to_many does not automatically
+  use the table set by the "User" object so it must be specified (along with the foreign key if applicable).
+
+  Patch submitted by Eric Anderson (eric1234)
+
+=== 1.0.5 release (February 25, 2008)
+
+* Feature : Add additional test for current_user being set to the symbol ':false'.
+  This is for compatibility with the restful_authentication plugin which will
+  set current_user to :false on a bad login.  Previously we were only testing
+  for current_user.nil? which was incomplete.
+
+=== 1.0.4 release (February 25, 2008)
+
+* Bugfix : RubyForge bug #9368.  Problems with about.yml
+  Fixes a minor bug in the about.yml plugin metadata file
+  so that it will parse cleanly. [GR]
+
+=== 1.0.3 release (February 17, 2008)
+
+* Minor changes to USAGE text for ./script/generate role_model
+
+=== 1.0.2 release (February 17, 2008)
+
+* From this release forward the plugin requires use of Ruby on Rails version 2.x.  Version 1.0.1 is the final release fully compatible with Rails 1.2.x.
+* Upgraded the database migration generator to create the new Rails 2.0.x style 'sexy migrations'.
+
+=== 1.0.1 release (February 17, 2008)
+
+* Moved source code to public Git repository at GitHub.com (http://github.com/DocSavage/rails-authorization-plugin/tree/master)
+* Removed attr_protected declaration from acts_as_authorized_user, acts_as_authorizable methods.  These conflicted with usage of the Authorization plugin with models generated by the restful_authentication generator or any model that specified the safer attr_accessible whitelist.  RA encourages the safer attr_accessible whitelisting of attributes that are accessible from its models.  You cannot apply both attr_accessible and attr_protected in the same model.  Users are encouraged to specify a whitelist of attr_accessible model attributes for their applications security. [grempe]
+
+=== SVN
+
+* Performance improvement for has_role?  [Sean Geoghegan]
+
+* Allow customization of message on redirection after failed authorization (:redirect_message option) [Joey Geiger]
+
+* Patch to allow authorizable objects that use single table inheritance (STI) [Sean Geoghegan]
+
+=== 1.0 release (Sept 13, 2006)
+
+* Added attr_protected for habtm and has_many role ids to block security concern if developers use update_attributes(params[:auth_obj]) on an authorizable object [Michael Schuerig]
+
+* Use before_filter rather than prepend_before_filter so necessary instance variables (and methods) can be established before trying authorization checks. This fix came about for Mephisto blog where a class-level permit "admin of site" was used. The site attribute was set in a before_filter. If you prepend your authorization filter, it will execute before any other before_filter, which is probably not a good idea.
+
+* Add "about" yaml for future Rails plugin directory.
+
+* Cleaned up exception handling a little [due to suggestion by Michael Schuerig]
+
+* Add generator for role model and migration, e.g., "script/generate role_model Role".
+  Role model must be called "Role" at this time. More general naming as a TO DO.
+
+* Removed simple_roles_table to simplify plugin.
+
+* Moved all files in Authorization namespace into /publishare subdirectory
+  to reduce danger of clashes in load path [nod to Michael Schuerig].
+
+* Small code refinement patch [Michael Schuerig]
+
+* The colon preceding a model name in the authorization expression is now optional. The parser uses accepted prepositions to disambiguate models from roles.
+
+* Change default parser from Recursive Descent parser to Eval parser.
+Currently implemented recursive descent parser doesn't handle left-sided
+boolean expressions well. Eval parser relies on Ruby (good thing), but
+wherever there's an eval, we have to be more careful.
+
+* Will start linking to and monitoring forum area at RubyForge
+http://rubyforge.org/forum/?group_id=1797
+
+* Added changelog :)
+
+* Added return false to handle_redirection to short-circuit filters if
+redirect occurs. This is second fix to prevent double renders.
+
+* Changed the requires to pull files from the plugin directory. (Necessary for name conflicts between plugin and apps)
+
+* Minor fixes to update documentation
+
+=== 1.0 rc3 (July 19, 2006)
+
+* Fix to prevent double redirect
+
+* Fix to migration examples
+
+... see svn log

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2006 William T Katz
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.rdoc

@@ -0,0 +1,512 @@
+= Authorization plugin
+
+This plugin provides a flexible way to add authorization to Rails.
+
+The authorization process decides whether a user is allowed access to some
+feature.  It is distinct from the authentication process, which tries to
+confirm a user is authentic, not an imposter. There are many authentication
+systems available for Rails, e.g., acts_as_authenticated and LoginEngine. This
+authorization system will play nicely with them as long as some simple
+requirements are met:
+
+1. User objects are available that implement a has_role?(role,
+   authorizable_object = nil) method. This requirement can be easily
+   handled by using acts_as_authorized_user in the User-like class.
+
+2. If you want to use "role of model" authorization expressions, like "owner of
+   resource" or "eligible for :award", then your models with roles must
+   implement an accepts_role?(role, user) method. This requirement can
+   be handled by using acts_as_authorizable in the model class.
+
+The authorization plugin provides the following:
+
+* A simple way of checking authorization at either the class or instance method
+  level using #permit and #permit?
+
+* Authorization using roles for the entire application, a model class, or an
+  instance of a model (i.e., a particular object).
+
+* Some english-like dynamic methods that draw on the defined roles. You will be
+  able to use methods like "user.is_fan_of angelina" or "angelina.has_fans?",
+  where a 'fan' is only defined in the roles table.
+
+* Pick-and-choose a mixin for your desired level of database complexity. For
+  all the features, you will want to use "object roles table" (see below)
+
+
+== Example Usage
+
+  class MeetingController < ApplicationController
+
+    permit "rubyists and wanna_be_rubyists", :except => :public_page
+
+    def public_page
+      render :text => "We're all in Chicago"
+    end
+
+    def secret_info
+      permit "interested in Answers and (matz or dhh)" do
+        render :text => "The Answer = 42"
+      end
+    end
+
+    def find_apprentice
+      @founder = User.find_by_name('matz')
+      permit "'inner circle' of :founder" do
+        if request.post?
+          apprentice = User.find_by_skillset(params[:uber_hacker])
+          ruby_community = Group.find_by_name('Ruby')
+          ruby_community.accepts_role 'yarv_builder', apprentice
+        end
+      end
+    end
+
+    def rails_conf
+      @meeting = Meeting.find_by_name('RailsConf')
+      permit "attendees of :meeting or swedish_mensa_supermodels" do
+        venue = Hotel.find_by_name("Wyndham O'Hare")
+        current_user.is_traveller_to venue
+        if permit? "traveller to :venue and not speaker"
+          Partay.all_night_long
+          @misdeeds = current_user.is_participant_in_what
+        end
+      end
+    end
+
+  end
+
+
+== Installation
+
+Installation of the Authorization plugin is quick and easy.
+
+=== Step 1
+
+Open a terminal and change directory to the root of your
+Ruby on Rails application referred to here as 'RAILS_ROOT'. You
+can choose to install the plugin using the standard Ruby on Rails tools (recommended),
+as a Git sub-module, or by grabbing a tarball.
+
+=== Step 2a (Standard install, recommended)
+
+NOTE : This assumes you are using a current (Rails 2.1.x +) version of Rails which
+now has built in support for installing a plugin directly from a git repo.  This also assumes
+you have Git installed and working properly.  You can always use the manual install shown below
+if this is not true.
+
+Run the following command in your RAILS_ROOT:
+
+  ./script/plugin install git://github.com/DocSavage/rails-authorization-plugin.git
+
+This will install the latest version of the plugin from our GitHub master repo
+into your RAILS_ROOT/vendor/plugins/rails-authorization-plugin directory.
+
+=== Step 2b (Alternative install using Git sub-module, for advanced users of the Git SCM)
+
+The source code for this plugin is maintained in a Git SCM
+repository. The Git repository will always have the latest
+version of the code.
+
+You can install the plugin using Git sub-modules (which
+are akin to using SVN externals). Installing this way allows
+you to update the plugin code later if needed (but note that
+it will not update any generated code created earlier by this
+plugin such as migrations, which you will need to update manually).
+Also note that if you are deploying your code using Capistrano
+this method may cause issues if you are not careful (e.g. the code
+will be deployed but the sub-modules will not be updated or
+installed at all).
+
+From your RAILS_ROOT directory run:
+
+  git submodule add git://github.com/DocSavage/rails-authorization-plugin.git vendor/plugins/authorization
+
+You should be able to update this plugin in the future with
+the simple command (again from RAILS_ROOT):
+
+  git submodule update
+
+=== Step 2c (Alternative manual install from tarball)
+
+If you like to install the old school manual way, feel free to download a copy of
+latest master branch plugin code from:
+
+http://github.com/docsavage/rails-authorization-plugin/tarball/master
+
+Once downloaded, rename the top level dir to 'rails-authorization-plugin' and then
+you can stuff that directory in your RAILS_ROOT/vendor/plugins directory.
+
+
+== Configuration
+
+These instructions will show you how to do the initial configuration
+of the plugin.
+
+=== Choose a Mixin Type
+
+==== Hardwired Roles
+
+This is the simplest way to use the plugin and requires no database.
+Roles are assumed to be coded into the Model classes using the
+<tt>has_role?(role, obj = nil)</tt> method. This method is however more
+limited in the functionality available to you.
+
+==== Object Roles (Recommended, DB Required)
+
+The Object Roles Table mixin provides full support for authorization
+expressions within a database by add a polymorphic field to the
+Role table. Because roles have polymorphic associations to an
+authorizable object, we can assign a user to a role for any model
+instance. So you could declare user X to be a moderator for workshop Y,
+or you could make user A be the owner of resource B.
+
+The identity module adds a number of dynamic methods that use defined
+roles. The user-like model gets methods like `user.is_moderator_of
+group (sets user to "moderator" of group`), user.is_moderator? (returns
+true/false if user has some role "moderator"), and group.has_moderators
+(returns an array of users that have role "moderator" for the group). If
+you prefer not to have these dynamic methods available, you can simply
+comment out the inclusion of the identity module within object_roles_table.rb.
+
+=== Initial Configuration Instructions
+
+Choose one of the installation types identified above and make sure your
+application provides a current_user method or something that returns the
+current user object (resful_authentication provides this out of the box).
+
+At the top of your RAILS_ROOT/config/environment.rb file add something
+like the following (customized for your controllers and actions of course):
+
+  ...
+
+  # Authorization plugin for role based access control
+  # You can override default authorization system constants here.
+
+  # Can be 'object roles' or 'hardwired'
+  AUTHORIZATION_MIXIN = "object roles"
+
+  # NOTE : If you use modular controllers like '/admin/products' be sure
+  # to redirect to something like '/sessions' controller (with a leading slash)
+  # as shown in the example below or you will not get redirected properly
+  #
+  # This can be set to a hash or to an explicit path like '/login'
+  #
+  LOGIN_REQUIRED_REDIRECTION = { :controller => '/sessions', :action => 'new' }
+  PERMISSION_DENIED_REDIRECTION = { :controller => '/home', :action => 'index' }
+
+  # The method your auth scheme uses to store the location to redirect back to
+  STORE_LOCATION_METHOD = :store_location
+
+  # standard rails config below here
+  Rails::Initializer.run do |config|
+
+  ...
+
+* Set the AUTHORIZATION_MIXIN constant to object roles or hardwired.  (See init.rb in this plugin for how the role support is mixed in.)
+* Set the LOGIN_REQUIRED_REDIRECTION to match the path or a hash with the :controller and :action for your applications login page.
+* Set the PERMISSION_DENIED_REDIRECTION to match the path or a hash with the :controller and :action for your applications permission denied page.
+* Set the STORE_LOCATION_METHOD to the method your application uses for storing the current URL that the user should return to after authentication (e.g. store_location).
+* See the PLUGIN_DIR\lib\authorization.rb file for the default values of LOGIN_REQUIRED_REDIRECTION, PERMISSION_DENIED_REDIRECTION and STORE_LOCATION_METHOD.
+
+
+=== Create the database tables
+
+If you plan to use the object roles method you will need to setup a few
+database tables. We have provided a database migration file
+(Rails 2.0+ compatible) that will make this process easy for you.
+If you plan to use the hardwired mixin, no extra database tables
+are required. and you can skip to the next step.
+
+Run the following command from your RAILS_ROOT (Note : The generator
+takes a model name as its argument, which at this time must be 'Role'.):
+
+  ./script/generate role_model Role
+
+This will create:
+
+  Model:      RAILS_ROOT/app/models/role.rb
+  Test:       RAILS_ROOT/test/unit/role_test.rb
+  Fixtures:   RAILS_ROOT/test/fixtures/roles.yml
+  Migration:  RAILS_ROOT/db/migrate/###_add_role.rb
+
+And now you will need to run a database migration from your RAILS_ROOT:
+
+  rake db:migrate
+
+=== Jumpstarting with a mixin
+
+Now we need to add the methods needed by each of your models that will
+participate in role based authorization. Typically these models fall into
+two categories, the User model, and all other models that will have
+roles available for use.
+
+For a typical installation you would add both mixins to your User model.
+
+  class User < ActiveRecord::Base
+
+    # Authorization plugin
+    acts_as_authorized_user
+    acts_as_authorizable
+
+  ...
+
+Then in each additional model that you want to be able to restrict based
+on role you would add just the acts_as_authorizable mixin like this:
+
+  class Event < ActiveRecord::Base
+
+    acts_as_authorizable
+
+  ...
+
+You are done with the configuration!
+
+
+== The Specifics
+
+=== permit and permit?
+
+permit and permit? take an authorization expression and a hash of options that
+typically includes any objects that need to be queried:
+
+  permit <authorization expression> [, options hash ]
+  permit? <authorization expression> [, options hash ]
+
+The difference between permit and permit? is redirection. permit is a
+declarative statement and redirects by default. It can also be used as a class
+or an instance method, gating the access to an entire controller in a
+before_filter fashion.
+
+permit? is only an instance method, can be used within expressions, does not
+redirect by default.
+
+The authorization expression is a boolean expression made up of permitted
+roles, prepositions, and authorizable models. Examples include "admin" (User
+model assumed), "moderator of :workshop" (looks at options hash and then
+@workshop), "'top salesman' at :company" (multiword roles delimited by single
+quotes), or "scheduled for Exam" (queries class method of Exam).
+
+Note that we can use several permitted prepositions ('of', 'for', 'in', 'on',
+'to', 'at', 'by'). In the discussion below, we assume you use the "of"
+preposition. You can modify the permitted prepositions by changing the constant
+in Authorization::Base::Parser.
+
+* If a specified role has no "of <model>" designation, we assume it is a user
+  role (i.e., the model is the user-like object).
+
+* If an "of model" designation is given but no "model" key/value is supplied in
+  the hash, we check if an instance variable @model if it's available.
+
+* If the model is capitalized, we assume it's a class and query
+  <tt>Model#self.accepts_role?</tt> (the class method) for the
+  permission. (Currently only available in ObjectRolesTable mixin.)
+
+For each role, a query is sent to the appropriate model object.
+
+The grammar for the authorization expression is:
+
+         <expr> ::= (<expr>) | not <expr> | <term> or <expr> | <term> and <expr> | <term>
+         <term> ::= <role> | <role> <preposition> <model>
+  <preposition> ::= of | for | in | on | to | at | by
+        <model> ::= /:*\w+/
+         <role> ::= /\w+/ | /'.*'/
+
+Parentheses should be used to clarify permissions. Note that you may prefix the
+model with an optional ":" -- the first versions of Authorization plugin made
+this mandatory but it's now optional since the mandatory preposition makes
+models unambiguous.
+
+==== Options
+
+  :allow_guests => false.
+
+We can allow permission processing without a
+current user object. The default is false.
+
+  :user => YourUserObject.
+
+The name of your user object.
+
+  :get_user_method => method_name
+
+The method name provided should return a user
+object. Default is #current_user, which is the how
+acts_as_authenticated works.
+
+  :only => [ :method1, :method2 ]
+
+Array of methods to apply permit (not valid when used in instance methods)
+
+  :except => [ :method1, :method2 ]
+
+Array of methods that won't have permission checking (not valid when used in instance methods)
+
+  :redirect => boolean
+
+Default is true. If false, permit will not redirect to denied page.
+
+  :login_required_redirection => path or hash
+
+  default is "{ :controller => 'session', :action => 'new' }"
+
+Path or Hash where user will be redirected if not logged in ()
+
+  :login_required_message => 'my message'
+
+A string to present to your users when login is required. Default is 'Login is required to access the requested page.'
+
+  :permission_denied_redirection => path or hash
+
+Path or Hash where user will be redirected if logged in but not authorized (default is '')
+
+  :permission_denied_message => 'my message'
+
+Message that will be presented to the user when permission is denied.  Default is 'Permission
+denied. You cannot access the requested page.'
+
+=== Setting and getting the roles
+
+Roles are set by #has_role and #accepts_role methods that are mixed into the
+User-like object and the authorizable models. User objects can set roles and
+optionally an object scope for that role:
+
+  user.has_role 'site_admin'
+  user.has_role 'moderator', group
+  user.has_no_role 'site_admin'
+  user.has_no_role 'moderator', group
+  user.has_role 'member', Group
+
+Note that the last method sets role "member" on a class "Group". Roles can be
+set with three scopes: entire application (no class or object specified), a
+model class, or an instance of a model (i.e., a model object).
+
+Models set roles for specific users:
+
+  a_model.accepts_role 'moderator', user
+  a_model.accepts_no_role 'moderator', user
+  Model.accepts_role 'class moderator', user
+
+The method language has been chosen to aid memory of the argument order. A user
+has a role "foo", so the role string immediately follows has_role. Similarly, a
+model accepts a role "foo", so the role string immediately follows
+accepts_role. Then we append the scope.
+
+Sometimes the user-like object might be an authorizable object as well, for example, when you
+allow 'friend' roles for users. In this case, the user-like object can be declared to be
+<tt>acts_as_authorizable</tt> as well as <tt>acts_as_authorized_user</tt>.
+
+Role queries follow the same pattern as the setting of roles:
+
+  user.has_role? 'moderator'
+  user.has_role? 'moderator', group
+  user.has_role? 'member', Group
+
+  a_model.accepts_role? 'moderator', user
+  Model.accepts_role? 'moderator', user
+
+When a user is queried without specifying either a model class or object, it
+returns true if the user has *any* matching role. For example,
+<tt>user.has_role? 'moderator'</tt> returns true if the user is 'moderator' of
+a class, a model object, or just a generic 'moderator'.  Note that if you say
+<tt>user.has_role 'moderator'</tt>, the user does not become 'moderator' for
+all classes and model objects; the user simply has a generic role 'moderator'.
+
+==== Dynamic methods through the Identity mixin
+
+The Object Roles Table version includes some dynamic methods that use the roles
+table.  For example, if you have roles like "eligible", "moderator", and
+"owner", you'll be able to use the following:
+
+  user.is_eligible_for_what   --> returns array of authorizable objects for which user has role "eligible"
+  user.is_moderator_of? group --> returns true/false
+  user.is_moderator_of group  --> sets user to have role "moderator" for object group.
+  user.is_administrator       --> sets user to have role "administrator" not really tied to any object.
+
+Models get has_* methods:
+
+  group.has_moderators  --> returns array of users with role "moderator" on that group
+  group.has_moderators? --> returns true/false
+
+Allowed prepositions are optional in the above dynamic methods. They are simply
+syntactic sugar.  For example, the following are equivalent:
+
+  user.is_member_of group
+  user.is_member_for group
+  user.is_member group
+
+Allowed prepositions are required in the authorization expressions because they
+are used to distinguish "role" and "role of :model" and "role of Model".
+
+If you prefer not to pollute your namespace with these dynamic methods, do not
+include the Identity module in <tt>object_roles_table.rb</tt>.
+
+=== Pattern of use
+
+We expect the application to provide the following methods:
+
+==== #current_user
+
+Returns some user object, like an instance of my favorite class,
+<tt>UserFromMars</tt>.  A <tt>user</tt> object, from the Authorization
+viewpoint, is simply an object that provides a <tt>has_role?</tt> method.
+
+Note that duck typing means we don't care what else the <tt>UserFromMars</tt>
+might be doing.  We only care that we can get an id from whatever it is, and we
+can check if a given role string is associated with it. By using
+<tt>acts_as_authorized_user</tt>, we inject what we need into the user object.
+
+If you use an authorization expression "admin of :foo", we check permission by
+asking <tt>foo</tt> if it <tt>accepts_role?('admin', user)</tt>. So for each
+model that is used in an expression, we assume that it provides the
+<tt>accepts_role?(role, user)</tt> method.
+
+Note that <tt>user</tt> can be <tt>nil</tt> if <tt>:allow_guests => true</tt>.
+
+==== #store_location (optional)
+
+This method will be called if authorization fails and the user is about to be
+redirected to the login action. This allows the application to return to the
+desired page after login.  If the application doesn't provide this method, the
+method will not be called.
+
+The name of the method for storing a location can be modified by changing the
+constant STORE_LOCATION_METHOD in environment.rb. Also, the default login and
+permission denied pages are defined by the constants LOGIN_REQUIRED_REDIRECTION
+and PERMISSION_DENIED_REDIRECTION in authorization.rb and can be overriden in
+your environment.rb.
+
+=== Conventions
+
+Roles specified without the "of model" designation:
+
+1. We see if there is a <tt>current_user</tt> method available that will return
+   a user object. This method can be overridden with the <tt>:user</tt> hash.
+
+2. Once a user object is determined, we pass the role to
+   <tt>user.has_role?</tt> and expect a true return value if the user has the
+   given role.
+
+Roles specified with "of model" designation:
+
+1. We attempt to query an object in the options hash that has a matching
+   key. Example: <tt>permit "knight for justice", :justice =>
+   @abstract_idea</tt>
+
+2. If there is no object with a matching key, we see if there's a matching
+   instance variable. Example: @meeting defined before we use <tt>permit
+   "moderator of meeting"</tt>
+
+3. Once the model object is determined, we pass the role and user (determined
+   in the manner above) to <tt>model.accepts_role?</tt>
+
+
+== Upgrading
+
+When upgrading this plugin, please refer to the following file:
+
+http://github.com/DocSavage/rails-authorization-plugin/tree/master/UPGRADE.rdoc
+
+
+== Developers Note : Contributing Patches
+
+Please see the file README_developers.txt for the methods we would like you to use to submit new code features, bugfixes and patches.