SimonSays!

This gem is a simple, declarative, role-based access control system for
Rails that works great with devise!

Installation

SimonSays can be installed via your Gemfile.

gem 'simon_says'

Usage

SimonSays consists of two parts:

1. A Roleable module mixin which provides a way to define
   roles on User models or on join through models.
2. An Authorizer module mixin which provides a
   declarative API to controllers for finding and authorizing resources.

Roleable

First, we need to define some roles on a model. Roles are stored as an
integer and bitmasking
is used to determine the roles assigned for given record. SimonSays
provides a generator for creating a new migration for this required
attribute:

rails g model User # if and only if this model does not yet exist
rails g active_record:simon_says User
rails db:migrate

Now we can define some roles in our User model. For example:

class User < ActiveRecord::Base
  include SimonSays::Roleable

  has_roles :add, :edit, :delete
end

# > User.new.roles
# => []

# > u = User.create(roles: %i[add edit])
# => #<User ...>
# > u.roles
# => [:add, :edit]
# > u.has_add?
# => true
# > u.has_delete?
# => false
# > u.update roles: %i[delete add edit]
# > u.save # save record with roles_mask of 7

The attribute name can be customized by using the :as option as seen
here in the Admin model:

class Admin < ActiveRecord::Base
  include SimonSays::Roleable

  has_roles :design, :support, :moderator, as: :access
end

# > Admin.new.access
# => []

# > Admin.new(access: :support).access
# => [:support]

Make sure to generate a migration using the correct attribute name if
:as is used. For example:

rails g active_record:simon_says Admin access

We can also use has_roles to define roles on a join through model
which is used to associate a User with a resource.

class Permission < ActiveRecord::Base
  include SimonSays::Roleable

  belongs_to :user
  belongs_to :document

  has_roles :download, :edit, :delete,
end

# > Permission.new(roles: Permission::ROLES).roles
# => [:download, :edit, :delete]

Roleable also creates two scopes that can be used to find records that
have a given set roles. Using the default attribute name, the two scopes
generated would be with_roles and with_all_roles. Both methods
accept one or more role symbols as its arguments. The first scope,
with_roles, will find any record with one or more the supplied roles.
The second scope, with_all_roles will only find record that have all
of the supplied roles.

It is useful to note the various dynamically generated methods as well
the ROLES constant, which is used in the Permission example. Take a
look at the Roleable
source code
to see how methods and scopes are dynamically generated with
has_roles.

Authorizer

The Authorizer concern provides several methods that can be used within
your controllers in a declarative manner.

Please note, certain assumptions are made with Authorizer. Building
upon the above User and Admin model examples, Authorizer would assume
there is a current_user and current_admin method. If these models
correspond to devise scopes this would be the case by default.
Additionally there would need to be an authenticate_user! and
authenticate_admin! methods, which devise provides as well.

Eventually, we would like to see better customization around the
authentication aspects. This library is intended to solve the problem of
authorization and access control. It is not an authentication library.

In general, the Authorizer concern provides four core declarative methods
to be used in controllers. All of these methods accept the :only and
:except options which end up being used in a before_action callback.

• authenticate(scope, opts): Declarative convenience method to setup authenticate before_action`
• find_resource(resource, opts): Declarative method to find a resource
  and assign it to an instance variable
• authorize_resource(resource, *roles): Authorize resource for given
  roles
• find_and_authorize(resource, *roles): Find a resource and then try
  authorize it for the given roles. If successful, the resource is
  assigned to an instance variable

When find resources, the default_authorization_scope is used. It can
be customized on a per-controller basis. For example:

class ApplicationController < ActionController::Base
  include SimonSays::Authorizer

  self.default_authorization_scope = :current_user
end

To authorize resources against a given role, we use either authorize
or find_and_authorize. For example, consider this
DocumentsController which uses an authenticated User resource and a
Permission through model:

class DocumentsController < ApplicationController
  authenticate :user

  find_and_authorize :document, :edit, through: :permissions, only: [:edit, :update]
  find_and_authorize :document, :delete, through: :permissions, only: :destroy
end

This controller will find a Document resource and assign it to the
@document instance variable. For the :edit and :update actions,
it’ll require a permission with an :edit role. For the :destroy
method, a permission with the :delete role is required. Since the
:through option is used, a @permission instance variable will also
be created.

The find_resource method may raise an ActiveRecord::RecordNotFound
exception. The authorize method may raise a
SimonSays::Authorizer::Denied exception if there is insufficient role
access. As a result, the find_and_authorize method may raise either
exception.

We can also use a different authorization scope with the :from
option for find_resource and find_and_authorize. For example:

class ReportsController < ApplicationController
  authorize_resource :admin, :support

  find_resource :report, from: :current_admin, except: [:index, :new, :create]
end

Please refer to the
docs
for more information on the various declarative methods provided by the
Authorizer.

Contributing

1. Fork it ( https://github.com/SimplyBuilt/SimonSays/fork )
2. Create your feature branch (git checkout -b my-new-feature)
3. Commit your changes (git commit -am 'Add some feature')
4. Push to the branch (git push origin my-new-feature)
5. Create a new Pull Request