Secure Web Files

Overview

This page explains how to configure which web files are publicly accessible in Bloomreach Content.

Purpose

Control public access to static web files by defining an allowlist.

Background

Web files are static resources used by the web application. Files such as CSS and JavaScript must be accessible to browsers to render web pages. Other files, including Freemarker templates, are used only on the server and should not be exposed publicly. You control public access to web files using an allowlist.

In brXM 14.x, the allowlist file is named hst-whitelist.txt. This name is considered culturally insensitive. Starting with version 15.0, the file is renamed to hst-allowlist.txt. For backward compatibility, the legacy filename remains in use for all 14.x releases.

Configuring Public Access to Web Files

You define which web files are publicly accessible by creating an allowlist file. Use hst-allowlist.txt for version 15.x and hst-whitelist.txt for version 14.x.

Place the allowlist file in the root directory of the web file bundle. For example, if the bundle root is site, the allowlist file should be located at:

/repository-data:
  /webfiles:
    /src:
      /main:
        /resources:
          /site:
            /hst-allowlist.txt:

For version 14.x, use hst-whitelist.txt instead of hst-allowlist.txt.

Projects created with the Maven archetype include a default allowlist that grants public access to the css/, fonts/, and js/ directories. The default contents are:

##########################################################################
#                                                                        #
#   This file must contain all files and folders that                   #
#   must be publicly available over http. Typically folders              #
#   that contain server side scripts, such a freemarker                  #
#   templates, should not be added as they in general should             #
#   not be publicly available.                                           #
#                                                                        #
#   The allowlisting is *relative* to the 'web file bundle root'         #
#   which is the folder in which this hst-allowlist.txt file is          #
#   located.                                                             #
#                                                                        #
#   Examples assuming the web file bundle root is 'site':                #
#                                                                        #
#   css/       : allowlists all descendant web files below 'site/css/'   #
#   common.js  : allowlists the file 'site/common.js'                    #
#                                                                        #
#   Note that the allowlisting is 'starts-with' based, thus for          #
#   example allowlisting 'css' without '/' behind it, allowlists all     # 
#   files and folders that start with 'css'                              #
#                                                                        #
##########################################################################

css/
fonts/
js/

Warning: The allowlist file is required. If the file is missing, no web files will be publicly accessible.

To ensure the allowlist file is imported into the repository, verify that *.txt is included in your Web Files Configuration. As of Web Files 2.0.1 and brXM 10.0.3, *.txt is included by default.

The allowlist uses a "starts-with" match. For example, allowing css (without a trailing slash) grants access to all files and folders that start with css.