Permissions Basics

Permissions in Concrete CMS

Concrete CMS offers robust permissions management, including authentication, user and group handling, and detailed access control over pages, files, and users. It supports combination groups, group sets, and custom permission access entities for tailored permissions. This guide explores how developers can utilize Concrete's permissions model, ranging from basic tasks like checking user permissions for specific operations on objects to advanced functions like creating custom permissions.

Permission Checks in Concrete CMS

Current Page Permissions

Check permissions against the current page in a theme's template using:

$cp = new Permissions($c);
if ($cp->canEditPageContents()) {
    // User can edit page contents
}

If $c isn't available, get it from the current request:

$c = \Page::getCurrentPage();
if ($cp->canEditPageProperties()) {
    // User can edit page metadata
}

Block Permissions

Within a block template, check block permissions with:

$bp = new Permissions($b);
if ($bp->canViewBlock()) {
    // User can view the block
}

File Permissions

To check if a user can add files globally:

$fs = \Concrete\Core\File\Set\Set::getGlobal();
$fsp = new Permissions($fs);
if ($fsp->canAddFiles()) {
    // User can add files
}

To check if a specific file can be deleted:

$f = \File::getByID(10);
$fp = new Permissions($f);
if ($fp->canDeleteFile()) {
    // User can delete the file
}

The Permissions class, when passed different objects, provides various methods for checking permissions based on the object type. Understanding the background processes of these permissions requests is essential for advanced usage.

Task Permissions in Concrete CMS

Task Permissions in Concrete CMS are global, not tied to specific permission objects. They apply to general tasks like Emptying Trash, Installing Packages, or Performing Backups. Here's how to check them:

$key = \Concrete\Core\Permission\Key\Key::getByHandle('empty_trash');
if ($key->validate()) {
    // User can empty the trash
}

$permissions = new Permissions();
if ($permissions->canEmptyTrash()) {
    // Alternative way to check
}

Although Task Permissions are global, they still use permission keys and categories.

Permissions Check Request Workflow

Understanding how a permissions check operates in Concrete CMS:

1. Initialization with Checker Object:

   • A Permissions check starts with creating a Permissions object, often with a parameter: php $permissions = new Permissions($page); // or $permissions = new Permissions($file);
   • $page and $file are examples of Permission Objects to be checked.

2. Permission Category Identification:

   • The Checker determines the Permission Category for the object, like "Page" for Concrete\Core\Page\Page objects.

3. Obtaining Permission Response:

   • Retrieves the specific Permission Response based on the object's category, such as \Concrete\Core\Permission\Response\PageResponse for Page objects.

4. Method Check in Permission Response:

   • Checks if a method like canEditPageContents exists in the response object. If so, executes it to return true or false.

5. Handling Absent Method with Permission Key:

   • If the method doesn’t exist, translates the method name into a handle for a Permission Key, like edit_page_contents.
   • Fetches the corresponding Permission Key object and runs Concrete\Core\Permission\Key\Key::validate().

6. Assignment and Validation:

   • The validate() method on the Permission Key object gets the current Permission Assignment.
   • From there, it retrieves the Permission Access object.

7. Final Access Check:

   • Determines which access entities are allowed this permission.
   • The validate() method on the Permission Access object assesses if the current user's session entities have this permission.
   • Returns a boolean result, completing the permissions check process.

Permissions Terminology

Checker

• The Permissions Checker is the global "Permissions" object, initiating every Permissions request.

Permission Object

• The subject of a Permissions request, typically a specific Page or File object.

Category

• Groups permissions for similar object types. For instance, view_page, edit_page_contents, and edit_page_properties are in the "Page" category, all working with Concrete\Core\Page\Page.

Key

• Represents a single permission in Concrete CMS, capable of general or custom functionality.

Assignment

• The linkage of a key to a specific permission object and Access object.

Access

• Comprises one or more List Item objects.

Access List Items

• Tracks included or excluded Access Entities, with optional duration for timed permissions.

Access Entities

• Represents users or groups as classes of users in an Access List Item. Examples include Group, User, Group Set, Combination Group, File Uploader, Page Owner, and Workflow Starter.

Permission Duration

• Optional element within an Access List Item, defining the effective timeframe for a permission (e.g., this user is allowed to edit a page only on weekdays from 9:00 AM to 5:00 PM).