Consul - A scope-based authorization solution
Consul is a authorization solution for Ruby on Rails that uses scopes to control what a user can see or edit.
We have used Consul in combination with assignable_values to solve a variety of authorization requirements ranging from boring to bizarre.
Describing a power for your application
You describe access to your application by putting a Power
model into app/models/power.rb
:
class Power
include Consul::Power
def initialize(user)
@user = user
end
power :notes do
Note.(@user)
end
power :users do
User if @user.admin?
end
power :dashboard do
true # not a scope, but a boolean power. This is useful to control access to stuff that doesn't live in the database.
end
end
There are no restrictions on the name or constructor arguments of your power class.
Querying a power
Common things you might want from a power:
- Get its scope
- Ask whether it is there
- Raise an error unless it its there
- Ask whether a given record is included in its scope
- Raise an error unless a given record is included in its scope
Here is how to do all of that:
power = Power.new(user)
power.notes # => returns an ActiveRecord::Scope
power.notes? # => returns true if Power#notes returns a scope
power.notes! # => raises Consul::Powerless unless Power#notes returns a scope
power.note?(Note.last) # => returns whether the given Note is in the Power#notes scope. Caches the result for subsequent queries.
power.note!(Note.last) # => raises Consul::Powerless unless the given Note is in the Power#notes scope
You can also write power checks like this:
power.include?(:notes)
power.include!(:notes)
power.include?(:note, Note.last)
power.include!(:note, Note.last)
Boolean powers
Boolean powers are useful to control access to stuff that doesn't live in the database:
class Power
...
power :dashboard do
true
end
end
You can query it like the other powers:
power.dashboard? # => true
power.dashboard! # => raises Consul::Powerless unless Power#dashboard? returns true
Role-based permissions
Consul has no built-in support for role-based permissions, but you can easily implement it yourself. Let's say your User
model has a string column role
which can be "author"
or "admin"
:
class Power
include Consul::Power
def initialize(user)
@user = user
end
power :notes do
case role
when :admin then Note
when :author then Note.
end
end
private
def role
@user.role.to_sym
end
end
Controller integration
It is convenient to expose the power for the current request to the rest of the application. Consul will help you with that if you tell it how to instantiate a power for the current request:
class ApplicationController < ActionController::Base
include Consul::Controller
current_power do
Power.new(current_user)
end
end
You now have a helper method current_power
for your controller and views. Everywhere else, you can access it from Power.current
. The power will be instantiated when the request is handed over from routing to ApplicationController
, and will be nilified once the request was processed.
You can now use power scopes to control access:
class NotesController < ApplicationController
def show
@note = current_power.notes.find(params[:id])
end
end
To make sure a power is given before every action in a controller:
class NotesController < ApplicationController
power :notes
end
You can use :except
and :only
options like in before filters.
You can also map different powers to different actions:
class NotesController < ApplicationController
power :notes, :map => { [:edit, :update, :destroy] => :changable_notes }
end
It is often convenient to map a power scope to a private controller method:
class NotesController < ApplicationController
power :notes, :as => end_of_association_chain
def show
@note = end_of_association_chain.find(params[:id])
end
end
This is especially useful when you are using a RESTful controller library like resource_controller. The mapped method is aware of the :map
option.
You can force yourself to use a power
check in every controller. This will raise Consul::UncheckedPower
if you ever forget it:
class ApplicationController < ActionController::Base
include Consul::Controller
require_power_check
end
Should you for some obscure reason want to forego the power check:
class ApiController < ApplicationController
skip_power_check
end
Validating assignable values
Sometimes a scope is not enough to express what a user can edit. You will often want to give a user write access to a record, but restrict the values she can assign to a given field.
Consul leverages the assignable_values gem to add an optional authorization layer to your models. This layer adds additional validations in the context of a request, but skips those validations in other contexts (console, background jobs, etc.).
You can enable the authorization layer by using the macro authorize_values_for
:
class Story < ActiveRecord::Base
authorize_values_for :state
endy
The macro defines an accessor power
on instances of Story
. If that field is set to a power, the values of state
will be validated against a whitelist of values provided by that power. If that field is nil
, the validation is skipped.
Here is a power implementation that can provide a list of assignable values for the example above:
class Power
...
def assignable_story_states(story)
if admin?
['delivered', 'accepted', 'rejected']
else
['delivered']
end
end
end
Here you can see how to activate the authorization layer and use the new validations:
story = Story.new
Power.current = Power.new(:role => :guest) # activate the authorization layer
story.assignable_states # ['delivered'] # apparently we're not admins
story.state = 'accepted' # a disallowed value
story.valid? # => false
story.state = 'delivered' # an allowed value
story.valid? # => true
You can not only authorize scalar attributes like strings or integers that way, you can also authorize belongs_to
associations:
class Story < ActiveRecord::Base
belongs_to :project
:project
end
class Power
...
def assignable_story_projects(story)
user.account.projects
end
end
The authorize_values_for
macro comes with many useful options and details best explained in the assignable_values README, so head over there for more. The macro is basically a shortcut for this:
assignable_values_for :field, :through => lambda { Power.current }
Installation
Add the following to your Gemfile
:
gem 'consul'
Now run bundle install
to lock the gem into your project.
Development
A Rails 2 test application lives in spec/app_root
. You can run specs from the project root by saying:
bundle exec rake spec
If you would like to contribute:
- Fork the repository.
- Push your changes with specs.
- Send me a pull request.
I'm very eager to keep this gem leightweight and on topic. If you're unsure whether a change would make it into the gem, talk to me beforehand.
Credits
Henning Koch from makandra