Media library configuration

Using the Media libraries application, users can store multimedia files such as photos, pictures, sound files, videos, package files, or documents. 

This page covers media library configuration options you may wish to use in your applications:

• Supported file types
• Enable upload of custom file types
• Image file request protection

Supported file types

Media libraries support the following types of images: bmp, gif, png, jpg, jpeg, tiff, tif, webp, avif. These types of image files can be uploaded to media libraries and displayed in your channels by default. Support for svg images can be enabled after considering the potential security impacts.

The system detects audio and video files based on their MIME type (audio types starting with the audio/ prefix and video types starting with the video/ prefix). For successfully detected audio and video file types, the system renders appropriate HTML5 markup. The types of files that can be previewed or played on your website therefore depend on the web browser (modern HTML5 web browsers typically support one or more of the ogg, mp4, or webm video codecs, and mp3, wav, or ogg audio codecs).

Enable upload of custom file types

If you want to configure the system to allow upload of a custom file type into media libraries, you need to:

1. Enable the custom extensions to be uploaded to the media library.
2. (Optional) If you want to use a custom extension as an image file, you need to configure the system to recognize the extension as an image file.

Customize allowed extensions

To customize the set of file types that can be uploaded into media libraries:

1. Open the Settings application.
2. Navigate to the Content → Assets category.
3. Add the selected file extensions into the Asset allowed extensions setting in the Security section (separated by semicolons).
4. Save the changes.

Specify image file types

By default, the system can recognize and process any media type, if you have the right player for the given file type. You can allow custom file types to be recognized as image files via a configuration key. However, by specifying image file types, you disable the automatic detection and support for media file types other than those explicitly added via your configuration.

To allow media files of specified types to be recognized as image files, add the CMSImageExtensions key to your application’s configuration file (appsettings.json by default).

"CMSImageExtensions": "bmp;gif;ico;png;wmf;jpg;jpeg;tiff;tif;webp;svg;avif;jfif;jfi;jif;jpe;dib"

Files of the specified types are now recognized as image files and will be, for example, offered in the Insert image dialog of the rich text editor.

Support for SVG images

Although the SVG vector format for images is supported by media libraries, it is not allowed by default. SVG images may host scripts or CSS and can pose a security risk. If you wish to use the SVG image format, you need to manually enable support for the extension.

The system does not perform sanitization of SVG images when they are uploaded. This means that SVG files stored in media libraries may potentially contain malicious content. The system protects against these risks by adding a CSP header to all responses that serve files through the system’s endpoints (/getmedia, etc.). This header prevents execution of inline scripts.

If your project uses custom endpoints or other functionality to serve images, you need to provide your own security measures.

Also consider additional security measures for SVG images if you have files mapped to external storage providers, such as Azure storage or Amazon S3. If files in external storage are accessed outside of Xperience endpoints, the system cannot provide any protection, and security depends on the features of the given storage provider.

Image file request protection

The system allows you to protect the media library image file endpoint (i.e., /getmedia), 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

Content authored in the system 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. To generate a validation hash for image file requests:

1. Make sure that the request protection is enabled. In the administration interface, enable the Settings → Content → Assets → Enable image file request protection setting.

2. Generate the validation hash using the GetProtectedUrl method of the IMediaProtectionService.

   • Both relative and absolute request URLs are supported.
   C#

   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");
    

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 the 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.