Revision as of 10:06, 31 March 2011

Access Control List (ACL) is a method to grant your users different permissions for working with CKFinder folders and files. The default settings placed in the config.php file grant full permissions for all options to every user.

In order to change this configuration option you should learn the basics of the $config['AccessControl'] settings placed in the configuration file.

Access Control List Syntax

The syntax of the ACL entries is as follows:

$config['AccessControl'][] = Array(
'role' => '*',
'resourceType' => '*',
'folder' => '/',

'folderView' => true,
'folderCreate' => true,
'folderRename' => true,
'folderDelete' => true,

'fileView' => true,
'fileUpload' => true,
'fileRename' => true,
'fileDelete' => true);

Access Control List entries are defined using the following values:

• role – this attribute sets the type of the user. By default it is set to * which can be treated as "everybody". You may set this parameter to other name like user or limited_functions. The name of the user type will be directly related to the functions the user can make use of.

• resourceType – this setting defines the resources handled in CKFinder. A resource type is nothing more than a way to group files under different paths, each having different configuration settings (like Images, Flash, Files). By default it is set to * which means that all resources are available.

• folder – this setting determines where the restrictions will be used. By declaring a folder name you specify the place you want to put your restrictions on. By default it is set to /, so no folder is set.

• folder* and file* options – these variables are of Boolean type and can be set to true or false. The true setting enables an option, false disables it.

• It is possible to define numerous ACL entries. All attributes are optional. Subfolders inherit their default settings from their parents' definitions.

Access Control List Examples

Have a look at the following examples that present various permission configurations in order to learn more about using Access Control Lists in CKFinder.

Example 1

If you want to restrict the upload, renaming, or deletion of files in the Logos folder of the resource type Images, use the following ACL settings.

$config['AccessControl'][] = Array(
'role' => '*',
'resourceType' => 'Images',
'folder' => '/Logos', 

'folderView' => true,
'folderCreate' => true,
'folderRename' => true,
'folderDelete' => true,

'fileView' => true,
'fileUpload' => false,
'fileRename' => false,
'fileDelete' => false);

This example only refers to file operations in the /Logos folder. It does not restrict operations on the folder, so the user can delete or rename it. In order to limit users' ability to modify the folder itself (not its contents), you should change permissions in the parent folder.

Example 2

The following settings restrict folder operations for the Images resource type.

$config['AccessControl'][] = Array(
'role' => '*',
'resourceType' => 'Images',
'folder' => '/', 

'folderView' => true,
'folderCreate' => true,
'folderRename' => false,
'folderDelete' => false

'fileView' => true,
'fileUpload' => true,
'fileRename' => true,
'fileDelete' => true);

Now a user can view and create a folder, but he will be unable to rename or delete it.

Explaining Folder Path for Example 1

In the first example above the /Logos path was used in ACL definition. It is rather obvious that this is not an absolute path to folder on the server.

Let us assume that the absolute path on server to the application folder is /sites/example.com/ and the path to userfiles folder is /sites/example.com/userfiles/.There is also "Images" resource type which in this case points to /sites/example.com/userfiles/images/.

Knowing the above let's define correct path for the Logos folder located in /sites/example.com/userfiles/images/Logos. The key is to define path relative to resource type (In this case resource type is "Images" pointing to /sites/example.com/userfiles/images/), thus the value that needs to be assigned to ACL folder property is /Logos/.

Please also note that:

• Folder path has to start from slash character.

• If you use a wildcard for resource type {{{wildcard_resource}}}, CKFinder will look through all resource types and apply ACL to every folder that matches the rule, for example Files:/Logos, Flash:/Logos.

Sessions

The {{{roleSessionVar}}} is a session variable name that CKFinder must use to retrieve the role of the current user.

$config['RoleSessionVar'] = 'CKFinder_UserRole';

To switch between different user roles, change the session variable:

$_SESSION['CKFinder_UserRole'] = "admin";

For more information about using session variables refer to the Sessions article.

Example 3

In your config.php file you can create three different roles.

First role is assigned to every user (wildcard * is used):

$config['AccessControl'][] = Array(
'role' => '*',
'resourceType' => '*',
'folder' => '/', 

'folderView' => true,
'folderCreate' => false,
'folderRename' => false,
'folderDelete' => false,

'fileView' => true,
'fileUpload' => false,
'fileRename' => false,
'fileDelete' => false);

Second role defines a registered user:

$config['AccessControl'][] = Array(
'role' => 'registered',
'resourceType' => '*',
'folder' => '/', 

'folderView' => true,
'folderCreate' => true,
'folderRename' => false,
'folderDelete' => false,

'fileView' => true,
'fileUpload' => true,
'fileRename' => false,
'fileDelete' => false);

Third role defines the administrator:

$config['AccessControl'][] = Array(
'role' => 'admin',
'resourceType' => '*',
'folder' => '/', 

'folderView' => true,
'folderCreate' => true,
'folderRename' => true,
'folderDelete' => true,

'fileView' => true,
'fileUpload' => true,
'fileRename' => true,
'fileDelete' => true);

With the above settings you have created three different user permission sets. The default user (everybody) is allowed to browse all files and folders. A registered user also has the ability to upload files and create folders. The administrator is granted full permissions.

Now suppose you have an authentication mechanism somewhere in your Web application. In this file you initialize the session with the session_start(); command and assign one of the pre-defined roles to the user in the following way — using the admin role:

$_SESSION['CKFinder_UserRole'] ='admin';

If you want to use the role assigned to registered users, use the following settings:

$_SESSION['CKFinder_UserRole'] ='registered';

A guest does not have any specific permissions granted, so the default values, defined with the * wildcard), are used:

$_SESSION['CKFinder_UserRole'] = 'guest';

The same situation would happen here, where the default values would be used.

$_SESSION['CKFinder_UserRole'] = 'any_other_value';