authorization 1.0.11

data/README.txt

@@ -0,0 +1,451 @@
+= Authorization plugin
+
+See the following wiki page for the latest version of this documentation:
+
+http://code.google.com/p/rails-authorization-plugin/w/list
+
+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)
+
+
+== Installation
+
+Installation Instructions
+
+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 in the standard recommended way,
+or as a Git sub-module.
+
+Step 2 (Standard install, recommended)
+
+Run the following command in your Rails.root:
+
+./script/plugin install http://rails-authorization-plugin.googlecode.com/svn/trunk/authorization
+
+This will install the latest version of the plugin from SVN trunk
+into your Rails.root/vendor/plugins/authorization directory.
+
+Step 2 (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 code in the SVN repository here at Google
+Code is a read-only mirror). 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, you will need to update that 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
+
+
+== 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
+has_role?(role, obj = nil) 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
+
+<tt>:allow_guests => false</tt>. We can allow permission processing without a
+current user object. The default is <tt>false</tt>.
+
+<tt>:user</tt> => A <tt>user</tt> object.
+
+<tt>:get_user_method => method</tt> that will return a <tt>user</tt>
+object. Default is <tt>#current_user</tt>, which is the how
+<tt>acts_as_authenticated</tt> works.
+
+<tt>:only => [ :method1, :method2 ]</tt>. Array of methods to apply permit (not
+valid when used in instance methods)
+
+<tt>:except => [ :method1, :method2 ]</tt>. Array of methods that won't have
+permission checking (not valid when used in instance methods)
+
+<tt>:redirect => bool</tt>. default is <tt>true</tt>. If <tt>false</tt>, permit
+will not redirect to denied page.
+
+<tt>:login_required_redirection => path or hash</tt> where user will be
+redirected if not logged in (default is "{ :controller => 'session', :action =>
+'new' }")
+
+<tt>:login_required_message => 'my message'</tt> (default is 'Login is required
+to access the requested page.')
+
+<tt>:permission_denied_redirection => path or hash</tt> where user will be
+redirected if logged in but not authorized (default is '')
+
+<tt>:permission_denied_message => 'my message</tt> (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>
+
+=== More information
+
+Information on this plugin and other development can be found at
+the project home page:
+
+http://code.google.com/p/rails-authorization-plugin/

data/README_developers.txt

@@ -0,0 +1,43 @@
+
+INSTRUCTIONS FOR DEVELOPERS:
+
+Pushing a read-only copy of the git repo master branch to the google code SVN repo.
+--
+
+Based on an article found at :
+http://blog.nanorails.com/articles/2008/1/31/git-to-svn-read-only
+
+Setup:
+
+Clone a local copy of the git repo from GitHub:
+
+'git clone git@github.com:DocSavage/rails-authorization-plugin.git'
+
+cd rails-authorization-plugin
+
+edit .git/config and add the following to the end:
+
+--
+[svn-remote "googlecode"]
+  url = https://rails-authorization-plugin.googlecode.com/svn/trunk
+  fetch = :refs/remotes/googlecode
+--
+
+run : 'git svn fetch'
+
+run : 'git checkout -b local-svn googlecode'
+
+run : 'git svn rebase'
+
+run : 'git merge master'
+
+run : 'git svn dcommit'
+
+
+Now in the future as new changes are commit to master, do this to publish to GoogleCode:
+
+$ git checkout local-svn
+$ git merge master
+$ git svn dcommit
+
+And thats it!