CanCanCan Cheatsheet

A breakdown of how to define and check abilities with CanCanCan, with an opinionated set of best practices based on experience.

Defining abilities

General Best practices

No access by default

Give abilities as you discover you need them

• Don’t define them upfront because you think you’ll need them
• Always use can? to enable a feature - never use cannot? to take it away

Only use the standard index, show, create, update, destroy (edit is subset of updated and new is a subset of create)

Your ability file is not somewhere to be DRY; being explicit and clear

Don’t use manage (its too permissive)

Don’t define aliases - always be explicit and granular:

1
2
3
4
5
6

# Bad
alias_action :create, :read, :update, :destroy, to: :crud
can :crud, User

# Good
can [:create, :read, :update, :destroy], User

Define permissions for one resource at a time.

1
2
3
4
5
6

# Bad: Update or destroy both articles and comments
can [:update, :destroy], [Article, Comment]

# Good
can [:update, :destroy], Article
can [:update, :destroy], Comment

Syntax

Hash Conditions

Preferred syntax (used most consistently without hidden side-effects between all 3 methods) * can? & authorize!: Keys match methods on instance, which must return values equal to the hash’s values * accessible_by: Generates a LEFT JOIN to query conditions on associated records (so almost anything you can pass to a hash of conditions in Active Record will work)

1

can :read, Project, active: true, user_id: user.id

Can’t pass model instances into the hash - you must use their id instead:

1
2
3
4
5

# Won’t work
can :manage, Project, group: user.groups

# Will work
can :manage, Project, group: { id: user.group_ids }

Must use lower-level attributes rather than your existing scopes that wrap them:

1

can :read, Article, is_published: true

Can use a range:

1

can :read, Project, priority: 1..3

Defining conditions on associations: * Will issue a query that performs an LEFT JOIN to query conditions on associated records

1
2

can :read, Project, category: { visible: true }
can :manage, Part, service: { account: { user: { id: user.id } } }

Blocks

Use only if you need to pass additional context or can’t express the logic using hashes:

1
2
3
4
5

can :create, Project do |project, remote_ip|
  # ...
end

can? :create, Project, request.remote_ip

Only evaluated when an actual instance object is present

1
2
3

can :update, Project do |project|
  project.priority < 3
end

Scopes & Raw SQL

If you need an operator other than the equality one, or for other complex cases, you can provide a scope or a Raw SQL segment.

You must always also define a block, or you get an error:

1
2
3
4
5
6

can :read, Article, Article.published_recently

# Raises exception:
# The can? and cannot? call cannot be used with a raw sql 'can' definition.
# The checking code cannot be determined for :read #<Article ..>.
can? :read, Article

When you also define a block:

• Block is used when can? and authorize! are passed an instance
• Scope or Raw SQL segment is use when accessible_by is called
• Neither are used when when can? and authorize! are passed a class (only matches on action and class type)

1
2
3
4
5
6

can :read, Article, Article.published_recently do |article|
  article.created_at > DateTime.now - 3.days
end

# Works fine
can? :read, Article

Using a SQL segment:

1
2
3

can :update, Project, ["priority < ?", 3] do |project|
  project.priority < 3
end

Operators

Defining custom logic

Useful when permissions are defined outside of Ruby such as when defining Abilities in Database * Block will be triggered for every can? check, even when only a class is used in the check.

1
2
3

can do |action, subject_class, subject|
  # ...
end

Merging ability files

1
2
3
4

# ApplicationController.rb
def current_ability
  @current_ability ||= ReadAbility.new(current_user).merge(WriteAbility.new(current_user))
end

Checking abilities

General best practices

Never use load_and_authorize_resource or load_resource, instead use the more explicit authorize! call for readability and flexibiltiy

Use check_authorization to ensure all controller actions are authorized: * Adds an after_filter to ensure authorize! is called for every controller action

1
2
3
4
5
6
7
8
9
10
11
12
13

class ApplicationController < ActionController::Base
  check_authorization

  skip_authorization_check :only => [:new, :create]

  check_authorization unless: :admin_subdomain? # Only skips checking authorization - still does the authorization

  private

  def admin_subdomain?
    request.subdomain == "admin"
  end
end

CanCanCan methods

There are 3 methods for checking a user’s abilities:

Abilities are matched on up to 3 different attributes:

• An action type
• A target or subject class
• A set of conditions (optional, if defined)

Usage examples

Handling failures

For unauthorized requests, return 404 rather than 302 to avoid leaking information. However if you do want to render unauthorized:

Custom message to include in the exception thrown:

1

authorize! :read, Article, :message => "Unable to read this article."

Raising exception manually:

1

raise CanCan::AccessDenied.new("Not authorized!", :read, Article)

Rescuing:

1
2
3
4
5
6
7
8
9
10
11

class ApplicationController < ActionController::Base
  rescue_from CanCan::AccessDenied do |exception|
    respond_to do |format|
      format.json { head :forbidden }
      format.html { redirect_to main_app.root_url, :alert => exception.message }
    end
  end
end

exception.action # => :read
exception.subject # => Article

Troubleshooting

Logging details of AccessDenied exceptions

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

# in ApplicationController
rescue_from CanCan::AccessDenied do |exception|
  if Rails.env.development?
    matching_rules = current_ability.send(:relevant_rules_for_match, exception.action, exception.subject)

    if matching_rules.any?
      describe_rules = matching_rules.map {|rule| { conditions: rule.conditions, block: rule.instance_variable_get(:@block) } }

      Rails.logger.debug "CanCanCan::AccessDenied: User has ability to #{exception.action} " \
                         "#{exception.subject.inspect}, but failed to satisfy conditions: " \
                         "#{describe_rules.to_sentence(two_words_connector: ' or ', last_word_connector: ' or ')}"
    else
      Rails.logger.debug "CanCanCan::AccessDenied: User does not have ability to #{exception.action} " \
                         "#{exception.subject.inspect}"
    end
  end
end

Order code is executed

• Request is made and assigned to a controller
• Controller instance calls current_ability method
• current_ability instantiates an instance of CanCan::Ability class (so your ability.rb file’s initialize method is called)

Case: For authorize! or can?

• Controller makes first call to authorize! or can? (which calls can? on your current_ability instance)
• Matching rules are found based on the subject’s class and action
• If the subject is a class, this is where the logic stops (and we only check for a matching action)
• If the subject is an instance
  • If a block is defined, its evaluated, and logic ends
  • If a hash is defined, its values are matched against the subject’s attributes

Case: For accessible_by

• Controller calls model_adaptor on your current_ability and other methods to find matching rules based on the subject’s class and action
• Returns a ActiveRecord::Relation for the subject model class with the raw SQL or scope if one has bee defined, otherwise a LEFT JOIN with the attributes from the hash

Common exceptions

1

undefined method `klass' for nil:NilClass

Occurs when you’ve defined an association name incorrectly in a condition hash.