Using Authority, you have:

• Broad, class-level rules. Examples:
  • “Basic users cannot delete any Widget.”
  • “Only admin users can create Offices.”
• Fine-grained, instance-level rules. Examples:
  • “Management users can only edit schedules with date ranges in the future.”
  • “Users can’t create playlists more than 20 songs long unless they’ve paid.”
• A clear syntax for permissions-based views. Examples:
  • link_to 'Edit Widget', edit_widget_path(@widget) if current_user.can_update?(@widget)
  • link_to 'Keelhaul Scallywag', keelhaul_scallywag_path(@scallywag) if current_user.can_keelhaul?(@scallywag)
• Graceful handling of access violations: by default, it displays a “you can’t do that” screen and logs the violation.
• Minimal effort and mess.

Most importantly, you have total flexibility: Authority does not constrain you into using a particular scheme of roles and/or permissions.

Authority lets you control access based on:

Authority encapsulates all authorization logic in Authorizer classes. Want to do something with a model? Ask its authorizer.

You can specify a model’s authorizer one of two ways:

• specify the class itself: authorizer = SomeAuthorizer
• specify the class’s name: authorizer_name = 'SomeAuthorizer' (useful if the constant isn’t yet loaded)

If you don’t specify an authorizer, the model will:

• Look for an authorizer with its name. Eg, Comment will look for CommentAuthorizer.
• If that’s not found, it will use ApplicationAuthorizer.

Models that have the same authorization rules should use the same authorizer. In other words, if you would write the exact same methods on two models to determine who can create them, who can edit them, etc, then they should use the same authorizer.

Some example groupings:

     Simplest case                Logical groups                                 Most granular

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

The authorization process generally flows like this:

               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`.)

If the answer is false and the original caller was a controller, this is treated as a SecurityViolation. If it was a view, maybe you just don’t show a link.

The authorization process for instances is different in that it calls the instance’s default method before calling the class default method. This allows you to define default behaviour that requires access to the model instance to be determined (eg, assume any action on a blog post is allowed if that post is marked ‘wiki’).

Starting from a clean commit status, add authority to your Gemfile, then bundle.

Edit config/initializers/authority.rb. That file documents all your options, but one of particular interest is config.abilities, which defines the verbs and corresponding adjectives in your app. The defaults are:

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

This option determines what methods are added to your users, models and authorizers. If you need to ask user.can_deactivate?(Satellite) and @satellite.deactivatable_by?(user), add :deactivate => 'deactivatable' to the hash.

# 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

Add your authorizers under app/authorizers, subclassing the generated ApplicationAuthorizer.

These are where your actual authorization logic goes. Here’s how it works:

• Instance methods answer questions about model instances, like “can this user update this particular widget?” (Within an instance method, you can get the model instance with resource).
  • Any instance method you don’t define (for example, if you didn’t make a def deletable_by?(user)) will fall back to the corresponding class method. In other words, if you haven’t said whether a user can update this particular widget, we’ll decide by checking whether they can update any widget.
• Class methods answer questions about model classes, like “is it ever permissible for this user to update a Widget?”
  • Any class method you don’t define (for example, if you didn’t make a def self.updatable_by?(user)) will call that authorizer’s default method.

For example:

# 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)

Any options you pass when checking permissions will be passed right up the chain. One use case for this would be if you needed an associated instance in order to do a class-level check. For example:

# 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)

This would ultimately call creatable_by? on the designated authorizer with two arguments: the user and {:for => @post}. If you’ve defined that method yourself, you’d need to ensure that it accepts the options hash before doing this, or you’d get a “wrong number of arguments” error.

There’s nothing special about the hash key :for; I just think it reads well in this case. You can pass any options that make sense in your case.

If you don’t pass options, none will be passed to your authorizer, either.

And you could always handle the case above without options if you don’t mind creating an extra model instance:

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

Any class method you don’t define on an authorizer will call the default method on that authorizer. This method is defined on Authority::Authorizer to simply return false. This is a ‘whitelisting’ approach; any permission you haven’t specified (which falls back to the default method) is considered forbidden.

You can override this method in your ApplicationAuthorizer and/or per authorizer. For example, you might want one that looks up the user’s roles and correlates them with permissions:

# 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

If your system is uniform enough, this method alone might handle all the logic you need.

One nice thing about putting your authorization logic in authorizers is the ease of testing. Here’s a brief example.

# 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

Assuming your user object is available in your views, you can do all kinds of conditional rendering. For example:

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

Authority is organized around protecting resources. But occasionally you may need to authorize something that has no particular resource. For that, it provides the generic can? method. It works like this:

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

If you’re using Authority’s ActiveController integration or have used it as a template for your own, your application will handle unauthorized requests with 403 Forbidden automatically.

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