Groups and Permissions

a brief description on how to deal with groups and permissions in bitweaver

Created by: xing, Last modification: 14 Apr 2008 (13:39 UTC) by Will

Introduction

Bitweaver's permissioning system is a granular group permissioning system.

The basic way it works is that a group is created, permissions to do specific actions within bitweaver are assigned to the group, then users are assigned the group.

For example:
A group may be created with permissions assigned to allow the members to edit, submit and approve articles. Yet another group may be assigned permissions to edit wiki pages and wiki books. You may then assign users to those groups to participate in your website as article and/or wiki editors depending on your needs.

Custom Content Permissions

R2 ONLY By default permissions naturally are applied globally to all content they have dominion over. However bitweaver's Kernel also supports custom permission assignment on a per content item basis. In other words, for any particular content item you can resign permissions to different groups.

For example:
By default you can assign your wiki pages to be editable by a group, for this example lets say the registered users group. But lets also suppose that you have a few pages you only want site administrators to be able to edit - maybe like a contact page. Using the custom permissions assignment option, you can remove the edit permission from registered users, and reassign it to just the administrators group. Note that you CAN assign custom permissions to any and all groups. For example you could have a wiki page in which you give edit permissions to anonymous users, in addition to registered users.

Public Groups and Self Assignment

R2 ONLY Beginning with version 2, it is possible to allow users to assign themselves to become a member of a public group, thus allowing them to choose to participate in specific roles if you've chosen to setup any of your bitweaver permissions that way. That is to say, if you have assigned some permissions to a group, if that group is public, users can assign themselves to that public group and inherit those permissions.

Configurating and Administrating

Starting With Groups

You can find the group setup page at either 'Administration' -> 'Users' -> 'Groups and Permissions' or my.domain.com/users/admin/edit_group.php. This page lists all available groups, some of their settings and outlines all permissions of each group. To edit a given group, click the 'Edit' icon. To view the group members, click the 'Group Members' icon. Bitweaver installs with several groups already pre-defined.

Once in the edit screen, you can modify group settings and assign / remove individual permissions that apply to the given group. This screencast illustrates how you can add the permission to remove wiki pages to registered users.
{file id=542}

Assigning Users to Groups

Here is a short screencast illustrating how to manually add a new user and how to add that user to the editor group.


Levels

Levels can be used to group certain permissions and thus easily assign a set of permissions to a group. Assigning a permission to a level has no outcome on the users or groups. It's merely a way to organise permissions.

For someone learning how to use bitweaver and work with the permissions for the first time, it's best to ignore the levels altogether.

Custom Permissions

R2 ONLY Most content in bitweaver, such as wiki pages, blog posts, etc, have a custom permissions icon in the upright corner which is by default available to administrators. When clicking this icon you are take to a page with a table listing all permissions for that content, and the various groups of the site. Checkmarks and Pluses indicate who has permission. You can assign and remove custom permissions for the content item by simply clicking the check boxes.

Developing Packages and Permissions Programming

Most of the information below is for R2 ONLY. If you are using R1 see the last section below: Simple Permissions.

Checking User Permissions


<?php
LibertyContent
::hasUserPermission$pPermName$pVerifyAccessControl=TRUE$pCheckGlobalPerm=TRUE )
?>


hasUserPermissions is the most important permissions checking method. You can use this to check any permission against a user. However, for three very common permissions, editing, viewing, and administrating, bitweaver has three convenience functions to make checking these easier. However, they are also very sophisticated, which is why recommend you use them in most cases of edit view and admin checking. See more on these below.


<?php
LibertyContent
::verifyUserPermissions$pPermName$pVerifyAccessControl=TRUE$pCheckGlobalPerm=TRUE )
?>


This function does the exact same thing as hasUserPermissions, however it includes an automatic failure so that you do not have to write any error handling for a failed permissions check. If you want to custom handle a failed permissions check, then you should use the hasUserPermissions method above which returns a boolean.

Parameters

PermName - the permission you want to know if the user has. example: p_blog_post

Verify Access Control - a boolean which toggles whether Liberty should include security services in its permissions check or not. There are packages which layer on even more sophisticated permissions controls such as GatekeeperPackage and ProtectorPackage. The default is to include them, if installed, in the premissions checking process. Generally you will want this to be true.

CheckGlobalPerm - to check the default permission for the group(s) the user is in if other custom permissions checks fail. This is also true by default, naturally, since this basically means check if the group the user has the permission requested. There are some special cases where you might not want the default to be checked - this is for that. Explaining such situations is tricky, you might ask in IRC #bitweaver if you are looking to do some sohpisticated premissions controlling.

Basic Permissions Convenience Functions


<?php
LibertyContent
::hasEditPermission$pVerifyAccessControl=TRUE )
?>



<?php
LibertyContent
::hasViewPermission$pVerifyAccessControl=TRUE )
?>



<?php
LibertyContent
::hasAdminPermission$pVerifyAccessControl=TRUE )
?>


These three methods of LIberty Content are the prefered way of checking for these three basic permissions. Bitweaver's custom permissions sytem is rather sophisiticated, so it is highly recommended you use these functions. __To make use of these functions in your package you must also register your package permissions with these functions".

There are also verify versions of these three methods which will automatically generate a fatal error page for you on invalidation. Again, as above, if you want to custom handle invalidation you should use the "has" methods above.


<?php
LibertyContent
::verifyEditPermission$pVerifyAccessControl=TRUE )
?>



<?php
LibertyContent
::verifyViewPermission$pVerifyAccessControl=TRUE )
?>



<?php
LibertyContent
::verifyAdminPermission$pVerifyAccessControl=TRUE )
?>


Registering Permissions with Liberty

In your package constructor you can register edit, view, and admin permissions with the base LibertyContent class. Here is an example from BlogsPackage, file: BitBlog.php (The whole constructor is shown here, permissions registration is at the bottom):


<?php
function BitBlog$pBlogId=NULL$pContentId=NULL ) {
    
$this->mBlogId = @$this->verifyId$pBlogId ) ? $pBlogId NULL;
    
parent::LibertyContent$pContentId );
    
$this->registerContentTypeBITBLOG_CONTENT_TYPE_GUID, array(
        
'content_description' => 'Blog',
        
'handler_class' => 'BitBlog',
        
'handler_package' => 'blogs',
        
'handler_file' => 'BitBlog.php',
        
'maintainer_url' => 'http://www.bitweaver.org'
    
) );
    
$this->mContentId $pContentId;
    
$this->mContentTypeGuid BITBLOG_CONTENT_TYPE_GUID;

    
// Permission setup
    
$this->mViewContentPerm  'p_blogs_view';
    
$this->mEditContentPerm  'p_blogs_create';
    
$this->mAdminContentPerm 'p_blogs_admin';
}
?>


Simple Permissions


<?php
BitSytem
::hasPermission$pPermission$pMsg NULL )
?>

hasPermission is a lighter weight permission check that only checks against global group permissions. It DOES NOT include checks for custom content permissions! This function is commonly used where we know we don't have any custom permissions assigned, such as when creating new content.


<?php
BitSytem
::verifyPermission$pPermission$pMsg NULL )
?>

Just like hasPermission but also automatically generates a failure page. If you want to custom handle an invalid permission check, you should use hasPermssion or hasUserPermission