Authorization System

Authorization System

At a Glance

These are cursory instructions meant for reference; for more detail, keep reading.

Mandatory Set-up

Set Forem.user_class in config/initializers/forem.rb or any initializer file.

Customizing Permissions

Override the following methods corresponding to each permission inside your user class.

• can_read_forem_category?(category)
• can_read_forem_forums?
• can_read_forem_forum?(forum)
• can_create_forem_topics?(forum)
• can_read_forem_topic?(topic)
• can_reply_to_forem_topic?(topic)
• can_edit_forem_posts?(forum)

About Forem's Authorization System

Forem uses Ryan Bates' popular CanCan gem for defining a solid authorization API for the forum system.

To use Forem, you must have set the Forem.user_class setting in config/initializers/forem.rb (or any initializer file, the name doesn't matter) in your application. Once this is done, the Forem::DefaultPermissions module will be included into this class.

In addition to this, Forem also comes with its own Ability class, which provides the foundations for the permissions system. You may override this in your own application if you see fit, and Forem will automatically know how to define the permissions correctly.

Usage

If you wish to override any of Forem's permission methods to operate in a different manner, simply override the method in the class that Forem.user_class is set to. In this example, we show how you would re-define it to query a permissions association on instances of this class to determine permissions:

def can_read_forem_forums?
  permissions.exists?(:object => forum, :action => :read)
end

If there is no signed-in user, Forem::Ability will initialize one with Forem.user_class.new. So to limit certain actions to signed-in users only, your permission method can check new_record? or persisted?:

def can_create_forem_topics?(forum)
  persisted?
end

Forem::DefaultPermissions

The Forem::DefaultPermissions module defines default permissions for the users of your application, which consist solely of the ability to read forums at the moment (Radar: what do you mean here?). The methods that are defined on your user class are these:

can_read_forem_category?(category)

Default: true

Determines if the user can read the specified category. Will also bar them from reading any forums inside this category if false.

can_read_forem_forums?

Default: true

Determines if the user can read any forums at all. If they cannot, they will not be able to access any forums.

can_read_forem_forum?(forum)

Default: true

Determines if the user can read the specified forum. If they cannot, they are denied access to this forum when they attempt to visit it and it will not appear on any forum listing.

can_create_forem_topics?(forum)

Default: true

Determines if the user can create a topic within this forum. If they cannot, the new topic link will not display at all, nor will they be able to visit /forums/:forum_id/topics/new or submit to /forums/:forum_id/topics.

can_reply_to_forem_topic?(topic)

Default: true

Determines if the user can reply to the given topic.

can_edit_forem_posts?(forum)

Default: true

Allows a user to edit their own posts within the given forum.

Advanced Customization

To restrict all access to Forem (e.g., to make it a members-only feature of a larger application), create a decorator for Forem::ApplicationController that installs a before_filter. For example, in app/decorators/controllers/forem/application_controller_decorator.rb:

Forem::ApplicationController.class_eval do
  before_filter :authenticate_user!
end

This example uses the default authenticate_user! filter provided by Devise; adapt for your own authentication system.