Mongoid Ability

Custom Ability class that allows CanCanCan authorization library store permissions in MongoDB via the Mongoid gem.

Installation

Add this line to your application's Gemfile:

gem 'mongoid_ability'

And then execute:

$ bundle

Or install it yourself as:

$ gem install mongoid_ability

Setup

The permissions are defined by a Lock that applies to a Subject and defines access for its owner – User and/or its Role.

Lock

A Lock class can be any class that include MongoidAbility::Lock. There should be only one such class in an application.

class MyLock
    include Mongoid::Document
    include MongoidAbility::Lock

    embedded_in :owner, polymorphic: true
end

This class defines a permission itself using the following fields:

:subject_type, type: String
:subject_id, type: Moped::BSON::ObjectId
:action, type: Symbol, default: :read
:outcome, type: Boolean, default: false

These fields define what subject (respectively subject type, when referring to a class) the lock applies to, which action it is defined for (for example :read), and whether the outcome is positive or negative.

For more specific behavior, it is possible to override the #calculated_outcome method (should, for example, the permission depend on some additional factors). The #calculated_outcome method receives options that are passed when checking the permissions using for example can? :read, MyClass, { option_1: 1 }

def calculated_outcome options={}
    # custom behaviour
    # return true/false
end

If you wish to check the state of a lock directly, please use the convenience methods #open? and #closed?. These take into account the #calculated_outcome. Using the :outcome field directly is discouraged as it just returns the boolean attribute.

The lock class can be further subclassed in order to customise its behavior, for example per action.

Subject

All subjects (classes which permissions you want to control) will include the MongoidAbility::Subject module.

Each action and its default outcome, needs to be defined using the .default_lock macro.

class MySubject
    include Mongoid::Document
    include MongoidAbility::Subject

    default_lock MyLock, :read, true
    default_lock MyLock, :update, false
end

The subject classes can be subclassed. Subclasses inherit the default locks (unless they override them), the resulting outcome being correctly calculated bottom-up the superclass chain.

Owner

This Ability class supports two levels of inheritance (for example User and its Roles). The locks can be either embedded (via .embeds_many) or associated (via .has_many). Make sure to include the as: :owner option.

class MyUser
    include Mongoid::Document
    include MongoidAbility::Owner

    embeds_many :locks, class_name: 'MyLock', as: :owner
    has_and_belongs_to_many :roles, class_name: 'MyRole'

    # override if your relation is named differently
    def self.locks_relation_name
      :locks
    end

    # override if your relation is named differently
    def self.inherit_from_relation_name
      :roles
    end
end

class MyRole
    include Mongoid::Document
    include MongoidAbility::Owner

    embeds_many :locks, class_name: 'MyLock', as: :owner
    has_and_belongs_to_many :users, class_name: 'MyUser'
end

Both users and roles can be further subclassed.

The owner also gains the #can? and #cannot? methods, that are delegate to the user's ability. It is then easy to perform permission checks per user:

current_user.can?(:read, resource, options)
other_user.can?(:read, ResourceClass, options)

CanCanCan

The default :current_ability defined by CanCanCan will be automatically overriden by the Ability class provided by this gem.

Usage

1. Setup subject classes and their default locks.
2. Define permissions using lock objects embedded (or associated to) either in user or role.
3. Use standard CanCanCan helpers (.authorize!, #can?, #cannot?) to authorize the current user.

How it works?

The ability class in this gem looks up and calculates the outcome in the following order:

1. User locks, defined for :subject_id, then :subject_type (then its superclasses), then defined in the subject class itself (via the .default_lock macro) and its superclasses.
2. Role locks have the same look up chain as the user locks. The role permissions are optimistic, meaning that in case a user has multiple roles, and the roles have locks with conflicting outcomes, the ability favors the positive one.

See the test suite for more details.

Contributing

1. Fork it ( https://github.com/tomasc/mongoid_ability/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