Skip to main content

Roles & Permissions

Admins create roles (CmRole) and enable permissions per model and action from the Roles page. cm-admin turns them into Pundit policies at runtime, optionally limited to a permission scope. Each user gets one role.

Quick example​

rails g cm_admin:install_role
rails g migration AddCmRoleToUser cm_role:references
rails db:migrate
cm_admin do
policy_scopes [{ scope_name: "test_supplier_filter", display_name: "By Test Supplier" }]
end

Setup​

1. Add the role and permission tables​

rails g cm_admin:install_role

Requires the paper_trail gem.

2. Add the role column to users​

rails g migration AddCmRoleToUser cm_role:references

The column name must be cm_role_id, or the policy fails.

3. Add the unique index for bulk permission updates​

rails g cm_admin:add_unique_index_to_permissions

Adds a unique index on (ar_model_name, action_name, cm_role_id) so bulk permission updates can use upsert_all.

4. Assign roles to users​

  1. Add request_params as an attribute in app/models/current.rb.
  2. Set it on every request so cm-admin can identify the action in the Pundit policy:
app/controllers/concerns/authentication.rb
module Authentication
extend ActiveSupport::Concern

included do
before_action :check_current_user
before_action :set_params
end

def set_params
Current.request_params = params if params
end
end
  1. Add belongs_to :cm_role, optional: true to the User model.
  2. Add CmRole to config.included_models in config/initializers/cm_admin.rb.
  3. Set cm_role_id on a user and log in as that user.

Permission scopes​

Every permission gets a Full Access scope by default. Declare extra scopes on the model:

cm_admin do
policy_scopes [{ scope_name: 'test_supplier_filter', display_name: 'By Test Supplier' }]
end

Using permission scopes in code​

cm_permission_scoped_records filters records by the current user's permission scope β€” useful in background jobs, custom controllers and helpers where you need the same scoping as the admin UI. It lives in CmAdmin::PermissionHelper:

module CmAdmin
module CustomHelper
include CmAdmin::PermissionHelper

def select_options_for_users(_ = nil, _ = nil)
cm_permission_scoped_records(::User).map { |user| [user.cm_display_name, user.id] }
end
end
end
cm_permission_scoped_records(model_class)
  • model_class β€” the ActiveRecord model class to scope (User, Order, …)
  • Returns an ActiveRecord::Relation scoped to the user's permissions

It finds the user's permission for the model's index action, calls the permission's scope on the model when it isn't 'all', and falls back to model_class.all. Requires the user to have a cm_role with cm_permissions, and the model to define the scope.

Checking permissions in code​

Always check permissions, never role names. Add these helpers to your User model:

def permission_with_scope?(model_name:, action_name:, scope_name:)
cm_role.cm_permissions.where(ar_model_name: model_name, action_name:, scope_name:).exists?
end

def has_permission?(model_name, action_name)
return false unless cm_role.present?

cm_role.cm_permissions.exists?(ar_model_name: model_name, action_name: action_name)
end

With a scope:

unless Current.user.permission_with_scope?(model_name: 'ReimbursementRequest', action_name: 'revert_acknowledged', scope_name: 'all')
# handle unauthorized
end

Without a scope:

column :note_type, header: 'Note Type', field_type: :enum, display_if: lambda { |_|
::Current.user.has_permission?('Customer', 'customer_restricted_fields')
}

Avoid role checks like Current.user&.role?('admin') or Current.user.cm_role.name == 'admin' β€” they bypass the permission system.

Overriding policies​

Policies are generated for every model by default. Set override_policy to supply your own:

cm_admin do
override_policy true
end
app/policies/cm_admin/user_policy.rb
class CmAdmin::UserPolicy < ApplicationPolicy
def index?
true
end
end

Recipes​

Show a field only with a scoped permission​

tab :details, '' do
row do
cm_show_section 'Details' do
field :status, field_type: :badge, badge_class: Item::STATUS_TAG_COLOR, display_if: ->(record) {
scoped_model = CmAdmin::ItemPolicyArchiveScope.new(Current.user, ::Item).resolve
scoped_model.find_by(id: record.id).present?
}
end
end
end

Set a default redirect path for a role​

Set the root route and add a default_redirect_path column on cm_roles (added automatically in new apps):

config/routes.rb
root 'cm_admin/static#index'
add_column :cm_roles, :default_redirect_path, :string, default: "#{CmAdmin::Engine.mount_path}/users"