Browse the Ruby on Rails Community.

You are here: Browse Railsplugins Authorization

Authorization

= Authorization plugin

http://www.writertopia.com/developers/authorization

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)
Steps in using the plugin

1. At the top of your config/environment.rb create an AUTHORIZATION_MIXIN constant and set it to "object roles" or "hardwired". (See init.rb in this plugin for how the role support is mixed in.) 2. Make sure your application provides a current_user method or something that returns the current user object. Add the constants in environment.rb to set your authentication system’s login page (DEFAULT_REDIRECTION_HASH) and method for storing the current URL for return after authentication (STORE_LOCATION_METHOD). (See authorization.rb in the plugin's /lib directory for the default values of DEFAULT_REDIRECTION_HASH and STORE_LOCATION_METHOD.) 3. If you use the "hardwired" mixin, no database use is required. Otherwise, you'll have to generate a role.rb model (and its associated join table with User) by running "script/generate role_model Role" and doing "rake migrate". 4. Add acts_as_authorized_user to your user class. 5. Add acts_as_authorizable to the models you want to query for roles.

Jumpstarting with a mixin

The Authorization plugin comes with two modules that provide different levels of database support. Each of the mixins provide the acts_as_authorized_user and acts_as_authorizable class methods for your models. If you use one of those declarations, you get methods that handle authorization with different database schemes. A full test web application is provided for each of the modules so you can see how they work. The “Object Roles Table” version is recommended for normal use and is the default.

=== 1) Hardwired Roles

This is the simplest and requires no database. Roles are assumed to be coded into the Model classes using the has_role?(role, obj = nil) method.

=== 2) Object Roles Table

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.

=== Migrations and Testing

Each mixin’s test web application comes with migrations to set up the database for the associated mixin. After reading the Rails Recipe on domain specific languages (DSLs) for testing, I added integration tests for each mixin test app that use a simple vocabulary for testing authorization. The object_roles_test application has the most tests. Please contribute tests to improve coverage.

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.