Defining Access Control

This website contains links to software which is either no longer maintained or will be supported only until the end of 2019 (CKFinder 2). For the latest documentation about current CKSource projects, including software like CKEditor 4/CKEditor 5, CKFinder 3, Cloud Services, Letters, Accessibility Checker, please visit the new documentation website.

If you look for an information about very old versions of CKEditor, FCKeditor and CKFinder check also the CKEditor forum, which was closed in 2015. If not, please head to StackOverflow for support.

(Created page with '__TOC__ Access Control Lists (ACL) are ways you to give your users different permissions while working on folders and files. The default settings in the config.ascx file give fu…')
 
(Folder and File Options: Example headings added)
 
(14 intermediate revisions by 2 users not shown)
Line 1: Line 1:
 
__TOC__
 
__TOC__
 
+
{{Ckfinder_2.x_Access_Control_Description|file=<code>config.ascx</code>|AccessControl=AccessControl}}
Access Control Lists (ACL) are ways you to give your users different permissions while working on folders and files. The default settings in the config.ascx file give full permissions to all users. In order to change this configuration you must firstly know the basics of the '''AccessControl''' settings, which can be found in the config.ascx file.&nbsp;
+
<source lang="asp">AccessControl acl = AccessControl.Add();
 
 
This is the syntax for these settings:
 
<pre>AccessControl acl = AccessControl.Add();
 
 
acl.Role = "*";
 
acl.Role = "*";
 
acl.ResourceType = "*";
 
acl.ResourceType = "*";
Line 18: Line 15:
 
acl.FileRename = true;
 
acl.FileRename = true;
 
acl.FileDelete = true;
 
acl.FileDelete = true;
</pre>  
+
</source>  
Basically, a single Access Control setting is defined in an instance of the AccessControl class, created with '''AccessControl.Add()'''.<br>
+
Basically, a single Access Control setting is defined in an instance of the <code>AccessControl</code> class, created with the <code>AccessControl.Add()</code> method.
  
The most important (and required) properties of the "'''AccessControl'''" objects are: '''Role''', '''ResourceType''' and '''Folder.'''<br>
+
The most important (and required) properties of the <code>AccessControl</code> objects are: <code>Role</code>, <code>ResourceType</code> and <code>Folder</code>.
  
== Role<br> ==
+
== Role Property ==
 +
The <code>Role</code> property sets the type of user defined by the ACL. If set to an asterisk (<code>*</code>), it is treated as "all users". You may set this parameter to other names like "Admin" or "Editor". The name of the user type will be directly connected to the function the user is allowed to use. See [[#RoleSessionVar|RoleSessionVar]] for more information.
  
The '''Role''' property sets the type of user defined by the ACL. If set to asterisk (*) it is treated as "all users". You may set this parameter to other names like "Admin" or "Redator". The name of the user type will be directly connected to the function the user are allowed to use. See [[#RoleSessionVar|RoleSessionVar]] for more information.<br>
+
== ResourceType Property  ==
 +
The <code>ResourceType</code> property defines the resource type related to a specific ACL setting. See the [[CKFinder_2.x/Developers_Guide/ASP.NET/Configuration/Resource_Types|Resource Types]] section for more information.
  
== ResourceType ==
+
If this property is set to an asterisk (<code>*</code>), the defined ACL is valid for all resource settings definined in the configuration file.
  
The '''ResourceType''' property defines the resource type related to a specific ACL setting. See Resource Types for more information.<br>
+
== Folder Property  ==
 
+
You can apply ACL settings to specific folders by using the <code>Folder</code> property. Just set it to the folder path. The settings will be recursivelly applied to all folders inside that path.
If this property is set to asterisk (*) the defined ACL is valid for all resource settings definined in the configuration file.<br>
 
 
 
== Folder ==
 
 
 
You can apply ACL settings to specific folders by using the'''Folder''' property. Just set it to the folder path. The settings will be recursivelly applied to all folders inside that path.
 
  
 
== Folder and File Options ==
 
== Folder and File Options ==
 +
All other properties are related to specific features to enable/disable by the ACL setting. Just set them to <code>true</code> or <code>false</code> according to your needs. Setting an option to <code>true</code> enables it, while setting it to <code>false</code> disables it.
  
All other properties are related to the specific features to enabled/disable by the ACL setting. Just set them to '''true''' or '''false''' according to your needs. True of course enables an option, false disables it.
+
== 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.
  
For example, just add the following if you want to restrict the user to upload, rename or delete files in the "/Company/Logos" folder of the resource type "Images":
+
=== Example 1 ===
<pre>acl = AccessControl.Add();
+
Add the following configuration code if you want to restrict the user to upload, rename, or delete files in the <code>/Company/Logos</code> folder of the <code>Images</code> resource type:
 +
<source lang="asp">acl = AccessControl.Add();
 
acl.Role = "*";
 
acl.Role = "*";
 
acl.ResourceType = "Images";
 
acl.ResourceType = "Images";
Line 50: Line 47:
 
acl.FileRename = false;
 
acl.FileRename = false;
 
acl.FileDelete = false;
 
acl.FileDelete = false;
</pre>  
+
</source>
Note that we are reusing the "acl" variable defined previously. You may have as many AccessControl.Add() calls as you want.
+
Note that we are reusing the previously defined <code>acl</code> variable. You may use as many <code>AccessControl.Add()</code> calls as you wish.
  
The above example only refers to file operations in the "/Company/Logos" folder itself and all its child folders. It doesn't restrict operations on the folder so the user can delete or rename the folder.
+
The above example only refers to file operations inside the <code>/Company/Logos</code> folder and all its child folders. It does not restrict operations on the folder so the user can delete or rename the folder.
  
In order to limit users from modifying the folder (not its contents) you should change the permissions in its parent folder. For example:
+
=== Example 2 ===
<pre>acl = AccessControl.Add();
+
In order to restrict users from modifying the folder (not its contents) you should change the permissions in its parent folder. For example:
 +
<source lang="asp">acl = AccessControl.Add();
 
acl.Role = "*";
 
acl.Role = "*";
 
acl.ResourceType = "Images";
 
acl.ResourceType = "Images";
Line 64: Line 62:
 
folderRename = false;
 
folderRename = false;
 
folderDelete = false;
 
folderDelete = false;
</pre>  
+
</source>
Now a user can view and create a folder, but s/he will not be unable to rename or delete it. This is the best way to secure your folders from unauthorized access.
+
Now a user can view and create a folder, but will not be unable to rename or delete it. This is the best way to secure your folders from unauthorized access.
 +
 
 +
== More About Folder Path<br>==
 +
In the first example above the <code>/Company/Logos</code> path was used in the ACL definition. It is rather obvious that this is not an absolute path to a folder on the server.
 +
 
 +
Let us assume that the absolute path on the server to the application folder is <code>/sites/example.com/</code> and the path to the <code>userfiles</code> folder is <code>/sites/example.com/userfiles/</code>.There is also the <code>Images</code> resource type which in this case points to <code>/sites/example.com/userfiles/images/</code>.
 +
 
 +
Knowing the above we will define the correct path for the <code>Logos</code> folder located in <code>/sites/example.com/userfiles/images/Company/Logos</code>.  The key is to define a '''path relative to resource type''' (in this case the resource type is <code>Images</code> pointing to <code>/sites/example.com/userfiles/images/</code>), thus the value that needs to be assigned to the ACL <code>Folder</code> property is <code>/Company/Logos/</code>.
 +
 
 +
If ACL for both <code>Company</code> and <code>Logos</code> folders need to be defined, it is enough to assign just the <code>/Company</code> path.
  
== RoleSessionVar<br> ==
+
Please also note that:
 +
* The folder path has to start from a slash character.
 +
* If you use a wildcard for a resource type (<code>acl.ResourceType = "*";</code>), CKFinder will look through all resource types and apply ACL to every folder that matches the rule, for example <code>Files:/Company/Logos</code>, <code>Flash:/Company/Logos</code>.
  
CKFinder uses the server side session to identify the current user role. In order to enable the Access Control settings for different users, you should initialize a session variable when the user logs on your system.
+
== RoleSessionVar ==
 +
CKFinder uses the server-side session to identify the current user role. In order to enable the Access Control settings for different users, you should initialize a session variable when the user logs into your system.
  
To indicate CKFinder the name of the session variable to use to identify the user role, just use the RoleSessionVar setting. For example:
+
To pass the name of the session variable to identify the user role to CKFinder, use the <code>RoleSessionVar</code> setting. For example:
<pre>RoleSessionVar = "CKFinder_UserRole";
+
<source lang="asp">RoleSessionVar = "CKFinder_UserRole";</source>  
</pre>  
+
In the above example, the <code>CKFinder_UserRole</code> session variable value will be used to match the ACL entries defined previously. See the [[#Role Parameter|Role Parameter]] section above.
In the above example, the "CKFinder_UserRole" session variable value will be used to match the ACL entries defined previously. See [[#Role|Role]], above in this page.
 
  
For example, in the config.ascx file you may the following three different roles:
+
For example, in the <code>config.ascx</code> file you may assign the following three different roles:
  
The '''Admin''' role, which has full permissions:
+
The '''Admin''' role that has full permissions:
<pre>AccessControl acl = AccessControl.Add();
+
<source lang="asp">AccessControl acl = AccessControl.Add();
 
acl.Role = "Admin";
 
acl.Role = "Admin";
 
acl.ResourceType = "*";
 
acl.ResourceType = "*";
Line 93: Line 102:
 
acl.FileRename = true;
 
acl.FileRename = true;
 
acl.FileDelete = true;
 
acl.FileDelete = true;
</pre>  
+
</source>
The '''User''' role, which cannot rename or delete files or folders:
+
The '''User''' role that cannot rename or delete neither files nor folders:
<pre>AccessControl acl = AccessControl.Add();
+
<source lang="asp">AccessControl acl = AccessControl.Add();
 
acl.Role = "User";
 
acl.Role = "User";
 
acl.ResourceType = "*";
 
acl.ResourceType = "*";
Line 109: Line 118:
 
acl.FileRename = false;
 
acl.FileRename = false;
 
acl.FileDelete = false;
 
acl.FileDelete = false;
</pre>  
+
</source>
The '''Guest''' role, which can only view the folders contents:
+
The '''Guest''' role that can only view the folders contents:
<pre>AccessControl acl = AccessControl.Add();
+
<source lang="asp">AccessControl acl = AccessControl.Add();
 
acl.Role = "Guest";
 
acl.Role = "Guest";
 
acl.ResourceType = "*";
 
acl.ResourceType = "*";
Line 125: Line 134:
 
acl.FileRename = false;
 
acl.FileRename = false;
 
acl.FileDelete = false;
 
acl.FileDelete = false;
</pre>  
+
</source>
'''<br>'''
 

Latest revision as of 10:51, 4 March 2013

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.ascx file grant full permissions for all options to every user.

In order to change this configuration option you should learn the basics of the AccessControl settings placed in the configuration file.

Access Control List Syntax

The syntax of the ACL entries is as follows:

AccessControl acl = AccessControl.Add();
acl.Role = "*";
acl.ResourceType = "*";
acl.Folder = "/";

acl.FolderView = true;
acl.FolderCreate = true;
acl.FolderRename = true;
acl.FolderDelete = true;

acl.FileView = true;
acl.FileUpload = true;
acl.FileRename = true;
acl.FileDelete = true;

Basically, a single Access Control setting is defined in an instance of the AccessControl class, created with the AccessControl.Add() method.

The most important (and required) properties of the AccessControl objects are: Role, ResourceType and Folder.

Role Property

The Role property sets the type of user defined by the ACL. If set to an asterisk (*), it is treated as "all users". You may set this parameter to other names like "Admin" or "Editor". The name of the user type will be directly connected to the function the user is allowed to use. See RoleSessionVar for more information.

ResourceType Property

The ResourceType property defines the resource type related to a specific ACL setting. See the Resource Types section for more information.

If this property is set to an asterisk (*), the defined ACL is valid for all resource settings definined in the configuration file.

Folder Property

You can apply ACL settings to specific folders by using the Folder property. Just set it to the folder path. The settings will be recursivelly applied to all folders inside that path.

Folder and File Options

All other properties are related to specific features to enable/disable by the ACL setting. Just set them to true or false according to your needs. Setting an option to true enables it, while setting it to false disables it.

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

Add the following configuration code if you want to restrict the user to upload, rename, or delete files in the /Company/Logos folder of the Images resource type:

acl = AccessControl.Add();
acl.Role = "*";
acl.ResourceType = "Images";
acl.Folder = "/Company/Logos/";

acl.FileUpload = false;
acl.FileRename = false;
acl.FileDelete = false;

Note that we are reusing the previously defined acl variable. You may use as many AccessControl.Add() calls as you wish.

The above example only refers to file operations inside the /Company/Logos folder and all its child folders. It does not restrict operations on the folder so the user can delete or rename the folder.

Example 2

In order to restrict users from modifying the folder (not its contents) you should change the permissions in its parent folder. For example:

acl = AccessControl.Add();
acl.Role = "*";
acl.ResourceType = "Images";
acl.Folder = "/Company/" 

folderCreate = true;
folderRename = false;
folderDelete = false;

Now a user can view and create a folder, but will not be unable to rename or delete it. This is the best way to secure your folders from unauthorized access.

More About Folder Path

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

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

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

If ACL for both Company and Logos folders need to be defined, it is enough to assign just the /Company path.

Please also note that:

  • The folder path has to start from a slash character.
  • If you use a wildcard for a resource type (acl.ResourceType = "*";), CKFinder will look through all resource types and apply ACL to every folder that matches the rule, for example Files:/Company/Logos, Flash:/Company/Logos.

RoleSessionVar

CKFinder uses the server-side session to identify the current user role. In order to enable the Access Control settings for different users, you should initialize a session variable when the user logs into your system.

To pass the name of the session variable to identify the user role to CKFinder, use the RoleSessionVar setting. For example:

RoleSessionVar = "CKFinder_UserRole";

In the above example, the CKFinder_UserRole session variable value will be used to match the ACL entries defined previously. See the Role Parameter section above.

For example, in the config.ascx file you may assign the following three different roles:

The Admin role that has full permissions:

AccessControl acl = AccessControl.Add();
acl.Role = "Admin";
acl.ResourceType = "*";
acl.Folder = "/";

acl.FolderView = true;
acl.FolderCreate = true;
acl.FolderRename = true;
acl.FolderDelete = true;

acl.FileView = true;
acl.FileUpload = true;
acl.FileRename = true;
acl.FileDelete = true;

The User role that cannot rename or delete neither files nor folders:

AccessControl acl = AccessControl.Add();
acl.Role = "User";
acl.ResourceType = "*";
acl.Folder = "/";

acl.FolderView = true;
acl.FolderCreate = true;
acl.FolderRename = false;
acl.FolderDelete = false;

acl.FileView = true;
acl.FileUpload = true;
acl.FileRename = false;
acl.FileDelete = false;

The Guest role that can only view the folders contents:

AccessControl acl = AccessControl.Add();
acl.Role = "Guest";
acl.ResourceType = "*";
acl.Folder = "/";

acl.FolderView = true;
acl.FolderCreate = false;
acl.FolderRename = false;
acl.FolderDelete = false;

acl.FileView = true;
acl.FileUpload = false;
acl.FileRename = false;
acl.FileDelete = false;
This page was last edited on 4 March 2013, at 10:51.