Quick Start Guide

Table of Contents

• Before You Begin
• Installation
  • Installation with NuGet Package
  • Installation with ZIP Package
• Initial Configuration
  • Authentication
  • Connector Route
  • Folder Permissions
  • Security
• Troubleshooting
  • JSON MIME Type Support
  • ASP.NET Support in IIS
  • Request Length Limit in IIS

Before You Begin

Have a look at the System Requirements section to make sure that your server meets all the application requirements. Check the Troubleshooting section for more information on how to adjust some IIS server settings such as JSON MIME type support (needed for language files), ASP.NET support or request length limit.

Installation

When you are sure that your server configuration is correct, complete the steps below to start using CKFinder.

The CKFinder ASP.NET connector can be installed in two ways:

• Installation with the ZIP distribution package. This is the simplest installation method that may be preferred if you want to quickly set up the application to give it a try.
• Installation as a NuGet package. This installation method is preferred if you want to integrate CKFinder with your application.

Important: The installation methods described below assume that the CKFinder server-side connector will be running as a standalone application. If you want to integrate the connector with an existing application, refer to the Integration section.

Important: Paths to content files (such as ckfinder.js, ckfinder.html, the connector files) differ between ZIP and NuGet packages:

• For ZIP package all content files are located in the ckfinder folder in the root of the project.
• For NuGet packages content files are added to the CKFinderScripts folder.

Most examples used in the documentation assume the usage of the ZIP package and its default paths.

Installation with NuGet Package

1. Install required NuGet packages (please have a look at Integrating in Existing Application article).
2. Configure the connector through the Web.config file (see Configuration) or through the Startup.cs file (see Configuration by Code).
3. Publish the application to your IIS server.
4. Configure required folder permissions (see Folder Permissions).
5. Configure authentication (see Authentication).

With CKFinder up and running you can now focus on adjusting some configuration options to your needs. Alternatively, you may edit the configuration in your Startup.cs file.

Installation with ZIP Package

1. Visit the CKFinder Download site and download the ZIP package for the ASP.NET version.
2. Unpack the distribution package to the wwwroot directory of your web server. This will place all files in the ckfinder directory. Please note that the name of this directory is important, because it will be used as a virtual path to the CKFinder connector application (by default CKFinder expects it to point to /ckfinder/connector). If you decide to use a different directory name, you will have to define an appropriate connector path for the CKFinder JavaScript client side (see connectorPath). You also need to take care to keep the route pointed by ckfinderRoute in sync with the CKFinder JavaScript client connectorPath.
3. Add the connector application to the Default Web Site application pool:
   • Open IIS Manager (InetMgr.exe).
   • In the Connections tab navigate to the /ckfinder/ directory, open the context menu and choose Convert to Application.
     
   • Click OK in the displayed dialog window.
4. Configure required folder permissions (see Folder Permissions).
5. Configure authentication (see Authentication).

Almost done! If you open the CKFinder samples page (located in /ckfinder/samples/), you will now see some working CKFinder samples. Depending on server permissions you may even be able to create a folder or upload files without further actions — if not, read more.

Initial Configuration

After you installed CKFinder, some configuration is needed in order to make it work.

By default the CKFinder configuration is stored in the Web.config file. Please refer to the Configuration section to find out more about available configuration options.

If you want to configure the connector through code to support dynamic configuration changes, please refer to Configuration by Code.

Note: If CKFinder was installed using the ZIP package, you can define your dynamic configuration in the App_Data/ConnectorConfig.cs file. This file has a special purpose and does not require manual compilation — the configuration defined here will be compiled and applied during runtime.

Authentication

By default, the CKFinder server connector is disabled. If you open the CKFinder full page sample (located in /ckfinder/samples/full-page-open.html for the ZIP package and /ckfinder/CKFinderScripts/samples/full-page-open.html for the NuGet package) you will see the following error message:

The file browser is disabled for security reasons. Please contact your system administrator and check the CKFinder configuration file.

In order to enable it, you should set the mask for allowed roles in the ckfinderAllowedRole setting in the <appSettings /> section of the Web.config file so that it matches users that should have access to CKFinder.

The simplest way to enable CKFinder (insecure, though):

<add key="ckfinderAllowedRole" value="*" />

If you would like to use a different authentication method, you have to implement the IAuthenticator interface and pass its instance to the ConnectorBuilder.SetAuthenticator method.

For more details please refer to the Implementing Authenticator HOWTO section.

Connector Route

The CKFinder connector is listening for commands under the route defined in the ckfinderRoute setting in the <appSettings /> section of the Web.config file.

By default is should be configured to /ckfinder/connector:

<add key="ckfinderRoute" value="/ckfinder/connector" />

If you want CKFinder to listen under a different route, remember to adjust the JavaScript configuration's connectorPath, too.

Folder Permissions

The connector requires the Modify permission to be set for two folders:

• /ckfinder/userfiles/ — The directory where user files will be stored (defined as a root option for the default backend).
• /ckfinder/App_Data/ — The directory for private application files (like logs and thumbnails).

The above are default locations that can be changed in the Configuration.

To add the Modify permission to the folder, proceed as follows:

1. Right click on a folder for which you want to change the permissions and choose Properties.
2. Open the Security tab and click the Edit... button.
3. In the opened Permissons window you will see a list of groups and user names. Find the built-in user account used by the IIS server and select it. The account should be easily distinguishable as its name starts with IIS (for example IIS_IUSRS).
4. Select the Modify permission from the list at the bottom of the dialog window.
5. Click Apply and OK to close the dialog window.

Security

In case when the files managed by CKFinder are served through the web server, it is recommended to perform some server configuration fine-tuning to make sure the files are served in a secure manner. To read more, please have a look at the following article: Securing a Publicly Accessible Folder.

Troubleshooting

If you have trouble installing and running CKFinder on IIS, check the following tips on how to adjust some server settings in order to resolve your issues. If CKFinder does not work as intended after the initial configuration and your server settings adjustments, please have a look at the Debugging and Logging section.

JSON MIME Type Support

If you are using IIS Express as your web server, you will need to make sure that JSON is an allowed MIME type. By default it is not allowed which may cause issues with CKFinder language files being unavailable, and you will see the following alert in CKFinder:

Alert message about missing JSON support in IIS

You will thus need to add JSON as a new MIME type in your IIS configuration.

Set the following options in the Add MIME Type dialog:

• File name extension: .json.
• MIME type: application/json.

Click OK to accept and restart the server to apply your changes.

ASP.NET Support in IIS

In some versions of IIS, .NET Framework 4.5 is not registered by default. If you get an error like this one:

Error message shown when .NET Framework is not registered in IIS

it means you will need to register the .NET Framework manually. To do this run aspnet_regiis.exe -i. You can find aspnet_regiis.exe in %WINDIR%\Microsoft.NET\Framework64\v4.0.30319.

Request Length Limit in IIS

If you are using IIS for hosting your application, the default upload file size is 4MB. In order to change it, modify these two attributes in your Web.config file to suit your needs:

<configuration>
  <system.web>
    <httpRuntime maxRequestLength="maximum_request_length_in_KILOBYTES" />
    <!--
      For example 10MB = 10 * 1024 = 10240
      <httpRuntime maxRequestLength="10240" />
    -->
  </system.web>
</configuration>

<configuration>
  <system.webServer>
    <security>
      <requestFiltering>
        <requestLimits maxAllowedContentLength="maximum_request_length_in_BYTES" />
        <!--
          For example 10MB = 10 * 1024 * 1024 = 10485760
          <requestLimits maxAllowedContentLength="10485760" />
        -->
      </requestFiltering>
    </security>
  </system.webServer>
</configuration>

Note: If you already have the these sections in your configuration, add only the required attributes.