Image and Asset Upload Validation

Overview

This page describes how to configure validation for uploaded images and assets in Bloomreach Content. Validation can include checks on file size, file extension, and—for images—resolution.

Security Consideration

Allowing uploads larger than approximately 20MB can expose your site to denial-of-service (DDOS) attacks. Set the maximum file size below 15MB to reduce this risk.

Validation Services

Uploaded files are validated before processing. The following components use upload validation:

  • GalleryWorkflowPlugin: Handles image and asset uploads to folders via the context menu (Add image / Add file).
  • ImageUploadPlugin and ResourceUploadPlugin: Used for uploading image variants (such as thumbnails) or asset files during editing.
  • CKEditor image picker dialog: Uploads through this dialog are validated by the image validation service.

By default, the file upload plugin attempts to load an instance of org.hippoecm.frontend.plugins.yui.upload.validation.FileUploadValidationService using the validator.id property. If no specific service is configured, the DefaultUploadValidationService is used.

DefaultUploadValidationService Configuration

The DefaultUploadValidationService validates file size and allowed file extensions. Configure this service at:

/hippo:configuration/hippo:frontend/cms/cms-services/assetValidationService
PropertyTypeDescriptionDefault value
max.file.sizeStringMaximum allowed file size per upload. Uses Wicket's Bytes.valueOf() for conversion.10mb
extensions.allowedString (multiple)Allowed file extensions (e.g., *.jpg, *.png). Leave blank to allow all extensions.
mimetypes.allowed
(Ignored since 14.7.0)		String (multiple)Ignored as of version 14.7.0. Use extension.mimetype.allowed.mappings instead. For values like image/tiff, skips MIME type validation against the upload stream. Useful for uncommon types such as TIFF or RAW.
extension.mimetype.allowed.mappings
(Available since 14.7.0)		String (multiple)Available since 14.7.0. Maps file extensions to Tika-detected MIME types (e.g., .aac,audio/x-aac). See Allow Extra MIME Types for details.

ImageUploadValidationService Configuration

The ImageUploadValidationService extends the default service with additional checks for image resolution and sets image-specific defaults. Configure this service at:

/hippo:configuration/hippo:frontend/cms/cms-services/imageValidationService
PropertyTypeDescriptionDefault value
max.file.sizeStringMaximum allowed file size per upload. Uses Wicket's Bytes.valueOf() for conversion.4mb
extensions.allowedString (multiple)Allowed file extensions (e.g., *.jpg, *.png). Leave blank to allow all extensions.*.jpg, *.jpeg, *.gif, *.png, *.svg
mimetypes.allowed
(Ignored since 14.7.0)		String (multiple)Ignored as of version 14.7.0. Use extension.mimetype.allowed.mappings instead. For values like image/tiff, skips MIME type validation against the upload stream. Useful for uncommon types such as TIFF or RAW.
max.widthLongMaximum allowed image width in pixels.1920
max.heightLongMaximum allowed image height in pixels.1280
extension.mimetype.allowed.mappings
(Available since 14.7.0)		String (multiple)Available since 14.7.0. Maps file extensions to Tika-detected MIME types (e.g., .aac,audio/x-aac). See Allow Extra MIME Types for details.

Allow Extra MIME Types

Available since version 14.7.0

Browsers provide a MIME type for uploads based on the file extension (e.g., .pdf), but this may not match the actual file content. For example, renaming example.gif to example.pdf results in a mismatch between the browser-provided and content-detected MIME types. If the backend detects a mismatch, it rejects the upload and returns a validation error such as:

The file 'sample.aac' content does not match with the given MIME type: audio/x-aac

The reported MIME type (audio/x-aac in this example) is the content-detected type.

If you encounter this error for a valid file extension, you can allow the extension and MIME type combination by configuring the extension.mimetype.allowed.mappings property. Add or update the property in either the assetValidationService or imageValidationService:

extension.mimetype.allowed.mappings: ['.aac,audio/x-aac']

To allow multiple mappings, separate them with commas:

extension.mimetype.allowed.mappings: ['.aac,audio/x-aac,.exe,application/x-dosexec']

Determine the required MIME type by attempting the upload and reviewing the error message.

Over 200 file extensions have been validated for asset uploads using this approach.

Media Validation Service

Available since brXM 16.7

The Media Validation Service enables pluggable validators for different media types. Validators can enforce format compliance, security requirements, and other criteria before files are stored in the repository.

When enabled, the CMS upload workflow selects the appropriate validator based on the file's MIME type. If validation fails, the upload is rejected and an error message is displayed.

SVG Security Validation

SVG files require additional security validation because they are XML-based and may contain embedded scripts, event handlers, or external references that introduce XSS or XXE risks.

The SVG validator blocks files containing:

  • Script elements and JavaScript event handlers
  • External content elements (<foreignObject>, <iframe>)
  • Dangerous URI schemes (such as javascript:, data:)
  • CSS-based attack patterns

The default configuration is designed to provide strong security for most use cases.

For configuration options, customization examples, and troubleshooting, refer to Media Validation Service.

WebP Image Support

Available since version 16.3.0

Starting with version 16.3, Bloomreach Content supports storing and serving WebP images. You can upload WebP images through the Images perspective, and they are delivered via the BinariesServlet like other image formats.

Key changes:

  • .webp is included as a default allowed extension for image uploads.
  • The commons-imaging library has been updated.
  • No additional configuration is required to store and serve WebP images.

Limitations:

WebP images are not scaled or cropped if you have defined imagesets with variants. This limitation exists because there is no official Java library for manipulating WebP images. Existing Java libraries rely on native components, which can introduce stability and maintenance issues.

Workarounds:

To enable scaling and cropping for WebP images, consider one of the following approaches:

  1. Add a Java Library

    • Integrate a Java library that provides ImageIO-compatible support for WebP, such as webp-imageio.
    • Add the library as a project dependency. The CMS will detect and use it automatically.
    • Note: Some users have reported segmentation faults with this library. Test thoroughly before deploying to production.

  2. Implement a Custom Gallery Processor

    • Create a custom gallery processor for WebP images.
    • Use the extension point org.hippoecm.frontend.plugins.gallery.processor.ScalingGalleryProcessor#handleMissingProcessor to implement scaling and cropping.
    • Refer to org.hippoecm.frontend.plugins.gallery.imageutil.AbstractScaleImageOperation for scaling and cropping routines.
    • For an example using GraphicsMagick, see webp-and-graphicsmagick.
    • You can also use other external or in-house services for WebP processing.
Share Feedback
Page: /build/editor-interface/image-and-asset-upload-validation
Section: Build
Category *
Image and Asset Upload Validation | Bloomreach Content Documentation