Creating Simple:Press Plugins: About Authorizations and Permission Sets

Introduction

This is the fifth in our series of articles on constructing plugins/extensions specifically for Simple:Press. Here are links to the prior articles:

• Hello World!
• Adding Settings
• Adding A Component Menu Item
• Using POST OPTIONS

In this article we will veer away from heavy coding and instead discuss the security model that underlies Simple:Press.

To make the discussion manageable, the article is divided into two sections. The first section provides a general overview of the default permissions and user-groups that are available with a fresh install of Simple:Press. The second section gets into a discussion of custom permissions and the Simple:Press permissions api.

Section 1: Default User Groups and Permission Sets

Background

Simple:Press has an extremely sophisticated, yet easy to work with, user access control system that enables you to create a forum that anyone can visit and post to right through to a completely private forum for invited individuals only. Or – of course – a mix of the two.

This system is controlled through the combination of Usergroups and Permissions.

Understanding these User Access controls before you start populating the forums is recommended as it can save you time and avoid later reorganizations.

Usergroups

One of the main two building blocks needed for access control to your forums is Usergroups.

Simple:Press will create some default Usergroups when it is first installed. For many users these default Usergroups will cover their requirements. For others, who perhaps need a more sophisticated level of access control, then as many Usergroups can be created as needed.

When a new user registers on your site, Simple:Press will place that new user in a Usergroup . Which one they are placed in is set in the Forum -> Usergroup->Map Users to Usergroups panel and can be mapped to a WordPress role. By default, when first installed, new users will be placed in the ‘Members’ Usergroup .

Using the ‘Add Member’ and ‘Move/Delete member’ tools you can manually adjust the memberships of each Usergroup.  You may have as many Usergroups as you wish but there must be at least one. When you create a new forum, your Usergroups are listed in the forum creation form and you will need to assign to each Usergroup a set of Permissions.

One important thing to consider is that you do not have to assign the same set of Permissions to the same Usergroup in all your forums.

Default Usergroups

Guest: This is a ‘virtual’ Usergroup and by default, it has no members. Guests, by their very nature, are not registered. Simple:Press will automatically treat non-registered users as guests and apply whatever permissions are linked to this Usergroup. Note that it IS possible to place genuine members into the Guest Usergroup who will then be granted the same permissions as your Guest visitors.

Members: This is the default Usergroup for registered Members of your website. It is largely in this area that you may wish to extend the number of Usergroups you create if you wish to have different ‘classes’ of members.

Moderators: This is a special Usergroup for your forum Moderators. You can have multiple Moderator Usergroups.

Please note that forum Administrators do NOT belong to a Usergroup and do NOT require permission being assigned to them. By their very nature, forum Admins are granted total and unrestricted access although their activities within the forum admin panels can be restricted

Permission Sets

Please note, within Simple:Press we will use Permissions and Auths (short for authorizations synonymously). 

Usergroups are the first building block of access control to your forums. The second is Permission Sets.

A Permission Set is a large group of access options that you can turn on and off that will grant or deny access to features, tools and actions within your forums.

Some examples of permissions in a permission set are:

• Whether a user can edit or delete their own posts
• Whether a user must have their first or all posts moderated
• Whether they can create signatures for their profile.

These and many others are all controlled by permissions.

It is essential to understand these permissions and how they work, and they should be set and created with care. Along with Usergroups they provide the Simple:Press admins powerful control over how their users interact with your forums.

Simple:Press will create some default Permission Sets when it is first installed. For many users these default sets will cover their requirements.

It is worth mentioning that many questions that come up on our support forum are resolved by resetting a permission. Understanding and awareness of the permissions that can be granted or denied can save a lot of time and frustration later.

Default Permission Sets

During the installation process, Simple:Press creates the following default Permission Sets.

No Access: As the name implies, this set has all available permission turned off.

Read Only: This set provides for read only access to a forum and very limited options.

Limited Access: This set grants users permission to create topics and posts but limits their activity elsewhere.

Standard Access: This set is designed for average members usage and is probably the widest used for registered users on your forums.

Full Access: This set is Standard Access but with a few extras like bypassing spam control.

Moderator Access: Specifically designed for your forum moderators with the permissions they need to perform their tasks.

Please note that forum Administrators do NOT belong to a Usergroup and do NOT require permissions being assigned to them. By their very nature, forum Admins are granted total and unrestricted access.

Like Usergroups, you may define as many Permission Sets as you need but there must always be at least one set. Permission Sets control what a user can and cannot do within the forum – such as view a forum, post to a forum, upload images or use private messaging.

Through Permission Sets you can control what members of a Usergroup can do in any forum to which they are assigned.

Section 2: Custom Permissions

How that you have a basic understanding of Usergroups and Permission Sets, its time to cover how you, as a developer, can customize permissions for your own use.

The Simple:Press API provides convenient methods for creating and managing custom permissions as well as controlling access to functionality through these permissions.  This allows site admins to add or modify access to functionality of the forum.  Typically, you would access this custom permission API from a plugin.

For examples of how to add and control permissions (auths), lets use the Private Messaging (PM) plugin as an example.

A new permission to allow using the PM system is done with the add auth API.  The prototype for this method looks like:

public function add($name, $desc, $active = 1, $ignored = 0, $enabling = 0, $negate = 0, $auth_cat = 1, $warning = '') 

The arguments to this API function set up the permission:

• $name is the name of the new permission.
• $des is a textual description displayed on the permissions page to admins.
• $active is a Boolean as to whether or not the auth should be activated (enabled) when its created (it can be activated separately with its own API call). 
• $ignored says whether the permission is ignored for guests (ie if $ignored is true, guests do not have permission). 
• $enabling is a flag to indicate tha,t in addition to the permission being created, the new functionality required enabling as an option as well (ie could be forum by forum or globally).
• $negate indicates if the permission should be negated when checked for admin access. 
• $auth_cat is the authorization category the new authorization belongs too.  This is simply for grouping on the manage permissions admin panel. 
• $warning is an optional text message displayed on the manage permissions admin panel to give warning about the use of the permission.

Adding Permissions

The PM plugin adds its new permission in this manner:

SP()->auths->add('use_pm', __('Can use the private messaging system', 'sp-pm'), 1, 1, 0, 0, 1);

In this case, the new auth ‘use_pm’ is added and enabled at the same time. 

Typically, you would do this API call once when a plugin is activated or installed.  Once the auth is created and enabled, it will be available on the manage permissions admin panel and can be used in any permission set/Usergroup combination for controlling access.

Deleting Permissions

Like adding a permission, one can also be deleted.  The prototype for deletion API is:

public function delete($id_or_name)

The single argument is the ID of the permission or the name of it.  Once a custom permission is deleted, it is gone forever.  To be used again later, it would have to be added as new permission again. 

An example of deleting the custom permission from the PM plugin:

SP()->auths->delete('use_pm');

Typically, you would only delete the custom permission if the plugin were being uninstalled.  For times if the plugin is deactivated or temporarily not needed, the API provides methods for disabling and enabling the custom permission without deleting it:

public function activate($name) 
public function deactivate($name)

Typical use of these API methods would be when activating or deactivating the plugin, but not installing or uninstalling.  Examples from the PM plugin:

SP()->auths->activate('use_pm');
SP()->auths->deactivate('use_pm');

Using Custom Permissions

Now that the custom permission has been created, it can be used.  The permissions API provides a standard way of checking if a user has the permission to do something.  Typically in your plugin, you would check for permission before allowing a user access to some functionality.  The prototype for checking permission is:

public function get($check, $id = 'global', $user = '')

• $check is the custom permission to check. 
• $id is the forum id to check for permission in.  Note if $id is not given, a global forum id check is used which simply means if the user has access in ANY forum then it will be granted.  This is useful for checking permissions that are sitewide of not forum specific. 
• $user is the user id to check for permission.  If the user id is omitted, the current user will be checked. 

Here is an example from the PM plugin:

if (sp_pm_get_auth('use_pm')) {
  // do something here!
}

In this example, the forum id and the user id are omitted from the API call, so the global permission check is used (not forum specific) since PM access is sitewide and the current user will be checked for permission.  If the API call returns true, the use has permission to ‘use_pm’ so you could allow access to the functionality.

Learning More

You can learn more about permission by taking a look at the Auths class in the API are of Simple:Press. The class can be found in the plugin files: /sp-api/sp-api-class-spcauths.php