Sitemap and Mount Level HTTPS Support

Bloomreach Content supports seamless HTTP and HTTPS configuration at the sitemap and mount levels. This allows you to control which parts of your site require HTTPS, which are accessible via HTTP, and how the system responds when a request uses the wrong scheme.

Previously, the HST (Hippo Site Toolkit) was scheme-agnostic and served responses over both HTTP and HTTPS without distinction. Enforcing HTTPS was typically handled by adding a servlet filter before the HST filter, such as the httpsfilter. This approach relied on client-side redirects when requests used the wrong scheme.

The integrated HTTPS support in HST provides:

  1. Configuration at the host, mount, or sitemap item level to specify HTTP, HTTPS, or scheme-agnostic behavior.
  2. Automatic support for both HTTP and HTTPS URLs within a single HTML page.
  3. Configurable response codes (such as 301, 302, 403, 404) when a request uses an incorrect scheme.

If you have enabled SSL at the container level (for example, in Tomcat), you must either set the default scheme on the hst:host using hst:scheme = https or configure the host as scheme-agnostic with hst:schemeagnostic = true.

Configuring Scheme at Host, Mount, or Sitemap Item Level

You can configure the following properties on hst:virtualhost, hst:mount, and hst:sitemapitem nodes:

  1. hst:scheme (String): Supported values are "http" and "https".
  2. hst:schemenotmatchresponsecode (Long): Supported values are 200, 301, 302, 303, 307, 403, and 404.
  3. hst:schemeagnostic (Boolean).

On the hst:virtualhosts node, you can configure hst:scheme and hst:schemenotmatchresponsecode, but not hst:schemeagnostic.

Property values are inherited from ancestor nodes if not explicitly set. For example, a hst:sitemapitem without a defined hst:scheme inherits the value from its parent sitemap item or from the mount.

Default values on hst:virtualhosts:

hst:scheme: http
hst:schemenotmatchresponsecode: 301

Default value on hst:virtualhost:

hst:schemeagnostic: false

If you set hst:scheme = https on a hst:mount and do not override hst:scheme on any sitemap items, the entire channel will require HTTPS. Requests to that channel over HTTP will result in a permanent redirect (301) to HTTPS, unless you set a different value for hst:schemenotmatchresponsecode.

If your site is generally accessed over HTTP but you want a specific page (such as a contact page) to require HTTPS, set hst:scheme = https only on the relevant sitemapitem.

Using hst:schemeagnostic

  • If some URLs in production must use HTTPS, but you also need to access the site via an internal host without an SSL certificate, set hst:schemeagnostic = true on the internal host. When this property is true, the scheme of the request is ignored, even if the matching sitemap item requires HTTPS.
  • If a particular sitemap item should be accessible over both HTTP and HTTPS, set hst:schemeagnostic = true on that item. For example, if binaries are served via a sitemap item and should match the scheme of the HTML page, mark that sitemap item as scheme-agnostic.

Enabling Strict-Transport-Security

If you require the entire channel or site to use HTTPS, you may also want to set the Strict-Transport-Security response header. Configure this by adding the following property to the hst:virtualhost or hst:mount node:

hst:responseheaders = Strict-Transport-Security : max-age=31622400

The hst:responseheaders property is multi-valued. If it already exists, add the new header to the list. Adjust the max-age value as appropriate for your requirements.

Note: For more information, see Configure Security Response Headers.

Automatic HTTP and HTTPS URLs in a Single HTML Page

When a user visits a page, for example:

http://www.example.org/about

all links on that page that point to sitemap items configured with hst:scheme = https will be rendered as fully qualified HTTPS links.

Conversely, if a user visits:

https://www.example.org/contact

all links to sitemap items configured with hst:scheme = http (the default) will be rendered as fully qualified HTTP links.

Note: Cross-scheme links (HTTP to HTTPS and vice versa) are supported automatically, including links between different hosts or channels.

Configurable Response Codes for Scheme Mismatches

If a request uses the wrong scheme, you can control the response code that HST returns.

For example, if you want the contact page to require HTTPS, configure the sitemap item as follows:

hst:scheme: https

A request to http://www.example.org/contact will result in a 301 (permanent redirect) to:

https://www.example.org/contact

If you prefer a different response, such as a 302 (temporary redirect), 403 (forbidden), or 404 (not found), set the following property on the sitemap item, mount, or virtual host:

hst:schemenotmatchresponsecode: 403

The hst:schemenotmatchresponsecode property determines the HST's behavior when the request scheme does not match the required scheme for the matched sitemap item. Supported values:

  1. 200 (HttpServletResponse.SC_OK): The request is processed as if the scheme matched.
  2. 301 (HttpServletResponse.SC_MOVED_PERMANENTLY): Permanent redirect.
  3. 302, 303, 307 (HttpServletResponse.SC_MOVED_TEMPORARILY, HttpServletResponse.SC_SEE_OTHER, HttpServletResponse.SC_TEMPORARY_REDIRECT): Temporary redirect.
  4. 403 (HttpServletResponse.SC_FORBIDDEN): Returns a forbidden error page.
  5. 404 (HttpServletResponse.SC_NOT_FOUND): Returns a not found error page.

Web Server and Reverse Proxy Configuration

Ensure that your Apache HTTP Server or other reverse proxy is configured correctly.

You may need to add entries to your hosts file, such as:

127.0.0.1 cms.example.com
127.0.0.1 www.example.com
Share Feedback
Page: /about/for-architects/request-handling/hst-seamless-https-support
Section: About
Category *
Sitemap/Mount level HTTPS support | Bloomreach Content Documentation