igmarin/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.

Minimal Pundit policy spec

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 (admin, owner, and guest contexts)
• Request specs with role matrix
• Shared examples for reusable patterns