Access Rules

• Jan 11, 2023
• 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.

Run Demo: ASPxFileManager - Access Control

Overview

Use the ASPxFileManager.SettingsPermissions.AccessRules collection property to specify access rules.

ASPX

<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:

ASPX

<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:

ASPX

<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:

ASPX

<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:

ASPX

<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 than Rule.Default and is specified in an access rule object with a higher index in the collection:

  ASPX

      <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 to Rule.Deny and has a higher index in the collection, the Edit permission has no effect. In this instance, a user cannot edit the folder nor its contents.

  ASPX

      <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:

ASPX

<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 to Rule.Deny, it takes priority.

• Otherwise, the priority is given to an access rule with a higher index in the collection.

  ASPX

  <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:

ASPX

<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:

  ASPX

  <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 to Rule.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.

  ASPX

  <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:

ASPX

<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:

ASPX

<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:

ASPX

<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:

ASPX

<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:

ASPX

<dx:ASPxFileManager ID="ASPxFileManager1" runat="server">
    <SettingsPermissions>
        <AccessRules>
            <dx:FileManagerFolderAccessRule Edit="Deny" Path="" />
            <dx:FileManagerFolderAccessRule Edit="Allow" Path="" Role="Admin" />
        </AccessRules>
    </SettingsPermissions>
</dx:ASPxFileManager>

C#

ASPxFileManager1.SettingsPermissions.Role = User.IsAdmin ? "Admin" : string.Empty;

VB.NET

ASPxFileManager1.SettingsPermissions.Role = If(User.IsAdmin, "Admin", String.Empty)