Secure Web Files - Bloomreach Experience Manager (PaaS/Self-Hosted) - The Fast and Flexible Headless CMS
13-04-2022

Secure Web Files

Introduction

Goal

Configure which web files are publicly accessible.

Background

Web files are static resources used by the web application. Some must be publicly accessible so the browser client can use them to render a web page, e.g. CSS and Javascript files. Others, such as Freemarker templates, are only used server-side and should be secured from public access. Which web files are publicly accessible is configured through an allowlist.

Please note that in Bloomreach Experience Manager 14.x, the allowlist has a legacy filename (hst-whitelist.txt) that is considered culturally insensitive. As of Bloomreach Experience Manager 15.0, a more appropriate filename (hst-allowlist.txt) is used. However, due to backward compatibility, the legacy filename remains in use in all 14.x releases.

Allowing Public Access to Web Files

Which web files should be publicly (HTTP/HTTPS) accessible is configured through an allowlist. This is a file called hst-allowlist.txt in v15.x and hst-whitelist.txt in v14.x.

The allowlist file is located in the bundle's root directory. When the bundle's root directory is site, the allowlist is located in the project at

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

* When using v14.x, replace hst-allowlist.txt with hst-whitelist.txt.

Projects created using the Maven archetype contain a default allowlist that grants public access to the folders css/fonts/ and js/. The default contents of the allowlist 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/
An allowlist file is required. If an allowlist file is not present, then none of the web files are publicly accessible.
Make sure that *.txt is among the Included Files in your Web Files Configuration to ensure that the allowlist file gets imported into the repository. As of Web Files 2.0.1 and Bloomreach Experience Manager 10.0.3 *.txt is included in the default configuration.
Note that the allowlist is 'starts-with' based, e.g. allowing 'css' without '/' behind it, allows all files and folders that start with 'css'
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?