Installation

The README states that you can run rails g authorization:install and rails g authorization:rules to install the plugin and generate a default rules file. This functionality is, however, currently broken.

However, what follows is an attempt to state the steps taken to achieve the same result manually.

1. Create the Role model.

rails g model Role title:string description:text

2. Follow the section below based on whether you want users to have a "has and belongs to many" relationship with users, or have users own roles.

Many Users to Many Roles

Create a join table for your user and role models. You should create a new migration, and fill it with something along these lines:

class CreateRolesUsers < ActiveRecord::Migration
  def change
    create_table :roles_users do |t|
      t.integer :role_id, null: false
      t.integer :user_id, null: false
      t.timestamps null: false
    end
  end
end

NOTE: Join tables require the model names to be listed in lexicographic order. Thus, if your "user" model is named something other than "User" and that name is before "Role" lexicographically (like "People"), you will have to name your table <user_model_name>_rules instead of roles_users (e.g. people_roles).

Roles Belong to Individual Users

Create a migration something like the following:

rails g migration AddRolesToUsers role_id:integer

Naturally, if your "user" model is not called "User", change "Users" in the command above to the name of your "user" model.

3. Migrate your database.

rake db:migrate

4. Add the role_symbols method to the User model

# app/models/user.rb

class User < ActiveRecord::Base
  ...

  # This is required for Declarative Authorization to work
   def role_symbols
    (roles || []).map {|r| r.title.to_sym}
  end
  ...

end

5. Add the appropriate relations to your User new Role models

Many Users to Many Roles

# app/models/user.rb

class User < ActiveRecord::Base
  ...
  has_and_belongs_to_many :roles
  ...
end

# app/models/role.rb

class Role < ActiveRecord::Base
  ...
  has_and_belongs_to_many :users
  ...
end

Roles Belong to Individual Users

# app/models/user.rb

class User < ActiveRecord::Base
  ...
  has_many :roles
  ...
end

# app/models/role.rb

class Role < ActiveRecord::Base
  ...
  belongs_to :user
  ...
end

6. Create roles

Many Users to Many Roles

role = Role.new(name: "Admin", description: "Control all the things")
user.roles << role

Roles Belong to Individual Users

user.roles.create(name: "Admin", description: "Control all the things")

7. Create and populate the config/authorization_rules.rb file.

Example config/authorization_rules.rb file:

authorization do
  role :guest do
    # add permissions for guests here, e.g.
    # has_permission_on :conferences, :to => :read
  end

  # permissions on other roles, such as
  # role :admin do
  #   has_permission_on :conferences, :to => :manage
  # end
  # role :user do
  #   has_permission_on :conferences, :to => [:read, :create]
  #   has_permission_on :conferences, :to => [:update, :delete] do
  #     if_attribute :user_id => is {user.id}
  #   end
  # end
  # See the readme or GitHub for more examples
end

privileges do
  # default privilege hierarchies to facilitate RESTful Rails apps
  privilege :manage, :includes => [:create, :read, :update, :delete]
  privilege :create, :includes => :new
  privilege :read, :includes => [:index, :show]
  privilege :update, :includes => :edit
  privilege :delete, :includes => :destroy
end

8. To use "model security", which includes things like the handy with_permissions_to method, you will need to add the following line to each model with which you want "model security."

using_access_control

e.g.

class Employee < ActiveRecord::Base
  using_access_control
  ...
end

9. Celebrate! It's over!