CKFinder 3 – ASP.NET Connector Documentation
Configuration

Configuration Files

This section describes how to configure the connector through static configuration files. If you prefer to configure the connector through code or if you require dynamic changes to your configuration, please refer to Configuration by Code.

The CKFinder WebApp uses two configuration files:

  • Web.config – The main settings and configuration file for an ASP.NET web application. It contains a section with the connector configuration, explained in this article.
  • config.js – An optional client-side configuration file, explained in the API documentation article about setting JavaScript configuration.

Connector Configuration

The following options can be set in the <ckfinder /> section of the Web.config file:

Attribute Name Type Description
cacheControlSeconds integer Configures cache lifetime for various CKFinder components.
checkDoubleExtension boolean Whether to allow for files with double file extension.
checkSizeAfterScaling boolean Indicates that the file size of uploaded images must be checked against the maxSize setting defined in the resource configuration only after scaling down (when needed). Otherwise, the size is checked right after uploading.
disallowUnsafeCharacters boolean Disallows creating folders and uploading files whose names contain characters that are not safe on an IIS web server. Due to security issues with IIS and classic ASP it is recommended to leave this option enabled.
enableCsrfProtection boolean Enables the CSRF protection in the connector. The default CSRF protection mechanism is based on double submit cookies.
enableVerboseLogging boolean Whether to enable verbose logging of exceptions.
overwriteOnUpload boolean Whether to overwrite files on upload instead of auto renaming. By default CKFinder automatically renames a file during upload when a file with the same name already exists in a folder. If enabled, then instead of auto renaming files, the existing files will be overwritten.
secureImageUploads boolean Whether to perform additional checks when uploading image files. If set to true, the connector will not accept files with image extensions that are not valid images.

This example demonstrates a sample <license /> section:

1 <ckfinder overwriteOnUpload="false"
2  checkDoubleExtension="true"
3  disallowUnsafeCharacters="false"
4  secureImageUploads="true"
5  checkSizeAfterScaling="true"
6  enableVerboseLogging="true">
7  <!--
8  Connector's configuration subsections: images, thumbnails, backends, etc.
9  -->
10 </ckfinder>

License

The <license /> subsection defines the CKFinder license. It has two attributes:

Attribute Name Type Description
name string The license name.
key string The license key.

This section is not mandatory, however, if it is not present or any of its attributes are missing or invalid, CKFinder will run in Demo mode.

This example demonstrates a sample <license /> section:

1 <license name="example.com" key="ABCD-EFGH-IJKL-MNOP-QRST-UVWX-YZ12" />

Images

The <images /> subsection defines settings for images. It has the following attributes:

Attribute Name Type Description
maxHeight integer The maximum height of uploaded images. If the image size is bigger than the one specified, the image will be resized to the defined dimensions.
maxWidth integer The maximum width of uploaded images. If the image size is bigger than the one specified, the image will be resized to the defined dimensions.
quality integer The quality of created images in a range from 1 to 100. The smaller the quality value, the smaller the size of resized images. Notice that an optimal quality value is about 80-90.

The <images /> subsection may contain the <sizes /> element with a collection of <size /> elements that define sizes of images that can be easily selected from CKFinder and passed to an external application (e.g. CKEditor) without having to resize the image manually.

Note: If maxWidth or maxHeight has value of 0 the limits are disabled.

The <size /> element has the following attributes:

Attribute Name Type Description
height integer The height boundary for the image.
name string The label used as an entry in the "Select Thumbnail" context menu. The translated label for a particular entry is taken from language files, for example small will be translated as lang.image["small"]. If a translation key is not set for the current language, an English version is used. If an English version was not found, an untranslated string is used (with the first letter set to uppercase).
quality integer The quality of the resized image in a range from 1 to 100.
width integer A width boundary for the image.

The last element that can be included in the <images /> subsection is <threshold />. This is a low-level internal configuration option used by CKFinder when showing image previews in various parts of the application. If CKFinder has an already resized version of an image in its cache and the size of the image is almost the same as requested (within the defined threshold), CKFinder will use that image.

This option increases performance by:

  • Avoiding having too many copies of images with almost the same size.
  • Avoiding scaling of images on every preview.

The <threshold /> element has the following attributes:

Attribute Name Type Description
percent integer The maximum difference in width and height in percent between the cached and the requested image.
pixels integer The maximum difference in width and height in pixels between the cached and the requested image.

This example demonstrates a sample <images /> subsection:

1 <images maxWidth="1280" maxHeight="720" quality="80">
2  <sizes>
3  <size name="small" width="480" height="320" quality="80" />
4  <size name="medium" width="600" height="480" quality="80" />
5  <size name="large" width="800" height="600" quality="80" />
6  </sizes>
7  <threshold pixels="80" percent="10" />
8 </images>

Thumbnails

The <thumbnails /> subsection defines settings for thumbnails. It has the following attributes:

Attribute Name Type Description
fileSystem string The name of a file system used for thumbnails. It must be defined in the <fileSystems /> section.
folder string The path and folder name for storing thumbnails.

The <thumbnails /> subsection should contain the <sizes /> element with a collection of <size /> elements that define sizes of thumbnails allowed to create.

The <size /> element has the following attributes:

Attribute Name Type Description
height integer The height boundary for the thumbnail.
quality integer The quality of a thumbnail in a range from 1 to 100.
width integer The width boundary for the thumbnail.

This example demonstrates a sample <thumbnails /> section:

1 <thumbnails folder="__thumbs" fileSystem="default">
2  <sizes>
3  <size width="150" height="150" quality="90" />
4  <size width="300" height="300" quality="80" />
5  </sizes>
6 </thumbnails>

Backends

The <backends /> subsection defines file system backends for the connector.

Each file system is represented by a <backends /> element with the following attributes:

Attribute Name Type Description
name string The name of the file system. Must be unique.
adapter string The type of the file system. Must equal to one of the values registered in FileSystemFactory. For WebApp possible values are local, dropbox, azure, s3 and ftp.
useProxyCommand boolean Whether the links to files stored in this file system should be pointing to the Proxy command.

The <backends /> elements may contain a collection of <option /> elements that define file system specific options.

Each <option /> element must have the following attributes defined:

Attribute Name Type Description
name string The name of the option.
value string The value of the option.

This example demonstrates a sample <fileSystems /> section:

1 <backends>
2  <backend name="default" adapter="local" useProxyCommand="true">
3  <option name="root" value="userfiles" />
4  </backend>
5  <backend name="remote" adapter="dropbox">
6  <option name="accessToken" value="ACCESSTOKEN" />
7  <option name="root" value="ckfinder_files" />
8  </backend>
9 </backends>

Local Backend

A local file system backend of local type.

Option Name Description
root The path to the root folder on local file system.
baseUrl
Optional
The base URL used for direct access to CKFinder files. This URL must correspond to the directory where CKFinder users' files are stored.

This example demonstrates a sample local backend:

1 <backend name="myBackend" adapter="local">
2  <option name="root" value="C:\Files" />
3  <option name="baseUrl" value="http://example.com/" />
4 </backend>

Dropbox Backend

A Dropbox backend of dropbox type. This backend allows you to attach any of the folders existing on your Dropbox account to CKFinder.

Option Name Description
root
Optional
The path to the root folder in the Dropbox account.
accessToken The access token to the Dropbox account.
baseUrl
Optional
The base URL used for direct access to CKFinder files on Dropbox (if you use a public folder, you can find a common prefix for all public files).

This example demonstrates a sample Dropbox backend:

1 <backend name="myBackend" adapter="dropbox">
2  <option name="root" value="Files" />
3  <option name="accessToken" value="YOUR-ACCESS-TOKEN" />
4  <option name="baseUrl" value="http://example.com/" />
5 </backend>

To use CKFinder with Dropbox you need an application token generated for your Dropbox account. To generate the token go to Dropbox App Console and create a new application, like on the screencast below:

dropbox_token.gif
Creating Dropbox application token

Note that when creating the application you can define the folder accessible by this application. In the example above access to an entire Dropbox account was allowed.

Azure Backend

An Azure Storage backend of azure type. This backend allows you to attach your Azure storage to CKFinder.

Option Name Description
account The name of the account.
container The name of the container.
key The access key to the account.
root
Optional
The path to the root folder in the container in the Azure Storage account.
baseUrl
Optional
The base URL used for direct access to CKFinder files on Azure.

This example demonstrates a sample Azure Storage backend:

1 <backend name="myBackend" adapter="azure">
2  <option name="root" value="Files" />
3  <option name="account" value="YOUR-ACCOUNT-NAME" />
4  <option name="key" value="YOUR-ACCESS-KEY" />
5  <option name="container" value="CKFinderContainer" />
6  <option name="baseUrl" value="http://example.com/" />
7 </backend>

Amazon S3 Backend

An Amazon S3 backend of the s3 type. This backend allows you to attach your Amazon S3 storage to CKFinder.

Option Name Description
bucket The name of the bucket.
key The access key to the account.
secret The secret for your account.
region The name of the S3 region. For list of regions and their endpoints please refer to http://docs.aws.amazon.com/general/latest/gr/rande.html#s3_region
root
Optional
The path to the root folder in the bucket in the Amazon S3 account.
baseUrl
Optional
The base URL used for direct access to CKFinder files on Amazon S3 (if the files are publicly visible, you can find a common prefix for them, for example http://s3-eu-west-1.amazonaws.com/bucket).
signatureVersion
Optional
Signature version for region (by default set to 4). For list of regions and supported signature versions please refer to http://docs.aws.amazon.com/general/latest/gr/rande.html#s3_region.

This example demonstrates a sample Amazon S3 backend:

1 <backend name="myBackend" adapter="s3">
2  <option name="root" value="Files" />
3  <option name="secret" value="YOUR-SECRET" />
4  <option name="key" value="YOUR-KEY" />
5  <option name="bucket" value="CKFinderBucket" />
6  <option name="region" value="eu-west-1" />
7  <option name="baseUrl" value="http://example.com/" />
8 </backend>

FTP Backend

A FTP backend of the ftp type. This backend allows you to files from FTP server in CKFinder.

Option Name Description
host The hostname of the FTP server.
port The port number of the FTP server.
userName The username for connection to the FTP server.
password The password for connection to the FTP server.
root
Optional
The path to the root folder in the FTP server.
ftpEncryption
Optional
An encryption mode to use. Valid values are: none, ssl, tls.
baseUrl
Optional
The base URL used for direct access to CKFinder files on the FTP server.

This example demonstrates a sample FTP backend:

1 <backend name="myBackend" adapter="ftp">
2  <option name="root" value="Files" />
3  <option name="host" value="localhost" />
4  <option name="port" value="21" />
5  <option name="userName" value="ckfinder" />
6  <option name="password" value="secret*password" />
7  <option name="ftpEncryption" value="tls" />
8  <option name="baseUrl" value="http://example.com/" />
9 </backend>

Resource Types

A resource type is nothing more than a way to group files under different paths, each one having different configuration settings. Resource types are represented in CKFinder as "root folders". Each resource type may use a different backend.

By default the CKFinder configuration file comes with two sample resource types configured: Files and Images. There are no restrictions on the maximum number of resource types configured. You can change or remove the default ones, but make sure to configure at least one resource type.

The <resourceTypes /> subsection defines available resource types. Each resource type is represented by a <resourceType /> element with the following attributes:

Attribute Name Type Description
name string A machine-friendly name of the resource type that will be used for the communication between the CKFinder UI and the server connector. Must be unique.
backend string The name of a backend. It must be defined in the <backends /> section.
folder string The path to files on the file system.
allowedExtensions string The file extensions you wish to be allowed for upload with CKFinder.
deniedExtensions string The file extensions you do not wish to be uploaded with CKFinder. Shall only be set if allowedExtensions is left empty.
maxSize integer The maximum allowed file size to be uploaded in bytes.
lazyLoad boolean If set to true, the Init command will not check if the resource type contains child folders. This option is especially useful for remote backends, as the Init command will be executed faster, and therefore CKFinder will start faster, too. It is recommended to set it to true for remote backends.

Important: It is recommended to always use the allowedExtensions setting, in favor of deniedExtensions. If you leave allowedExtensions empty and add an extension to the deniedExtensions list, for example pdf, the settings will allow the upload of all other files except the files with the pdf extension (e.g. .php or .exe files).

This example demonstrates a sample <resourceTypes /> subsection:

1 <resourceTypes>
2  <resourceType name="Files" folder="files" maxSize="1000000" allowedExtensions="doc,txt,zip" backend="default" />
3  <resourceType name="Images" folder="images" allowedExtensions="bmp,gif,jpeg,jpg,png" backend="default" />
4 </resourceTypes>

Access Control

Access Control List (ACL) is a feature that grants your users different permissions for working with CKFinder folders and files. The default settings grant full permissions for all options to every user.

The <accessControl /> subsection defines the ACL. Each rule is represented by a <rule /> element with the following attributes:

Attribute Name Type Description
resourceType string The name mask of the resource type (see Resource Types).
role string The role mask of the user for which the ACL setting is provided.
fileDelete
Optional
enumeration Whether the user can delete files. Possible values are: allow, deny and inherit.
fileRename
Optional
enumeration Whether the user can rename files. Possible values are: allow, deny and inherit.
fileUpload
Optional
enumeration Whether the user can create (e.g. upload) files. Possible values are: allow, deny and inherit.
fileView
Optional
enumeration Whether the user can view the file content. Possible values are: allow, deny and inherit.
folder string The path mask of the folder where the restrictions will be used.
folderCreate
Optional
enumeration Whether the user can create a folder. Possible values are: allow, deny and inherit.
folderDelete
Optional
enumeration Whether the user can delete a folder. Possible values are: allow, deny and inherit.
folderRename
Optional
enumeration Whether the user can rename a folder. Possible values are: allow, deny and inherit.
folderView
Optional
enumeration Whether the user can view the list of files. Possible values are: allow, deny and inherit.
imageResize
Optional
enumeration Whether - when choosing the image - the user can resize it to dimensions predefined in the configuration file. Possible values are: allow, deny and inherit.
imageResizeCustom
Optional
enumeration Whether - when choosing the image - the user can resize it to any dimensions. Possible values are: allow, deny and inherit.

Note: The imageResize and imageResizeCustom attributes correspond to the Choose Resized feature which automatically creates a resized version of the chosen image. They do not affect resizing of the image modified in the CKFinder's image editor (Edit feature).

It is possible to define numerous ACL entries. Subfolders inherit their default settings from their parents' definitions.

About Masks

Masks may contain:

  • Asterisk (*) characters which will match zero or more characters.
  • Question mark (?) characters which will match exactly one character.

Example masks for folders:

Mask /path/to/folder /another path/to/folder /path/ o/folder /path/to/nowhere
/path/to/folder Yes No No No
*/to/folder Yes Yes No No
/path/?o/folder Yes No Yes No
/path/??/* Yes No Yes Yes

This example demonstrates a sample <accessControl /> section:

1 <accessControl>
2  <rule role="*"
3  resourceType="*"
4  folder="*"
5  folderView="allow"
6  folderCreate="allow"
7  folderRename="allow"
8  folderDelete="allow"
9  fileView="allow"
10  fileUpload="allow"
11  fileRename="allow"
12  fileDelete="allow"
13  imageResize="allow"
14  imageResizeCustom="allow" />
15  <rule role="User"
16  resourceType="Files"
17  folder="/"
18  folderView="allow"
19  folderCreate="allow"
20  folderRename="allow"
21  folderDelete="deny"
22  fileView="allow"
23  fileUpload="deny"
24  fileRename="deny"
25  fileDelete="deny" />
26 </accessControl>

HTML Extensions

Types of files that may allow for HTML code in the first kB of data.

Sometimes when uploading a file it may happen that a file contains HTML code in the first kilobytes of its data. CKFinder will upload the file with the HTML code only when the file extension is specified in htmlExtensions.

The <htmlExtensions /> subsection contains a collection of <extension /> elements with the following attribute:

Attribute Name Type Description
name string The extension of a file to be allowed to contain HTML code.

This example demonstrates a sample <htmlExtensions /> subsection:

1 <htmlExtensions>
2  <extension name="html" />
3  <extension name="htm" />
4  <extension name="xml" />
5  <extension name="js" />
6 </htmlExtensions>

Hidden Folders

Folders that are not to be displayed in CKFinder, no matter their location.

The <hideFolders /> subsection contains a collection of <folder /> elements with the following attribute:

Attribute Name Type Description
name string The mask for the name of the folder to be hidden.

This example demonstrates a sample <hideFolders /> subsection:

1 <hideFolders>
2  <folder name=".*" />
3  <folder name="__thumbs" />
4 </hideFolders>

Hidden Files

Files that are not to be displayed in CKFinder, no matter their location.

The <hideFiles /> subsection contains a collection of <file /> elements with the following attribute:

Attribute Name Type Description
name string The mask for the name of the file to be hidden.

This example demonstrates a sample <hideFiles /> subsection:

1 <hideFiles>
2  <folder name=".*" />
3  <folder name="Changelog.txt" />
4 </hideFiles>

Plugins

The <plugins /> subsection defines plugins to be enabled in the connector.

Each plugin is represented by a <plugin /> element with the following attribute:

Attribute Name Type Description
name string The name of the plugin. It also defines the folder name where the plugin is located.

The <plugin /> elements may contain a collection of <option /> elements that define plugin-specific options.

Each <option /> element must have the following attributes defined:

Attribute Name Type Description
name string The name of the option.
value string The value of the option.

This example demonstrates a sample <plugins /> subsection:

1 <plugins>
2  <plugin name="FirstPlugin">
3  <option name="pluginOption" value="pluginValue" />
4  <option name="pluginOptionCollection" value="collectionValue1" />
5  <option name="pluginOptionCollection" value="collectionValue2" />
6  <option name="pluginOptionCollection" value="collectionValue3" />
7  </plugin>
8  <plugin name="SecondPlugin" />
9 </plugins>

Roles Configuration

By default the connector extracts roles from the Claims passed in the .AspNet.ApplicationCookie cookie. The connector does not perform any authentication by itself and it is up to another application to authenticate the user and set the cookie.

Note: Under IIS the authentication cookie is encrypted using the MachineKey.Encrypt method. This means that CKFinder should be hosted on the same machine as the application doing the authentication. Alternatively, the machine key may be set in Web.config. Refer to MSDN for more information.

To change the method of role extraction, implement an IAuthenticator interface and assign it to the connector using the ConnectorBuilder.SetAuthenticator method.

WebApp-only Configuration Options

The sample project WebApp contains two additional options present in the <appSettings /> section of the Web.config file:

  • ckfinderAllowedRole – A mask for user roles that may have access to CKFinder.
  • ckfinderRoute – The route for CKFinder connector. It is a virtual path under which the connector is listening for commands. It should be in sync with the CKFinder JavaScript client connectorPath.