Authority (CURRENTLY UNMAINTAINED)

Authority is now unmaintained. Users who have installed it decided to trust me, and I'm not comfortable transferring that trust to someone else on their behalf. However, if you'd like to fork it, feel free.

Gary Foster has provided a script to migrate to Pundit.

Overview

Authority helps you authorize actions in your Ruby app. It's ORM-neutral and has very little fancy syntax; just group your models under one or more Authorizer classes and write plain Ruby methods on them.

Authority will work fine with a standalone app or a single sign-on system. You can check roles in a database or permissions in a YAML file. It doesn't care! What it does do is give you an easy way to organize your logic and handle unauthorized actions.

If you're using it with Rails controllers, it requires that you already have some kind of user object in your application, accessible via a method like current_user (configurable).

Contents

• Overview
• The flow of Authority
• Installation
• Defining Your Abilities
• Wiring It Together
  • Users
  • Models
  • Authorizers
    • Passing Options
    • Default methods
    • Testing Authorizers
  • Controllers
  • Views
• The Generic `can?`
• Security Violations & Logging
• Credits
• Contributing

• Roles in your app's database (rolify makes this easy)
• Roles in a separate, single-sign-on app
• Users' points (like StackOverflow)
• Time and date
• Weather, stock prices, vowels in the user's name, or anything else you can check with Ruby

All you have to do is define the methods you need on your authorizers. You have all the flexibility of normal Ruby classes.

You make the rules; Authority enforces them.

     Simplest case                Logical groups                                 Most granular

  ApplicationAuthorizer        ApplicationAuthorizer                         ApplicationAuthorizer
           +                             +                                             +
           |                    +--------+-------+                 +-------------------+-------------------+
           |                    +                +                 +                   +                   +
           |             BasicAuthorizer   AdminAuthorizer  CommentAuthorizer  ArticleAuthorizer  EditionAuthorizer
           |                    +                +                 +                   +                   +
   +-------+-------+            +-+       +------+                 |                   |                   |
   +       +       +              +       +      +                 +                   +                   +
Comment Article Edition        Comment Article Edition          Comment             Article             Edition

               current_user.can_create?(Article)                 # You ask this question, and the user
                           +                                     # automatically asks the model...
                           |
                           v
             Article.creatable_by?(current_user)                 # The model automatically asks
                           +                                     # its authorizer...
                           |
                           v
           AdminAuthorizer.creatable_by?(current_user)           # *You define this method.*
                           +                                     # If you don't, the inherited one
                           |                                     # calls `default`...
                           v
    AdminAuthorizer.default(:creatable, current_user)            # *You define this method.*
                                                                 # If you don't, it will use the one
                                                                 # inherited from ApplicationAuthorizer.
                                                                 # (Its parent, Authority::Authorizer,
                                                                 # defines the method as `return false`.)

(Diagrams made with AsciiFlow)

If you're using Rails, run rails g authority:install. Otherwise, pass a block to Authority.configure with configuration options somewhere when your application boots up.

config.abilities =  {
  :create => 'creatable',
  :read   => 'readable',
  :update => 'updatable',
  :delete => 'deletable'
}

# Whatever class represents a logged-in user in your app
class User
  # Adds `can_create?(resource)`, etc
  include Authority::UserAbilities
...
end

class Article
  # Adds `creatable_by?(user)`, etc
  include Authority::Abilities

  # Without this, 'ArticleAuthorizer' is assumed;
  # if that doesn't exist, 'ApplicationAuthorizer'
  self.authorizer_name = 'AdminAuthorizer'
  ...
end

# app/authorizers/schedule_authorizer.rb
class ScheduleAuthorizer < ApplicationAuthorizer
  # Class method: can this user at least sometimes create a Schedule?
  def self.creatable_by?(user)
    user.manager?
  end

  # Instance method: can this user delete this particular schedule?
  def deletable_by?(user)
    resource.in_future? && user.manager? && resource.department == user.department
  end
end

# undefined; calls `ScheduleAuthorizer.default(:updatable, user)`
ScheduleAuthorizer.updatable_by?(user)

As you can see, you can specify different logic for every method on every model, if necessary. On the other extreme, you could simply supply a default method that covers all your use cases.

# I don't have a comment instance to check, but I need to know
# which post the user wants to comment on
user.can_create?(Comment, :for => @post)

user.can_create?(Comment.new(:post => @post))

# app/authorizers/application_authorizer.rb
class ApplicationAuthorizer < Authority::Authorizer

  # Example call: `default(:creatable, current_user)`
  def self.default(able, user)
    has_role_granting?(user, able) || user.admin?
  end

  protected

  def has_role_granting?(user, able)
    # Does the user have any of the roles which give this permission?
    (roles_which_grant(able) & user.roles).any?
  end

  def roles_which_grant(able)
    # Look up roles for the current authorizer and `able`
    ...
  end
end

# An authorizer shared by several admin-only models
describe AdminAuthorizer do

  before :each do
    @user  = FactoryGirl.build(:user)
    @admin = FactoryGirl.build(:admin)
  end

  describe "class" do
    it "lets admins update" do
      expect(AdminAuthorizer).to be_updatable_by(@admin)
    end

    it "doesn't let users update" do
      expect(AdminAuthorizer).not_to be_updatable_by(@user)
    end
  end

  describe "instances" do

    before :each do
      # A mock model that uses AdminAuthorizer
      @admin_resource_instance = mock_admin_resource
    end

    it "lets admins delete" do
      expect(@admin_resource_instance.authorizer).to be_deletable_by(@admin)
    end

    it "doesn't let users delete" do
      expect(@admin_resource_instance.authorizer).not_to be_deletable_by(@user)
    end

  end

end

If you're using Rails, ActionController support will be loaded in through a Railtie. Otherwise, you'll want to integrate it into your framework yourself. Authority's controller is an excellent starting point.

You can check authorization in your controllers in one of two ways:

• authorize_actions_for Llama protects multiple controller actions with a before_filter, which performs a class-level check. If the current user is never allowed to delete a Llama, they'll never even get to the controller's destroy method.
• authorize_action_for @llama can be called inside a single controller action, and performs an instance-level check. If called inside update, it will check whether the current user is allowed to update this particular @llama instance.

If either method finds a user attempting something they're not authorized to do, a Security Violation will result.

How does authorize_actions_for know to check deletable_by? before the controller's destroy action? It checks your configuration. These mappings are configurable globally from the initializer file. Defaults are as follows:

config.controller_action_map = {
 :index   => 'read',    # `index` controller action will check `readable_by?`
 :show    => 'read',
 :new     => 'create',  # `new` controller action will check `creatable_by?`
 :create  => 'create',  # ...etc
 :edit    => 'update',
 :update  => 'update',
 :destroy => 'delete'
}

They are also configurable per controller, as follows:

class LlamasController < ApplicationController

  # Check class-level authorizations before all actions except :create
  # Also, to authorize this controller's 'neuter' action, ask whether `current_user.can_update?(Llama)`
  authorize_actions_for Llama, :except => :create, :actions => {:neuter => :update},

  # To authorize this controller's 'breed' action, ask whether `current_user.can_create?(Llama)`
  # To authorize its 'vaporize' action, ask whether `current_user.can_delete?(Llama)`
  authority_actions :breed => 'create', :vaporize => 'delete'

  ...

  def edit
    @llama = Llama.find(params[:id])
    authorize_action_for(@llama)        # Check to see if you're allowed to edit this llama. failure == SecurityViolation
  end

  def update
    @llama = Llama.find(params[:id])
    authorize_action_for(@llama)        # Check to see if you're allowed to edit this llama.
    @llama.attributes = params[:llama]  # Don't save the attributes before authorizing
    authorize_action_for(@llama)        # Check again, to see if the changes are allowed.
    if @llama.save?
    # etc
  end

end

You can pass extra arguments to your authorization checks in these controller helpers:

• authorize_actions_for(Llama, args: [{:mamma => true}]
• authorize_action_for(@llama, :sporting => @hat_style)

Generally, though, your authorization will depend on some attribute or association of the model instance, so the authorizer can check @llama.neck_strength and @llama.owner.nationality, etc, without needing any additional information.

Note that you can also call authority_actions as many times as you like, so you can specify one mapping at a time if you prefer:

class LlamasController < ApplicationController
  def breed
    # some code
  end
  authority_actions :breed => 'create'

  def vaporize
    # some code
  end
  authority_actions :vaporize => 'delete'
end

If you have a controller that dynamically determines the class it's working with, you can pass the name of a controller instance method to authorize_actions_for instead of a class, and the class will be looked up when a request is made.

class LlamasController < ApplicationController

  authorize_actions_for :llama_class

  def llama_class
    # This method can simply return a class...
    [StandardLlama, LludicrousLlama].sample

    # ... or an array with a class and some options
    [OptionLladenLlama, {country: 'Peru'}]
  end
end

If you want to authorize all actions the same way, use the special all_actions hash key. For instance, if you have nested resources, you might say "you're allowed to do anything you like with an employee if you're allowed to update their employer".

class EmployeesController < ApplicationController
  authorize_actions_for :parent_resource, all_actions: :update
  private
  def parent_resource
    Employer.find(params[:employer_id])
  end
end

Finally, you can enforce that every controller action runs an authorization check using the class method ensure_authorization_performed, which sets up an after_filter to raise an exception if it wasn't. Any only or except arguments will be passed to after_filter. You can also use if or unless to specify the name of a controller method which determines whether it's necessary.

Since this runs in an after_filter, it obviously doesn't prevent the action, it just alerts you that no authorization was performed. Therefore, it's most useful in development. An example usage might be:

class ApplicationController < ActionController::Base
  ensure_authorization_performed :except => [:index, :search], :if => :auditing_security?, :unless => :devise_controller?

  def auditing_security?
    Rails.env != 'production'
  end
end

If you want a skippable filter, you can roll your own using the instance method, also called ensure_authorization_performed.

link_to 'Edit Widget', edit_widget_path(@widget) if current_user.can_update?(@widget)

If the user isn't allowed to edit widgets, they won't see the link. If they're nosy and try to hit the URL directly, they'll get a Security Violation from the controller.

current_user.can?(:view_stats_dashboard) # calls `ApplicationAuthorizer.authorizes_to_view_stats_dashboard?`
current_user.can?(:view_stats_dashboard, :on => :tuesdays, :with => :tea) # same, passing the options

# application_authorizer.rb
class ApplicationAuthorizer < Authority::Authorizer
  # ...
  def self.authorizes_to_view_stats_dashboard?(user, options = {})
    user.has_role?(:manager) # or whatever
  end
end

Use this very sparingly, and consider it a code smell. Overuse will turn your ApplicationAuthorizer into a junk drawer of methods. Ask yourself, "am I sure I don't have a resource for this? Should I have one?"

If you use Authority to conditionally render links, users will only see links for actions they're authorized to take. If a user deliberately tries to access a restricted resource (for instance, by typing the URL directly), Authority raises and rescues an Authority::SecurityViolation.

When it rescues the exception, Authority calls whatever controller method is specified by your security_violation_handler option, handing it the exception. The default handler is authority_forbidden, which Authority mixes in to your ApplicationController. It does the following:

• Renders public/403.html
• Logs the violation to whatever logger you configured.

You can define your own authority_forbidden method on ApplicationController and/or any other controller. For example:

# Send 'em back where they came from with a slap on the wrist
def authority_forbidden(error)
  Authority.logger.warn(error.message)
  redirect_to request.referrer.presence || root_path, :alert => 'You are not authorized to complete that action.'
end

Your method will be handed the SecurityViolation, which has a message method. In case you want to build your own message, it also exposes user, action and resource.

When a user action is successfully authorized, Authority will call authority_success on your controller. By default, this does nothing, but you can override it to log the event or do something else. For instance:

def authority_success(user, action, resource)
  Authority.logger.info "user #{user} was authorized to #{action} resource #{resource}"
end

• adamhunter for pairing with me on this gem. The only thing faster than his typing is his brain.
• kevmoo, MP211, and scottmartin for pitching in.
• nkallen for writing a lovely blog post on access control when he worked at Pivotal Labs. I cried sweet tears of joy when I read that in 2010. I was like, "Zee access code, she is so BEEUTY-FUL!"
• jnunemaker for later creating Canable, another inspiration for Authority.
• TMA for sponsoring the initial releases of Authority.

Responses, AKA 'Hollaback'

Do you like Authority? Has it cleaned up your code, made you more personable, and taught you the Secret to True Happiness? Awesome! I'd love to get email from you - see my Github profile for the address.

Contributing

How can you contribute? Let me count the ways.

1. Publicity

If you like Authority, tell people! Blog, tweet, comment, or even... [shudder]... talk with people in person. If you feel up to it, I mean. It's OK if you don't.

2. Documentation

Add examples to the wiki to help others solve problems like yours.

3. Issues

Tell me your problems and/or ideas.

4. Code or documentation

1. Have an idea. If you don't have one, check the TODO file or grep the project for 'TODO' comments.
2. Open an issue so we can talk it over.
3. Fork this project
4. Create your feature branch (git checkout -b my-new-feature)
5. bundle install to get all dependencies
6. rspec spec to run all tests.
7. Update/add tests for your changes and code until they pass.
8. Commit your changes (git commit -am 'Added some feature')
9. Push to the branch (git push origin my-new-feature)
10. Create a new Pull Request