implement-authorization

Implement Authorization

Quick Reference

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

Core Process

Implementation Workflow

1. Inspect existing authorization — reuse the installed policy framework; add pundit or cancancan only if the task requires a new framework and project conventions permit it
2. Generate base only when needed — run the gem's installer (rails g pundit:install or rails g cancan:ability) only when no supported framework is present and the project permits the generator; otherwise proceed with the detected framework without invoking generators
3. Define policies/abilities — create policy classes (Pundit) or populate the Ability class (CanCanCan); always use policy objects, never inline authorization logic in controllers
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; use persisted records (e.g., User.create!) not unsaved ones
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; check specific permissions, never presence checks alone

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

Output Style

When implementing or reviewing authorization, the output answer.md must include:

1. Manual Denied-Action Verification — a dedicated section with actual Rails console output, or an explicit unrun status showing the authorization exception raised when an unauthorized action is attempted. Always use persisted records (User.create!, Post.create!), never unsaved ones.
2. HTTP and Policy Verification — concrete curl requests or controller test commands with expected HTTP response codes (e.g. 403 Forbidden or 302 Found) when access is denied.
3. Language — English unless explicitly requested otherwise.

See references/output-style.md for full formatting examples including Pundit and CanCanCan console output templates.

Integration

Skill	When to chain
write-tests	When implementing authorization tests.

Extended Resources (Progressive Disclosure)

Load these files only when their specific content is needed:

• EXAMPLES.md — Use when you need complete Pundit or CanCanCan implementation examples beyond the inline samples
• references/workflow.md — Use when you need the step-by-step authorization implementation workflow diagram
• references/output-style.md — Use when you need full formatting templates for console verification output