NewsFeaturesDownloadsDevelopmentSupportAbout Us

Permissions

From LifeType Wiki

Contents

Introduction

The permissions framework introduced in Lifetype 1.2 allows to have a more precise control over what users can do in blogs and in the site administration area. Each area/functionality defines the permissions required to be executed, and the code will take care that the user currently requesting the action has the required permission before proceeding. If that's not the case, an informative error message will be displayed.

Permissions

Permissions are identified by their unique name, which usually is a string. There are two types of permissions:

  • Blog permission
  • Admin permission

Blog permissions are those permissions that affect blogs, while admin permissions are those linked to global administration functionalities. Blog owners or users with the necessary permissions can grat blog permissions, while only administrators can grant administrator permissions to other users.

In addition to these two types, any permission can be marked as a core permission. A core permission is a permission that cannot be deleted, as it would affect some of the core functionalities. For example removing the "new_post" permission would make it impossible for anyone to add new posts, so it is marked as a core permission to avoid strange situations.

Blog owners do not need any extra permission to access all the areas of a blog. Users marked as global administrators do not need any extra permissions either, the logic that checks permissions is smart enough to grant admin users full access without having the required permissions so please have these in mind when using permissions in your sites.

Managing permissions

New permissions can be added, deleted and updated by accessing the Administration->New Permission and Administration->Permissions areas.

New permissions can be added at any time, although the only reason for adding new permissions would be to use them in custom code. The set of permissions used by the core functionalities of Lifetype is static and cannot be changed (unless you modify core code, of course)

Existing permissions can be updated and renamed, and even core permissions can be renamed. However please be aware of the adverse effects that renaming core permissions will have on the functionalities of your site.

In order to assign a global/admin permission or set of admin permissions to a user, please edit the user settings via Administration->Users->Site Users. Click the name of the user whose permissions you would like to modify and then select the desired permissions from the list.

In order to assign blog permissions or a set of blog permissions to a user, please edit the user settings via Control Centre->Blog Users. Click the name of the user and then select the permissions from the list.

Blog permissions

Blog permissions are granted and removed via Control Centre->Manage Blog Users->Blog Users. Click the link pointing to the user and you will have access to the "Edit Blog User" page that will allow you to amongst other things, control the set of permissions that this user is granted. Each permission is presented in a list by its description, which should be fairly self-describing.

Blog permissions control all aspects relative to a specific blog, and include access to features such as editing, viewing and deleting posts, changing the blog settings, editing the blog users and so on. By default only blog owners are allowed to access this page. However, blog owners can grant permissions and users with permissions add new blog user, view blog users and update user permissions to other users to allow them access this screen. Bear in mind that a user with these permissions could grant himself any sort of access, as he/she is able to access the screen to control the permissions of any user (including his/her own user)

Special blog permisisons

These are a few special permissions that are accessible when configuring user access to a blog:

  • Allow access to this blog that totally blocks a user from even logging into a blog, regardless of the rest of permissions. This permission can be used to temporarily block a user from accessing our blog, rather than removing him completely from the blog.
  • Allow to modify other users' articles and Allow to view other users' articles allow users to see and even update everybody else's posts in the same blog. This can be used to restrict users to work on their own posts only.

Admin permisisons

Administrative permissions (site-wide permissions) are granted via Administration->Site Users->Users and clicking the name of the user whose permissions we would like to update. This screen cannot be used to control permissions relative to a blog, but only to control global permissions. Global permissions include things like access to features under the "Administration" area and a few other things such as being able to log in at all.

Special admin permissions

Most of the permissions are pretty straightforward in the sense that they control a specific functionality of Lifetype. However, there are a few permissions that control other not so obvious things:

  • User is allowed to log in: This is a permission that can only be granted by administrators and that allows a user to log into the administration interface of Lifetype. All new users inherit this permission by default, and it can be used to disallow a user from accessing the admin interface instead of disabling it.
  • User can administrate other blogs (admin mode): This permission allows a user to use the admin mode feature, where a user is allowed to administrate other blogs without the need to be the blog owner.

Plugins and permissions

The following two permissions are the default permissions that can be used by plugins to control access to the features they provide:

  • Manage blog plugins: This permission is used by default by plugins. Unless a plugin specifies its own permissions, this permission will be required to access the blog-only features of a plugin.
  • Manage the admin-only features of plugins: This permission is used by default by plugins. Unless a plugin specifies its own permissions, this permission will be required to access the administrator-only features of a plugin.

Plugins are also allowed to register and use their own group of permisisons, and this will allow greater flexibility to site administrators to control which plugins can be accessed by whom. Otherwise relying on the two permissions above for all plugins means that a person who has the two permissions above is able to access all plugins in the site.

As an example, the 'templateeditor' plugin provides its own set of permissions to control access to editing blog templates (User can edit blog templates (templateeditor plugin)) and global templates (User can edit global templates (templateeditor plugin))

In the case of plugin permissions, users will need to get to assign these permissions to themselves manually before they can be used.


Implementation

The implementation of the permissions framework uses the Permission, Permissions, UserPermission and UserPermissions classes at its foundation.

For action classes, there are a couple of methods that should be called to define which permissions are required in order to perform the requested action.

Access control

Access control in custom Action classes is implemented via the AdminAction::requirePermission($perm) and AdminAction::requireAdminPermission($perm). These two methods will fill an array with permissions that is checked when the controller processes this action, in method AdminAction::canPerform(). Depending on whether we require a blog permission or an admin permission, we should call requirePermission() or requireAdminPermission() respectively.

Either of these two methods should be called in the constructor of our class that extends AdminAction, otherwise the AdminAction::perform() method is already too late:

class MyAdminAction extends AdminAction
{
  function MyAdminAction( $actionInfo, $request )
  {
    $this->AdminAction( $actionInfo, $request );
    ...
    $this->requireAdminPermission( "my_permission" );
  }
  ...
}

In case the user currently executing the action class does not have the required permission, an error screen will be shown and the processing flow will stop.

The Permission and Permissions classes

The Permission class represents a single permission, and contains basic methods for setting the name, description, and attributes (type, core permission or not, etc):

  • Permission::getName()/setName()
  • Permission::getDescription()/setDescription()
  • Permission::isCorePermission/setCorePermission()
  • Permission::isAdminOnlyPermission/setAdminOnlyPermission()

The Permissions class provides the methods for adding, deleting, updating and loading permissions from the database:

  • Permissions::addPermission( &$perm )
  • Permissions::updatePermission( &$perm )
  • Permissions::getPermission( $id )
  • Permissions::getPermissionByName( $name )
  • Permissions::deletePermission( $id )
  • Permissions::getAllPermissions()

Adding new permissions

Plugins and custom code are allowed to dynamically add new permissions if needed, but we have to be careful not to add the same permission twice (the core Permissions class is not checking for duplicate permissions!), therefore we have to check whether the permission already exists or not before adding it:

$perms = new Permissions();
if( !$perms->getPermissionByName( "my_new_permission" )) {
  $perm = new Permission( "my_new_permission", "description" );
  $perm->setCorePermission( false );
  $perm->setAdminOnlyPermission( false );
  $perms->addPermission( $perm );
}

When using this code in a plugin, make sure it is in the PluginBase::register() method as it only needs to be executed when the plugin is loaded for the first time.

Loading existing permissions

The methods Permissions::getPermissionByName($name), Permissions::getPermission($id) and Permissions::getAllPermissions() can be used to retrieve a Permission object given its name, numeric database identifier or just all of them. The one that will be most commonly used is Permissios::getPermissionByName(), specially in those situations where we want to check if a permissionalready exists.

The UserPermission and UserPermissions clases

The UserPermission class establishes a link between a user (represented by a UserInfo object), a permission (represented by a Permission object) and a blog (represented by a BlogInfo object) If the permission is an admin only permission then there will be no BlogInfo object.

The most useful methods from the UserPermission class are:

  • UserPermission::getBlogInfo()
  • UserPermission::getUserInfo()
  • UserPermission::getPermission()

If the permission is admin only, then getBlogInfo() will return null. You could always check if UserPermissions::getBlogId() returns 0 first, as that's the main indicator that this is an admin permission.

The UserPermissions class providers methods for adding, updating, deleting and loading permission relationships from the database such as:

  • UserPermissions::getUserPermissions( $userId, $blogId )
  • UserPermissions::grantPermission( &$perm )
  • UserPermissions::revokePermission( $userId, $blogId, $permissionId )
  • UserPermissions::revokePermissions( $userId, $blogId )
  • UserPermissions::revokeBlogPermissions( $blogId )
  • UserPermissions::revokeUserPermissions( $userId )

Please consult the online API documentation for more information on each one of these methods and their parameters.

Loading user permissions

Although the UserPermissions provides methods for loading user permissions given a user and a blog, it is usually a lot more comfortable if we use the UserInfo::getPermissions($blogId) method. The UserInfo::hasPermissionByName($permName,$blogId=0) and UserInfo::hasPermission($permission,$blogId=0) methods can also be used ot check whether a user has the given permission (by name or by identifier) in the given blog.

Modifying user permissions

The following methods allow to modify the permissions a user has at either the global level or at a blog level:

  • UserPermissions::grantPermission( &$perm ): Grants the given permission (represented by a UserPermission object) to a user
  • UserPermissions::revokePermission( $userId, $blogId, $permissionId ): Given a user identifier, a blog identifier and a permission identifier, remove this permission from the user.
  • UserPermissions::revokePermissions( $userId, $blogId ): Revoke all permissions for the given user in the given blog.
  • UserPermissions::revokeBlogPermissions( $blogId ): Remove all users and permissions from the given blog.
  • UserPermissions::revokeUserPermissions( $userId ): Remove all permissions from all blogs given a user id.