Skip to content
This repository

Authorization for Rails 4 + admin UI. Semantic, Flexible, Lightweight

branch: master
README.md

TheRole - Authorization Gem for Ruby on Rails with administrative interface.

Gem Version | Build Status | Code Climate | ruby-toolbox

Semantic, Flexible, Lightweight

INTRO

Bye bye CanCan, I got The Role! Description
Bye bye CanCan, I got The Role! TheRole is an authorization library for Ruby on Rails which restricts what resources a given user is allowed to access. All permissions are defined in with 2-level-hash, and stored in the database as a JSON string.

TheRole - Semantic, lightweight role system with an administrative interface.

Role is a two-level hash, consisting of the sections and nested rules.

A Section may be associated with a controller name.

A Rule may be associated with an action name.

A Section can have many rules.

A Rule can be true or false.

Sections and nested Rules provide an ACL (Access Control List)


Using hashes, makes role system extremely easy to configure and use.

GUI

:warning: UI moved in the_role_bootstrap3_ui gem

https://github.com/the-teacher/the_role_bootstrap3_ui

We are waiting for foundation version of UI

TheRole management web interface => localhost:3000/admin/roles
TheRole

puts following yields into your layout:

= yield :role_sidebar
= yield :role_main

Rails 4 version

gem 'the_role', '~> 2.5.2'

gem 'the_role_bootstrap3_ui'

Please read the_role_bootstrap3_ui docs to know more about assets

https://github.com/the-teacher/the_role_bootstrap3_ui

If you have any questions

Please, before asking anything try to launch and play with the Dummy App in the spec folder. Maybe an example integration will be better than any documentation. Thank you!

Instalation

Understanding

API

Install

# You can use any Bootstrap 3 version (CSS, LESS, SCSS)
gem 'bootstrap-sass', github: 'thomas-mcdonald/bootstrap-sass'

gem "the_role", "~> 2.0.0"
bundle

install note

bundle exec rails g the_role --help

Change User migration

Add a role_id:integer field to your User Model

def self.up
  create_table :users do |t|
    t.string :login
    t.string :email
    t.string :crypted_password
    t.string :salt

    # TheRole field
    t.integer :role_id

    t.timestamps
  end
end

Change User model

class User < ActiveRecord::Base
  include TheRole::User
  # or following alias for AR:
  # has_role

  # has_many :pages
end

Create Role model

Generate Role model

bundle exec rails g the_role install

or you can create Role model manually:

class Role < ActiveRecord::Base
  include TheRole::Role
  # or following alias for AR:
  # acts_as_role
end

install TheRole migrations

rake the_role_engine:install:migrations

Invoke migrations

rake db:migrate

Create Admin

Create admin role

bundle exec rails g the_role admin

Makes any user as Admin

User.first.update( role: Role.with_name(:admin) )

Integration

Change your ApplicationController

include TheRoleController in your Application controller

class ApplicationController < ActionController::Base
  include TheRole::Controller

  protect_from_forgery

  def access_denied
    flash[:error] = t('the_role.access_denied')
    redirect_to(:back)
  end
end

Mount routes

config/routes.rb

  concern :the_role, TheRole::AdminRoutes.new

  namespace :admin do
    concerns :the_role
  end

Configuration

create the_role config:

bundle exec rails g the_role config

config/initializers/the_role.rb

TheRole.configure do |config|
  config.layout                = :application
  config.default_user_role     = :user
  config.access_denied_method  = :access_denied      # define it in ApplicationController
  config.login_required_method = :authenticate_user! # devise auth method

  # config.first_user_should_be_admin = false
  # config.destroy_strategy           = :restrict_with_exception # can be nil
end

Usage with any controller

class PagesController < ApplicationController
  before_action :login_required, except: [:index, :show]
  before_action :role_required,  except: [:index, :show]

  before_action :set_page,       only: [:edit, :update, :destroy]
  before_action :owner_required, only: [:edit, :update, :destroy]

  def edit
     # ONLY OWNER CAN EDIT THIS PAGE
  end

  private

  def set_page
    @page = Page.find params[:id]

    # TheRole: You should define OWNER CHECK OBJECT
    # When editable object was found
    # You should define @owner_check_object before invoking **owner_required** method
    @owner_check_object = @page
  end
end

integration with Inhirited Resource

  def owner_required
    @owner_check_object = resource
    super
  end

Understanding

TheRole instead of CanCan?

TheRole, in contrast to CanCan, has a simple and predefined way to find the access state of the current role. If you don't want to create your own role scheme with CanCan Abilities - TheRole can be a great solution for you.

You can manage roles with a simple UI. TheRole's ACL structure is inspired by Rails' controllers, that's why it's so great for Rails applications.

What does semantic mean?

Semantic - the science of meaning. Humans should be able to quickly understand what is happening in a role system.

Look at the next Role hash. If you can understand access rules - this authorization system is semantic.

role = {
  'pages' => {
    'index'   => true,
    'show'    => true,
    'new'     => false,
    'edit'    => false,
    'update'  => false,
    'destroy' => false
  },
  'articles' => {
    'index'  => true,
    'show'   => true
  },
  'twitter'  => {
    'button' => true,
    'follow' => false
  }
}

Virtual sections and rules

Usually, we use real names of controllers and actions for names of sections and rules:

@user.has_role?(:pages, :show)

But, also, you can use virtual names of sections, and virtual names of section's rules.

@user.has_role?(:twitter, :button)
@user.has_role?(:facebook, :like)

And you can use them as well as other access rules.

Usage within Views

<% if @user.has_role?(:twitter, :button) %>
  Twitter Button is Here
<% else %>
  Nothing here :(
<% end %>

Who is Administrator?

Administrator is the user who can access any section and rules of your application.

Administrator is the owner of any objects in your application.

Administrator is the user, who has a virtual section system and a rule administrator in the role-hash.

admin_role_fragment = {
  :system => {
    :administrator => true
  }
}

Who is Moderator?

Moderator is the user, who has access to any actions of some section(s).

Moderator is the owner of any objects of some class.

Moderator is the user, who has a virtual section moderator, with section name as rule name.

An example of a Moderator of Pages (controller) and Twitter (virtual section)

moderator_role_fragment = {
  :moderator => {
    :pages   => true,
    :blogs   => false,
    :twitter => true
  }
}

Who is Owner?

Administrator is owner of any object in system.

Moderator of pages is owner of any page.

User is owner of objects, when Object#user_id == User#id.

API

User

# User's role
@user.role # => Role obj

Is a user Administrator?

@user.admin?                       => true | false

Is a user Moderator?

@user.moderator?(:pages)           => true | false
@user.moderator?(:blogs)           => true | false
@user.moderator?(:articles)        => true | false

Has user got access to rule of section (action of controller)?

@user.has_role?(:pages,    :show)  => true | false
@user.has_role?(:blogs,    :new)   => true | false
@user.has_role?(:articles, :edit)  => true | false

# return true if one of roles is true
@user.any_role?(pages: :show, posts: :show) => true | false

Is user Owner of object?

@user.owner?(@page)                => true | false
@user.owner?(@blog)                => true | false
@user.owner?(@article)             => true | false

Role

# Find a Role by name
@role = Role.with_name(:user)
@role.has?(:pages, :show)       => true | false
@role.moderator?(:pages)        => true | false
@role.admin?                    => true | false

# return true if one of roles is true
@role.any?(pages: :show, posts: :show) => true | false

CREATE

# Create a section of rules
@role.create_section(:pages)
# Create rule in section (false value by default)
@role.create_rule(:pages, :index)

READ

@role.to_hash => Hash

# JSON string
@role.to_json => String

# check method
@role.has_section?(:pages) => true | false

UPDATE

# set this rule on
@role.rule_on(:pages, :index)
# set this rule off
@role.rule_off(:pages, :index)
# Incoming hash is true-mask-hash
# All the rules of the Role will be reset to false
# Only rules from true-mask-hash will be set true
new_role_hash = {
  :pages => {
    :index => true,
    :show => true
  }
}

@role.update_role(new_role_hash)

DELETE

# delete a section
@role.delete_section(:pages)

# delete a rule in section
@role.delete_rule(:pages, :show)

Changelog

  • 2.3.0 - Refactoring
  • 2.1.0 - User#any_role? & Role#any?
  • 2.0.3 - create role fix, cleanup
  • 2.0.2 - code cleanup, readme
  • 2.0.1 - code cleanup
  • 2.0.0 - Rails 4 ready, configurable, tests
  • 1.7.0 - mass assignment for User#role_id, doc, locales, changes in test app
  • 1.6.9 - assets precompile addon
  • 1.6.8 - doc, re dependencies
  • 1.6.7 - Es locale (beta 0.2)
  • 1.6.6 - Ru locale, localization (beta 0.1)
  • 1.6.5 - has_section?, fixes, tests (alpha 0.3)
  • 1.6.4 - En locale (alpha 0.2)
  • 1.6.3 - notifications
  • 1.6.0 - stabile release (alpha 0.1)

i18n

Ru, En (by me)

Es by @igmarin

zh_CN by @doabit & @linjunpop

PL by @egb3

MIT-LICENSE

Copyright (c) 2012-2014 [Ilya N.Zykin]

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

Something went wrong with that request. Please try again.