RoleCore
RoleCore is a Rails engine which could provide essential industry of Role-based access control.
Demo
The dummy app shows a simple multiple roles with CanCanCan integration including a management UI.
Clone the repository.
$ git clone https://github.com/rails-engine/role_core.git
Change directory
$ cd role_core
Run bundler
$ bundle install
Preparing database
$ bin/rails db:migrate
Start the Rails server
$ bin/rails s
Open your browser, and visit http://localhost:3000
What's does the RoleCore do
The role model
The essence of RBAC is the role, despite your application, there are many possibilities: single-role, multi-roles, extendable-role and the role may associate to different kinds of resources (e.g: users and groups)
RoleCore provides an essential definition of Role, you have to add association to adapt to your application, for example:
- single-role: adding
one-to-many
association between Role and User - multi-roles: adding
many-to-many
association between Role and User - extendable-role: adding a self-association to Role
- polymorphic-asscociated-role: consider using polymorphic association technique
Although it's not out-of-box, but it will give you fully flexibility to suit your needs.
Permissions definition
RoleCore provides a DSL (which inspired by Redmine) that allows you define permissions for your application.
Empowered by virtual model technique,
these permissions your defined can be persisted through serialization,
and can be used with OO-style, for example: role.permissions.project.create?
There also support permission groups, and groups support nesting.
You don't need to any migration when you changing definitions.
I18n is supported too.
In fact, the essence of permissions is Hash, keys are permissions, and values are booleans. so computing of permissions with many roles, can be understood as computing of Hashes.
Management UI
Building a management UI is difficult, but virtual model technique will translates permissions to a virtual model's (a class that conforms to ActiveModel) attributes, and groups will translates to nested virtual models, that means you can use all Rails view helpers including the mighty form builder, and can benefit to Strong Parameter.
The dummy app shows that rendering a permission list only about 20 lines.
If your application is API-only, you can simply dumping the role's permissions to JSON, and can still be benefit to StrongParameter.
Checking permission
RoleCore DOES NOT handle the authentication or authorization directly, you have to integrate with CanCanCan, Pundit or other solutions by yourself.
RoleCore can be working with CanCanCan, Pundit easily and happily.
Installation
Add this line to your Gemfile:
gem "role_core"
if your Rails < 7 or met visit_Psych_Nodes_Alias': Unknown alias: redis (Psych::BadAlias)
, add this line:
gem "psych", "~> 3.3"
Then execute:
$ bundle
Copy migrations
$ bin/rails role_core:install:migrations
Then do migrate
$ bin/rails db:migrate
Run config generator
$ bin/rails g role_core:config
Run model generator
$ bin/rails g role_core:model
Getting start
Define permissions
Permissions are defined in config/initializers/role_core.rb
,
checking it to know how to define permissions.
(If you want to define permissions in runtime, check Dynamic Permissions)
In addition, there also includes a directive about how to integrate with CanCanCan.
I18n
Check config/locales/role_core.en.yml
Hook application
In order to obtain maximum customizability, you need to hooking up role(s) to your user model by yourself.
User who has single role
one-to-many
relationship between Role and User
Create Generate one-to-many
migration, adding role_id
to User
model
$ bin/rails g migration AddRoleToUsers role:references
Then do migrate
$ bin/rails db:migrate
Declare a User belongs to a Role
association
class User < ApplicationRecord
belongs_to :role
# ...
end
Declare a Role has many Users
association
class Role < RoleCore::Role
has_many :users
end
Checking permission
Permissions you've defined will translate to a virtual model (a Class which implemented ActiveModel interface),
permission
would be an attribute, group
would be a nested virtual model (like ActiveRecord's has_one
association).
So you can simply check permission like:
user.role.permissions.read_public?
user.role.permissions.project.read? # `project` is a `group`
For better usage, you may delegate the permissions
from Role
model to User
:
class User < ApplicationRecord
belongs_to :role
delegate :permissions, to: :role
# ...
end
Then you can
user.permissions.read_public?
user.permissions.project.read?
Keep in mind: fetching role
will made a SQL query, you may need eager loading to avoid N+1 problem in some cases.
User who has multiple roles
many-to-many
relationship between Role and User
Create Generate a many-to-many
intervening model
$ bin/rails g model RoleAssignment user:references role:references
Then do migrate
$ bin/rails db:migrate
Declare a User has many Roles through RoleAssignments
association
class User < ApplicationRecord
has_many :role_assignments, dependent: :destroy
has_many :roles, through: :role_assignments
# ...
end
Declare a Role has many Users through RoleAssignments
association
class Role < RoleCore::Role
has_many :role_assignments, dependent: :destroy
has_many :users, through: :role_assignments
end
Check permission
Permissions you've defined will translate to a virtual model (a Class which implemented ActiveModel interface),
permission
would be an attribute, group
would be a nested virtual model (like ActiveRecord's has_one
association).
So you can simply check permission like:
user.roles.any? { |role| role.permissions.read_public? }
user.roles.any? { |role| role.permissions.project.read? } # `project` is a `group`
For better usage, you could declare a can?
helper method:
class User < ApplicationRecord
has_many :role_assignments, dependent: :destroy
has_many :roles, through: :role_assignments
def can?(&block)
roles.map(&:permissions).any?(&block)
end
# ...
end
Then you can
user.can? { |permissions| permissions.read_public? }
user.can? { |permissions| permissions.project.read? }
Keep in mind: fetching roles
will made a SQL query, you may need eager loading to avoid N+1 problem in some cases.
Integrate with Pundit
Just call permissions' method (see checking permission
above) in Pundit's policy.
e.g:
class PostPolicy
attr_reader :user, :post
def initialize(user, post)
@user = user
@post = post
end
def update?
user.permissions.post.update?
end
def update_my_own?
return true if user.permissions.post.update?
return unless user.permissions.post.update_my_own?
post.author == user
end
end
Integrate with CanCanCan
Open config/initializers/role_core.rb
, uncomment CanCanCan integration codes and follows samples to define permissions for CanCanCan
Open your User model:
-
For a user who has single role:
Add a delegate to User model:
delegate :computed_permissions, to: :role
-
For a user who has multiple roles:
Add a
computed_permissions
public method to User model:def computed_permissions roles.map(&:computed_permissions).reduce(RoleCore::ComputedPermissions.new, &:concat) end
Open app/models/ability.rb
, add user.computed_permissions.call(self, user)
to initialize
method.
class Ability
include CanCan::Ability
def initialize(user)
# Apply RoleCole managing permissions
user.computed_permissions.call(self, user)
# You still can add other permissions
can :read_public, :all
end
end
You can check dummy app for better understanding.
Management UI
See RolesController in dummy app and relates view for details.
Hacking
RoleCore is a Rails engine, and following the official best practice, so you can extend RoleCore by the article suggests.
Integrate to existing role model
For some reason, you want to use RoleCore's ability and keeping use your own role model, e.g: integrate with rolify.
You can archive this goal by:
- Modify the migration file which RoleCore generated, changing the role table name
- Add
include RoleCore::Concerns::Models::Role
to your role model
Note: If you want another column name or there's no name in your role model, you need to lookup RoleCore::Concerns::Models::Role
source code, copy and modify to fit your needs
Dynamic permissions
By design, RoleCore is for static permissions, but dynamic permissions is easy to support.
See example in dummy app and relates view for details.
Contributing
Bug report or pull request are welcome.
Make a pull request
- Fork it
- Create your feature branch (
git checkout -b my-new-feature
) - Commit your changes (
git commit -am 'Add some feature'
) - Push to the branch (
git push origin my-new-feature
) - Create new Pull Request
Please write unit test with your code if necessary.
License
The gem is available as open source under the terms of the MIT License.