Securing media libraries

Media libraries on your site can be secured or unsecured. To ensure the required functionality, several settings need to be configured as described below.

Setting up a secured media library

Secured media libraries allow viewing of their content to members of authorized roles or to authenticated users only. Keep in mind that secured media libraries are slower than unsecured ones as permission checking involves processing overhead.

Hosting environment settings

Set up your hosting environment so that files cannot be downloaded or accessed using direct file links, such as: <site url>/media/file.jpg

For example, if using an IIS (Internet Information Services) server:

1. Open IIS Manager – navigate to Start -> Control Panel -> Administrative Tools and start Internet Information Services (IIS) Manager.

2. In the connections pane, select the application for which you want to change the settings.

3. Navigate to the folder of your application for which you want to want to change the settings. You can find individual media library folder under <site name>/media.

4. In the Features View, double-click Authentication.

   1. Select Anonymous Authentication.
   2. In the Actions list, click Disable.
   3. (Optional) If Windows Authentication is enabled, disable it as well.

Additionally, you can configure direct file links for certain roles using Web.config authorization.

Media library security settings

Once you changed the settings in your hosting environment, you need to make changes in Xperience.

Changing security settings for a particular media library

1. Open the Media libraries application.
2. Edit () the Media library for which you want to set the permissions.
3. Switch to the Security tab.
4. Assign the See library content permission to Authenticated users or to Authorized roles.
5. (Optional) If you assigned the permission to Authorized roles, select the See library content check box for the roles which you want to allow to see the library content.

By default, Xperience does not evaluate the See library content permission which allows users to access the media library from the live site if permanent links are used. To make the system check for the permission, you need to enable the Check file permissions setting as described below.

Changing the Check file permissions setting

1. Open the Settings application.
2. Switch to Content -> Media.
3. In the Security settings group, select Check file permissions.
4. Save the changes.

Setting up an unsecured media library

Hosting environment settings

Set up your hosting environment so that files can be downloaded or accessed using direct file links, such as: <site url>/media/file.jpg

For example, if using an IIS (Internet Information Services) server:

1. Open IIS Manager – navigate to Start -> Control Panel -> Administrative Tools and start Internet Information Services (IIS) Manager.
2. In the connections pane, select the application for which you want to change the settings.
3. Navigate to the folder of your application for which you want to want to change the settings. You can find individual media library folder under <site name>/media.
4. In the Features View, double-click Authentication.
5. Select Anonymous Authentication.
6. In the Actions list, click Enable.
7. (Optional) If you disabled Windows authentication in order to secure your media libraries previously, you can now enable it.

Media library security settings

Once you changed the settings in your hosting environment, you need to make changes in Xperience.

Changing security settings for a particular media library

Note that if you want to change the settings temporarily and then revert back to the secured mode, you can simply turn checking file permissions off.

1. Open the Media libraries application.
2. Edit () the Media library for which you want to set the permissions.
3. Switch to the Security tab.
4. Assign the See library content permission to All users.

Changing check file permissions settings

1. Open the Settings application.
2. Switch to Content -> Media.
3. In the Security settings group, disable the Check file permissions setting.
4. Save the changes.

Image file request protection

The system allows you to protect image file endpoints (i.e., getmedia, getimage, getavatar, getattachment, getmetafile), so that access to resized variants of image files is restricted only to validated requests.

The protection works by adding a validation hash at the end of requests to system handlers that contain resize parameters for image files. When the request protection is enabled, a request to example.com/getmedia/1d35f70d-…-3a3a25bcf363/E5yfzxe.jpg?width=200 would return the image in the default size. To retrieve the image in the desired size, you need to generate a validation hash for the request URL: example.com/getmedia/1d35f70d-…-3a3a25bcf363/E5yfzxe.jpg?width=200&mediaprotectionhash=94f…fcf

To enable the request protection, enable the Settings → System → Files → Enable image file request protection setting in the administration interface.

Content authored in the system (e.g., image files inserted in the rich text) includes the validation hash. For content managed outside of the system (e.g., links to image files from stylesheets), you need to make sure that all image requests with the resize query parameter include the validation hash. There are two ways to generate the validation hash for image file requests:

• Generate the validation hash in code using the GetProtectedUrl method of the IMediaProtectionService.
  • Both relative and absolute request URLs are supported.
  Generate validation hash for a request

  Copy

  
  // An instance of the `IMediaProtectionService` obtained using the dependency injection
  IMediaProtectionService mediaProtectionService;
  
  // Retrieves a requests URL with a validation hash
  var urlWithHash = mediaProtectionService.GetProtectedUrl("~/getmedia/1d35f70d-dcd8-4dc8-a528-3a3a25bcf363/E5yfzxe.jpg?width=201");
  

• Generate the validation hash manually in the administration interface.

  1. Navigate to System → Files → Media protection.

  2. Enter a URL to a system image handler with a resize query parameter.

     • Both relative and absolute request URLs are supported.

  3. Select Get protected URL to receive a url with a validation hash.

Enable image file request protection on existing projects

When you enable the request protection on an existing project, you also need to ensure that any affected URLs in already existing content (i.e., any URLs to image files with resizing parameters) are updated to contain the validation hash. Otherwise, all affected URLs without a validation hash return image files in the original dimensions.

• Affected URLs in custom code need to be validated using the GetProtectedUrl method of the IMediaProtectionService.
• Affected URLs in static files need to be manually validated and replaced with a URL with a validation hash.
• Depending on the customizations in your project, you may also need to update the affected URLs in existing content to be converted to URLs with the validation hash.
• Affected URLs added to structured content of pages via the rich text field editor can be converted to URLs with the validation hash programmatically. You can examine the following sample converter implementation: UrlConverter.cs