Documentation (Sitecore 5.1/5.2)

Sitecore MediaHandler module allows the developers to prevent unauthorized Extranet Users from downloading certain files from the web server. The module is implemented as .NET HttpHandler.

1. Installation Guide

The MediaHandler module is distributed as a standard Sitecore package. Thus to start using it, you should install the package. Please refer to the Installing Modules and Packages article if you are not familiar with the standard Sitecore Packager tool.

The package installs the sitecore.mediahandler.dll assembly to the “/bin” folder of your site, adds /downloads folder to the root directory of the site and the NoMediaAccess.html page to the /sitecore directory.

The /downloads folder contains the web.config file and a sample ncom.download file. The mentioned custom web.config file registers the Sitecore.MediaHandler class as a media handler for the files with the .download extension and from the /downloads folder of your site:

For this setting to work, it is also necessary to map the *.download extension to aspnet_isapi.dll in IIS. Please follow the steps below to do this:

Start IIS Manager;
Right-click a Web Site, select “Properties” from the context menu;
Switch to the “Home Directory” tab;
Click the ‘Configuration’ button in the ‘Application settings’ pane;
In the ‘Application Configuration’ dialog box, switch to the ‘Mappings’ tab;
Click the ‘Add’ button;
In the ‘Add/edit application extension mapping’ dialog box, enter the path to aspnet_isapi.dll and the extension of the file to map (.download).

Add the following setting into the <settings> section of the web.config file.

2. Administrator’s Manual

ASP.NET User in Windows 2000 and XP or Network Service User in Window 2003 Server must have read access rights to the downloadable files which are to be handled by the module. Since ASP.NET user is a member of the “Users” group, this is usually true by default.

For each _filename_._ext_ restricted file you should create a _filename_.download file in the /downloads folder.

The *.download file should have the following format:

the “file” attribute contains the full path to the restricted file.

the “roles” attribute contains a pipe-separated list of roles that are allowed to download the file. Asterisk character (“*”) means all roles.

Please see the ncom.download sample file.

After a *.download file is created, you can add a link to it at a web page, for example:

When a User clicks on the link to the *.download file, MediaHandler checks whether the User is currently logged in (Extranet Security) and whether the User is a member of a Role which is allowed to download the file. If so, the handler reads the file from the disk and flushes its content to output stream (the name of the file is handled correctly by appending a "content-disposition" header to the HTTP response).

If the User is not a member of any Role allowed to download the file, he will be redirected to the error page. By default, it is /sitecore/nomediaaccess.html, but a custom error page can be set by modifying the “NoMediaPermissionUrl” setting in the web.config file.