J.swiderski (talk | contribs) |
(→Folder and File Options: Example headings added) |
||
| (5 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}} | |
| − | + | <source lang="asp">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; | ||
| − | </ | + | </source> |
| − | Basically, a single Access Control setting is defined in an instance of the AccessControl class, created with | + | 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 | + | The most important (and required) properties of the <code>AccessControl</code> objects are: <code>Role</code>, <code>ResourceType</code> and <code>Folder</code>. |
| − | == | + | == 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 | + | == 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. | ||
| − | If this property is set to asterisk (*) the defined ACL is valid for all resource settings definined in the configuration file. | + | If this property is set to an asterisk (<code>*</code>), the defined ACL is valid for all resource settings definined in the configuration file. |
| − | == Folder == | + | == 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. | |
| − | You can apply ACL settings to specific folders by using the | ||
== 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. | ||
| − | + | == 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 <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; | ||
| − | </ | + | </source> |
| − | Note that we are reusing the | + | 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 | + | 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 | + | === 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: |
| + | <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; | ||
| − | </ | + | </source> |
| − | Now a user can view and create a folder, but | + | 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>== | == 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. | |
| − | If ACL for both <code>Company</code> and <code>Logos</code> folders | ||
Please also note that: | Please also note that: | ||
| − | * | + | * The folder path has to start from a slash character. |
| − | *If you use a wildcard for resource type (acl.ResourceType = "*";), CKFinder will look through all resource types and apply ACL to every folder that matches the rule, | + | * 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 | + | == 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 | + | To pass the name of the session variable to identify the user role to CKFinder, use the <code>RoleSessionVar</code> setting. For example: |
| − | < | + | <source lang="asp">RoleSessionVar = "CKFinder_UserRole";</source> |
| − | </ | + | 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 | ||
| − | 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 | + | The '''Admin''' role that has full permissions: |
| − | < | + | <source lang="asp">AccessControl acl = AccessControl.Add(); |
acl.Role = "Admin"; | acl.Role = "Admin"; | ||
acl.ResourceType = "*"; | acl.ResourceType = "*"; | ||
| Line 107: | Line 102: | ||
acl.FileRename = true; | acl.FileRename = true; | ||
acl.FileDelete = true; | acl.FileDelete = true; | ||
| − | </ | + | </source> |
| − | The '''User''' role | + | The '''User''' role that cannot rename or delete neither files nor folders: |
| − | < | + | <source lang="asp">AccessControl acl = AccessControl.Add(); |
acl.Role = "User"; | acl.Role = "User"; | ||
acl.ResourceType = "*"; | acl.ResourceType = "*"; | ||
| Line 123: | Line 118: | ||
acl.FileRename = false; | acl.FileRename = false; | ||
acl.FileDelete = false; | acl.FileDelete = false; | ||
| − | </ | + | </source> |
| − | The '''Guest''' role | + | The '''Guest''' role that can only view the folders contents: |
| − | < | + | <source lang="asp">AccessControl acl = AccessControl.Add(); |
acl.Role = "Guest"; | acl.Role = "Guest"; | ||
acl.ResourceType = "*"; | acl.ResourceType = "*"; | ||
| Line 139: | Line 134: | ||
acl.FileRename = false; | acl.FileRename = false; | ||
acl.FileDelete = false; | acl.FileDelete = false; | ||
| − | </ | + | </source> |
| − | |||
Latest revision as of 10:51, 4 March 2013
Contents
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 exampleFiles:/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;