Access Rules
- 9 minutes to read
This topic explains how to manage security permissions for folders and files using a set of folder/file access rules (the ASPxFileManager.SettingsPermissions.AccessRules collection). To control rule priority, you must index rules within a collection. A rule with a higher index has a higher priority.
Note
Refer to the Permissions help topic if you wish to permit/deny access to individual files and folders, or to implement complicated user access logic.
Overview
Use the ASPxFileManager.SettingsPermissions.AccessRules collection property to specify access rules.
<dx:ASPxFileManager ID="ASPxFileManager1" runat="server" >
<SettingsPermissions>
<AccessRules>
<%-- Add folder and file access rules here. --%>
<dx:FileManagerFolderAccessRule Path="" Role="Guest" Upload="Deny" />
<dx:FileManagerFileAccessRule PathPattern="*.xml" Role="Guest" Edit="Deny" />
</AccessRules>
</SettingsPermissions>
</dx:ASPxFileManager>
Access rules are applied in the order they are defined in the collection. A rule with a higher index has a higher priority and can override the effect of a preceding rule. Each object in this collection is either a Folder or File access rule.
Important
We highly recommend that you specify only one permission in an access rule so that permission priority is explicitly defined by the order of access rule objects in the AccessRules collection. To specify multiple permissions for a single folder or file, create separate access rules for these permissions:
<AccessRules>
<dx:FileManagerFileAccessRule PathPattern="MyFile.txt" Edit="Deny" />
<%-- The rule below takes priority because it is specified later in the collection. --%>
<dx:FileManagerFileAccessRule PathPattern="MyFile.txt" Download="Deny" />
</AccessRules>
Folder Access Rules
A folder access rule is a FileManagerFolderAccessRule type object. A folder access rule affects the folder itself, all its subfolders and included files. To define a rule, specify the following properties for this object:
Path - The path to a folder to which the rule should be applied. The path is specified relative to FileManagerSettings.RootFolder.
Role - A security role for which the rule is in effect. If omitted, the rule affects all roles.
One of the properties that specify folder access permissions. See the Access Permissions section of this article for a full list of available properties.
The code sample below configures folder access rules:
<dx:ASPxFileManager ID="ASPxFileManager1" runat="server" >
<SettingsPermissions>
<AccessRules>
<dx:FileManagerFolderAccessRule Path="Documents" EditContents="Deny" />
<dx:FileManagerFolderAccessRule Path="Documents" Role="DocumentManager" EditContents="Allow" />
</AccessRules>
</SettingsPermissions>
</dx:ASPxFileManager>
File Access Rules
A file access rule is a FileManagerFileAccessRule type object. A file access rule affects a file (or a set of files) whose path matches a specified pattern. To define a rule, specify the following properties for this object:
PathPattern - A string value that specifies a file path pattern. The pattern can contain a wildcard character (
*
), which matches any character sequence. All files paths that match this pattern are affected by the rule.Role - A security role for which the rule is in effect. If omitted, the rule affects all roles.
One of the properties that specify file access permissions. See the Access Permissions section of this article for a full list of available properties.
The code sample below configures file access rules:
<dx:ASPxFileManager ID="ASPxFileManager1" runat="server" >
<SettingsPermissions>
<AccessRules>
<dx:FileManagerFileAccessRule PathPattern="*.xml" Edit="Deny" />
<dx:FileManagerFileAccessRule PathPattern="*.xml" Role="Admin" Edit="Allow" />
</AccessRules>
</SettingsPermissions>
</dx:ASPxFileManager>
Security Roles
Set the FileManagerSettingsPermissions.Role property to apply a security role to the File Manager control. This property accepts an arbitrary string that specifies role name.
You can associate any number of access rules with specific security roles to group related permissions together. Assign role name to an access rule object’s Role property to associate the rule with this role. If an access rule object’s Role
property is not set, this rule applies to all security roles.
The code sample below sets up security roles for the File Manager control and switches roles at runtime:
<dx:ASPxRadioButtonList ID="rblRole" runat="server" AutoPostBack="true" SelectedIndex="0" OnValueChanged="rblRole_ValueChanged">
<Items>
<dx:ListEditItem Text="Default User" Value="" Selected="True" />
<dx:ListEditItem Text="Document Manager" Value="DocumentManager" />
<dx:ListEditItem Text="Media Moderator" Value="MediaModerator" />
<dx:ListEditItem Text="Administrator" Value="Administrator" />
</Items>
</dx:ASPxRadioButtonList>
<dx:ASPxFileManager ID="FileManager" runat="server" ...>
...
<SettingsPermissions>
<AccessRules>
<dx:FileManagerFolderAccessRule Path="" Edit="Deny" />
<dx:FileManagerFileAccessRule PathPattern="*.xml" Edit="Deny" />
<dx:FileManagerFolderAccessRule Path="System" Browse="Deny" />
<dx:FileManagerFolderAccessRule Path="Documents" Role="DocumentManager" EditContents="Allow" />
<dx:FileManagerFolderAccessRule Path="Music" Role="MediaModerator" EditContents="Allow" />
<dx:FileManagerFolderAccessRule Path="Video" Role="MediaModerator" EditContents="Allow" />
<dx:FileManagerFolderAccessRule Path="" Role="MediaModerator" Upload="Deny" />
<dx:FileManagerFolderAccessRule Role="Administrator" Edit="Allow" Browse="Allow" />
</AccessRules>
</SettingsPermissions>
</dx:ASPxFileManager>
Access Permissions
An access rule should define access permission. A permission allows/prohibits specific user actions against specified files or folders. A permission is specified by the corresponding property of an access rule object.
Folder Access Rule Permissions
The table below lists access permission properties available for folder access rules:
Property Name | Description |
---|---|
Browse | Permission to view a folder and its contents |
Edit | Permission to rename, move or delete a folder, its subfolders and files |
EditContents | Permission to edit a folder’s files and subfolders |
Upload | Permission to upload files to a folder |
File Access Rule Permissions
The table below lists access permission properties available for file access rules:
Property Name | Description |
---|---|
FullAccess | Full access permission for a file |
Download | Permission to download a file |
Edit | Permission to rename, move or delete files/folders |
Permission Values
An access rule object’s permission properties accept values of the Rights enumeration type. The following values are available:
Value | Description |
---|---|
Rights.Allow | Allow the action. |
Rights.Deny | Prohibit the action. |
Rights.Default | If there is another permission that explicitly allows or denies the action, use that permission. Otherwise, allow the action. |
Access Permission Priority
Certain access rule permissions may produce overlapping/contradictory effects (when they affect the same files/folders or roles). To resolve overlaps/contradictions, the File Manager control prioritizes certain permissions over others based on a set of predefined rules.
Folder Access Rule
Browse
If the Browse
permission is set to Rule.Deny
, it has priority over any other folder access rule permission.
Edit
If the Edit
and EditContents
permissions are specified in separate access rule objects, priority is applied as follows:
The
Edit
permission takes priority if it has a value other thanRule.Default
and is specified in an access rule object with a higher index in the collection:<AccessRules> <%-- The EditContents permission has no effect. --%> <dx:FileManagerFolderAccessRule Path="Images" EditContents="Deny" /> <dx:FileManagerFolderAccessRule Path="Images" Edit="Allow" /> </AccessRules>
If the rule with the
EditContents
permission is set toRule.Deny
and has a higher index in the collection, theEdit
permission has no effect. In this instance, a user cannot edit the folder nor its contents.<AccessRules> <%-- The Edit permission has no effect. --%> <dx:FileManagerFolderAccessRule Path="Images" Edit="Allow" /> <dx:FileManagerFolderAccessRule Path="Images" EditContents="Deny" /> </AccessRules>
Important
If Edit
permission has a value other than Rule.Default
, the EditContents
permission setting specified in the same access rule object has no effect. In this instance, the Edit
permission defines whether a user can edit both the folder and its contents. Consider the example below:
<AccessRules>
<%-- The EditContents permission is ignored in both rules. --%>
<dx:FileManagerFolderAccessRule Path="Images" EditContents="Deny" Edit="Allow" />
<dx:FileManagerFolderAccessRule Path="Documents" EditContents="Allow" Edit="Deny" />
</AccessRules>
You should only specify one permission in an access rule object.
Upload
Upload
permission is only in effect if the EditContents
permission is in effect and not set to Rule.Deny
.
File Access Rule
Full Access
If the FullAccess
permission is set to Rule.Deny
, it has priority over any other file access rule permission. If the FullAccess
permission is set to Rule.Allow
, the Edit
permission specified in a separate rule has priority. See the Edit subsection for more information.
Download
The Download
permission has no effect if the FullAccess
permission is set to Rule.Deny
.
Edit
If FullAccess
and Edit
permissions are specified in separate access rule objects, priority is applied as follows:
- If an access rule’s
FullAccess
permission is set toRule.Deny
, it takes priority. Otherwise, the priority is given to an access rule with a higher index in the collection.
<AccessRules> ... <dx:FileManagerFileAccessRule PathPattern="*.txt" FullAccess="Allow"/> <%-- The rule below takes priority because it is specified later in the collection. --%> <dx:FileManagerFileAccessRule PathPattern="ReadOnly\*.txt" Edit="Deny"/> </AccessRules>
Important
If the FullAccess
permission has a value other than Rule.Default
, it has priority over the Edit
permission specified in the same access rule object. Consider the following example:
<AccessRules>
<%-- A user can rename and delete .txt files even though `Edit` is set to `Rule.Deny` --%>
<dx:FileManagerFileAccessRule PathPattern="*.txt" FullAccess="Allow" Edit="Deny"/>
</AccessRules>
It is highly suggested that you always specify only one permission in an access rule object.
File and Folder Access Rule Interaction
If a folder access rule’s Edit
or EditContents
permission is set to Rule.Deny
and is in effect, it has priority over Edit
or FullAccess
set to Rule.Allow
for any file contained in this folder or its subfolder.
Usage Considerations
Take the following additional considerations into account when you create access rules:
The File Manager does not allow users to delete, rename or move a folder if it contains files or folders with access restricted by an access rule:
<AccessRules> <%-- Users cannot edit the Text folder regardless of its Edit permission setting. --%> <dx:FileManagerFolderAccessRule Path="Text" Edit="Allow" /> <dx:FileManagerFileAccessRule PathPattern="Text\MyFile.txt" Edit="Deny" /> </AccessRules>
A file access rule’s
FullAccess
permission set toRule.Deny
disables all operations on affected files and hides files from the File Manager’s UI.When this permission is explicitly set to
Rule.Allow
, it enables all editing operations on the files if they are not prohibited by the relevant folder’s access rule or a file access rule with a higher index in the collection.Important
If your usage scenario requires you to explicitly enable the
FullAccess
permission in an access rule, make certain that all prohibitive rules required for the same files have a higher index in the AccessRules collection.<AccessRules> ... <dx:FileManagerFileAccessRule PathPattern="*.jpg" FullAccess="Allow" /> <%-- A prohibitive rule is specified later in the collection so it has priority. --%> <dx:FileManagerFileAccessRule Role="Guest" PathPattern="*.jpg" Edit="Deny" /> </AccessRules>
Examples
Allow a user to edit only .jpg files:
<dx:ASPxFileManager ID="ASPxFileManager1" runat="server">
<SettingsEditing AllowCreate="true" AllowDelete="true" AllowMove="true" AllowRename="true" />
<SettingsPermissions>
<AccessRules>
<dx:FileManagerFileAccessRule Edit="Deny" PathPattern="*" />
<dx:FileManagerFileAccessRule Edit="Allow" PathPattern="*.jpg" />
</AccessRules>
</SettingsPermissions>
</dx:ASPxFileManager>
Hide the ‘Admin’ folder from a user:
<dx:ASPxFileManager ID="ASPxFileManager1" runat="server">
<SettingsPermissions>
<AccessRules>
<dx:FileManagerFolderAccessRule Browse="Deny" Path="Admin" />
</AccessRules>
</SettingsPermissions>
</dx:ASPxFileManager>
Make a folder read-only for a user:
<dx:ASPxFileManager ID="ASPxFileManager1" runat="server">
<SettingsEditing AllowCreate="true" AllowDelete="true" AllowMove="true" AllowRename="true" />
<SettingsPermissions>
<AccessRules>
<dx:FileManagerFolderAccessRule Edit="Deny" Path="ReadOnly" />
</AccessRules>
</SettingsPermissions>
</dx:ASPxFileManager>
Allow a user to upload files only to the 'UploadFolder'
folder:
<dx:ASPxFileManager ID="ASPxFileManager1" runat="server">
<SettingsPermissions>
<AccessRules>
<dx:FileManagerFolderAccessRule Upload="Deny" Path="" />
<dx:FileManagerFolderAccessRule Upload="Allow" Path="UploadFolder" />
</AccessRules>
</SettingsPermissions>
</dx:ASPxFileManager>
Prohibit non-admin users to edit files:
<dx:ASPxFileManager ID="ASPxFileManager1" runat="server">
<SettingsPermissions>
<AccessRules>
<dx:FileManagerFolderAccessRule Edit="Deny" Path="" />
<dx:FileManagerFolderAccessRule Edit="Allow" Path="" Role="Admin" />
</AccessRules>
</SettingsPermissions>
</dx:ASPxFileManager>