Image and Asset Upload Validation - Bloomreach Experience Manager (PaaS/Self-Hosted) - The Fast and Flexible Headless CMS

Image and Asset Upload Validation

Introduction

Goal

Configure the validation of uploaded images and assets.

Background

Uploaded files can be validated before they are processed. This means validating properties like file size and file extension or more specific ones like image resolution.

The validation services are used in the following sections:

  • GalleryWorkflowPlugin: this plugin takes care of uploading image/asset files to a image/asset folder via the context menu (Add image / Add file).
  • ImageUploadPlugin/ResourceUploadPlugin: these plugins are used to upload an image variant (e.g. thumbnail variant) or an asset file when editing an image/asset.
  • The image picker dialog in the CKEditor: uploading file via the image picker will be validated by the image validation service.

By default, the file upload plugin will try to load an instance of the org.hippoecm.frontend.plugins.yui.upload.validation.FileUploadValidationService by looking up a service specified by the property validator.id. If no specific service is found, the DefaultUploadValidationService is used.

Configuration

The DefaultUploadValidationService will validate file size and file extension(s). It can be configured at /hippo:configuration/hippo:frontend/cms/cms-services/assetValidationService.

Property Type Description Default value
max.file.size

String

Maximum file size allowed per file. The value is converted using Wicket's Bytes.valueOf()

10mb
extensions.allowed

String multiple

File extensions allowed. Values are configured as *.jpg, *.png, etc. Leave blank for all extensions.

 
mimetypes.allowed
(Ignored since 14.7.0)

String multiple

This property is ignored as of version 14.7.0. Use extension.mimetype.allowed.mappings instead.

For the configured values like image/tiff, validation of the upload's mime type against the actual upload stream is skipped. This can be helpful if the validation doesn't work for unusual types like TIFF or RAW.

 

extension.mimetype.allowed.mappings 
(Available since 14.7.0)

String multiple
Available since version 14.7.0.

Mapping from extension to Tika detected MIME type. An example mapping is .aac,audio/x-aac. See Allow Extra MIME Types below for more information on this property and how to find out the required values.

 

The ImageUploadValidationService extends the DefaultUploadValidationService and adds validation of the image resolution as well as more image specific default values.

It is located at /hippo:configuration/hippo:frontend/cms/cms-services/imageValidationService.

Property Type Description Default value
max.file.size

String

Maximum file size allowed per file. The value is converted using Wicket's Bytes.valueOf()

4mb
extensions.allowed

String multiple

File extensions allowed. Values are configured as *.jpg, *.png, etc. Leave blank for all extensions.

*.jpg, *.jpeg, *.gif, *.png, *.svg
mimetypes.allowed 
(Ignored since 14.7.0)

String multiple

This property is ignored as of version 14.7.0. Use extension.mimetype.allowed.mappings instead.

For the configured values like image/tiff, validation of the upload's mime type against the actual upload stream is skipped. This can be helpful if the validation doesn't work for unusual types like TIFF or RAW.

 

max.width

Long

Maximum horizontal number of pixels allowed.

1920

max.height

Long

Maximum vertical number of pixels allowed.

1280

extension.mimetype.allowed.mappings 
(Available since 14.7.0)

String multiple
Available since version 14.7.0.

Mapping from extension to Tika detected MIME type. An example mapping is .aac,audio/x-aac. See Allow Extra MIME Types below for more information on this property and how to find out the required values.

 

Allow Extra MIME Types

This feature is available since version 14.7.0.

When uploading a file, a browser provides a MIME type based on the extension, for example .pdf. However, this MIME type does not necessarily match the actual MIME type of the contents of the file. Anyone can rename example.gif file to example.pdf and upload it: in that case the browser-provided MIME type is different from the content-detected MIME type. If the back-end detects a discrepancy between the browser-provided MIME type and the content-detected MIME type, a validation error is returned and the file upload is not allowed. It is likely that the file has been mangled with, for example a .exe has been renamed to .pdf

The new feature has been tested with 200+ different file extensions. However, during testing, it was found that browsers can sometimes send different MIME types for the same extension. Although the back-end checks for different provided MIME types whether they are a super or subtype of the content-detected MIME type, some browsers send a MIME type for an extension which the back-end cannot map to the content-detected MIME type. If such a use case happens, the CMS user gets to see a failure message during upload, for example:

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

The 'given MIME type' above is the back-end, content-detected MIME type.

If this happens while the file extension is correct, this extension can be configured to be allowed in extension.mimetype.allowed.mappings. Such a mapping will replace the browser-provided MIME type for a given file extension such that the browser-provided MIME type is ignored.

For either the assetValidationService or imageValidationService  add or update it to contain:

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

So from the error message in the CMS file upload, use the extension, followed by a comma, followed by the MIME type from the error message. In case a second value is needed, for example if you want .exe files to be allowed to be uploaded (.exe is by default not allowed), make it:

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

You can get hold of the value 'x-dosexec' by trying to upload a .exe and analyzing the resulting error message:

The file 'sample.exe' content does not match with the given MIME type: application/x-dosexex

Any image type can be uploaded and 200+ different file extensions have been validated as asset to upload. 

Did you find this page helpful?
How could this documentation serve you better?
On this page
    Did you find this page helpful?
    How could this documentation serve you better?