Site HTTPS Troubleshooting

This page describes how Bloomreach Experience Manager (XM) handles HTTP and HTTPS requests, and how to troubleshoot common HTTPS configuration scenarios.

Overview

Earlier versions of the HST (Hippo Site Toolkit) were scheme agnostic. The HST responded to both http and https requests without distinction, and generated fully qualified links using http by default. In typical deployments, a httpsfilter was used in front of the HST to redirect traffic between HTTP and HTTPS as needed.

With the introduction of seamless HTTP/HTTPS support, the HST now checks the scheme of incoming requests against the scheme configured on the matched host, mount, or sitemap item. If the schemes do not match, the HST performs a client-side redirect to the configured scheme. By default, this scheme is http. If you require custom redirect logic, use the httpsfilter, or run the servlet container (such as Tomcat) with SSL support, you must adjust the HST configuration.

Custom HTTPS Redirect Logic

If you implement custom Java code (for example, in an HstComponent class) to redirect between http and https, set the following property in your HST configuration:

hst:schemeagnostic: true

You can set this property at the host, mount, or sitemap item level. When enabled, the HST behaves as it did prior to version 7.8.x and does not enforce scheme checks.

If you want to use seamless HTTPS support and implement your own redirect logic (such as with a custom HTTPS support valve), do not set the HST to scheme agnostic. Instead, configure the following property on the relevant hst:virtualhost node:

hst:customhttpssupport: true

When hst:customhttpssupport is set to true, the HST serves requests over https even if the matched mount or sitemap item is configured for http. This setting prevents browser redirect loops that can occur if custom Java code requires https while the sitemap item requires http.

SSL Support at the Container Level (e.g., Tomcat)

In most cases, Bloomreach recommends offloading HTTPS to a reverse proxy (such as Apache HTTPD) rather than configuring SSL directly on the servlet container. If you use SSL offloading, ensure the reverse proxy sets the X-Forwarded-Proto header. For configuration details, see configure Apache HTTP server as reverse proxy for Hippo.

If you configure SSL support directly on the servlet container (for example, following the Tomcat SSL documentation), update the HST configuration to allow only https requests. You can do this in one of two ways:

Set the default scheme for all hosts to https by configuring the following property on /hst:hst/hst:hosts:
```
hst:scheme: https
```
Set the following property on all root hst:virtualhost nodes:
```
hst:schemeagnostic: true
```

These configurations ensure that the HST responds appropriately to HTTPS requests when SSL is enabled at the container level.