rails-authorization-policies

Rails Authorization Policies

Implement and test authorization patterns in Rails applications.

Files: SKILL.md · EXAMPLES.md · references/workflow.md

HARD-GATE

ALWAYS test authorization with multiple roles (admin, user, guest)
NEVER rely on presence checks alone — check specific permissions
ALWAYS use policy objects, never inline authorization logic in controllers

Quick Reference

Gem	Pattern	Best For
Pundit	Explicit policy classes	Complex per-resource rules
CanCanCan	Centralized Ability class	Simple role-based permissions

Implementation Workflow

1. Add gem — add pundit or cancancan to Gemfile and run bundle install
2. Generate base — run the gem's installer (rails g pundit:install or rails g cancan:ability)
3. Define policies/abilities — create policy classes (Pundit) or populate the Ability class (CanCanCan)
4. Authorize in controllers — call authorize @record (Pundit) or authorize! :action, @record (CanCanCan) in each action
5. Verify authorization — attempt an unauthorized action in the browser or console and confirm it raises Pundit::NotAuthorizedError or CanCan::AccessDenied as expected
6. Scope queries — use policy_scope(Model) or accessible_by(current_ability) for index actions
7. Test all roles — write policy specs and request specs covering admin, owner, and guest

See references/workflow.md for the complete implementation guide with additional detail.

Patterns

Pundit

class PostPolicy < ApplicationPolicy
  def update?
    user.admin? || record.user_id == user.id
  end
end

CanCanCan

class Ability
  include CanCan::Ability

  def initialize(user)
    can :update, Post, user_id: user.id
    can :manage, :all if user.admin?
  end
end

Troubleshooting

Error	Likely Cause	Fix
Pundit::NotDefinedError	No policy class found for the record	Create app/policies/model_policy.rb inheriting from ApplicationPolicy
Pundit::AuthorizationNotPerformedError	authorize not called in a controller action	Add authorize @record in the action, or after_action :verify_authorized to catch misses
CanCan::AccessDenied unexpectedly raised	Ability rules not matching the current user/role	Inspect current_ability.can?(:action, @record) in the console to debug rule evaluation

Testing

Cover every role (admin, owner, guest) in both policy specs and request specs.

Inline Policy Spec Example (Pundit)

RSpec.describe PostPolicy do
  subject { described_class.new(user, post) }

  let(:post) { create(:post, user: owner) }
  let(:owner) { create(:user) }

  context 'as admin' do
    let(:user) { create(:user, :admin) }
    it { is_expected.to permit_action(:update) }
  end

  context 'as owner' do
    let(:user) { owner }
    it { is_expected.to permit_action(:update) }
  end

  context 'as guest' do
    let(:user) { create(:user) }
    it { is_expected.not_to permit_action(:update) }
  end
end

See EXAMPLES.md for complete testing examples including:

• Policy specs with permit_action matchers
• Request specs with role matrix
• Shared examples for reusable patterns