HST Custom HTTPS Support

Overview

Bloomreach Content provides built-in HTTPS support at the site (mount) or sitemap item level through HST seamless HTTPS support. However, this approach may be too broad for scenarios where you need HTTPS enforcement based on specific content or business logic. For example:

• Enforce HTTPS for any document containing a form component.
• Require HTTPS for documents that link to a form document.
• Require HTTPS for documents with the myproject:secure mixin.

In these cases, you may have documents under the same sitemap item that require different schemes (HTTP or HTTPS). The standard seamless HTTPS support does not address this level of granularity. To implement domain-specific HTTPS rules, you must provide custom logic. HST includes utilities to simplify this process.

Prerequisites

To enable custom HTTPS support, you must set the following property on the relevant hst:virtualhost node (or one of its ancestors):

hst:customhttpssupport: true
copy

If you encounter a browser redirect loop, verify that this property is set. This configuration prevents conflicts between seamless HTTPS support and your custom logic. Without hst:customhttpssupport = true, the default scheme may override your custom redirects, resulting in redirect loops. Setting this property allows HTTPS requests even when the default hst:scheme is http.

Implementing Custom HTTPS Logic

You can implement custom HTTPS redirects in a HstComponent Java class using HstResponse#sendRedirect(...) or HstResponseUtils#sendRedirect(...). However, handling all edge cases—such as development environments, hosts without SSL certificates (hst:schemeagnostic = true), or Experience manager requests—can be complex and inefficient. Redirects in components may also occur after other components have already executed, reducing efficiency.

To address these challenges, HST provides the AbstractHttpsSchemeValve class. This valve covers common edge cases and requires you to implement a single method:

public abstract boolean requiresHttps(ValveContext context);
copy

The HST framework will only call requiresHttps when a redirect to HTTPS is possible. If a redirect cannot be honored due to configuration or context, the method is not invoked.

Example: Custom HTTPS Scheme Valve

Suppose you want to enforce HTTPS for documents with the myproject:secure mixin. Implement the valve as follows:

public class HttpsSchemeValve extends AbstractHttpsSchemeValve {
    @Override
    public boolean requiresHttps(final ValveContext context) {
        final HippoBean contentBean = context.getRequestContext()
                                     .getContentBean();
        if (contentBean == null ) {
            return false;
        }
        try {
            return contentBean.getNode().isNodeType("myproject:secure");
        } catch (RepositoryException e) {
            throw new RuntimeRepositoryException(e);
        }
    }
}
copy

Injecting the Custom Valve into the Pipeline

To activate your custom valve, add it to the HST pipeline using Spring configuration. The preferred location is after the initializationValve and before the aggregationValve. Place the configuration file as shown:

site/
  components/
    src/
      main/
        resources/
          META-INF/
            hst-assembly/
              overrides/

Create a file named httpsScheme-valve.xml with the following content:

<beans xmlns="http://www.springframework.org/schema/beans"
       xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
       xsi:schemaLocation="http://www.springframework.org/schema/beans
       http://www.springframework.org/schema/beans/spring-beans-3.0.xsd">

  <bean id="httpsSchemeValve" class="com.example.hst.container.HttpsSchemeValve">
    <property name="valveName" value="httpsSchemeExampleValve" />
    <property name="afterValves" value="initializationValve"/>
    <property name="beforeValves" value="cmsSecurityValve"/>
  </bean>

  <bean class="org.springframework.beans.factory.config.MethodInvokingFactoryBean">
    <property name="targetObject">
      <bean class="org.springframework.beans.factory.config.MethodInvokingFactoryBean">
        <property name="targetObject" ref="org.hippoecm.hst.core.container.Pipelines" />
        <property name="targetMethod" value="getPipeline"/>
        <property name="arguments">
          <value>DefaultSitePipeline</value>
        </property>
      </bean>
    </property>
    <property name="targetMethod" value="addInitializationValve"/>
    <property name="arguments">
      <ref bean="httpsSchemeValve" />
    </property>
  </bean>
</beans>
copy

This configuration injects your HttpsSchemeValve into the DefaultSitePipeline after the initializationValve.

Verification: Example Scenario

You can verify your custom HTTPS support using the testsuite project.

Prerequisites

• Configure Apache HTTP Server as a reverse proxy. See Configure Apache HTTP Server as Reverse Proxy for Bloomreach Content.
• Update your hosts file (for example, /etc/hosts on Ubuntu):

127.0.0.1 cms.example.com
127.0.0.1 www.example.com 

Steps

1. Start the testsuite project.
2. In the CMS console, navigate to
   http://localhost:8080/cms/console/?path=/content/documents/demosite/common/about-us.
3. Add the mixin testsuite:secure to the "about-us" document.
4. Ensure the www.example.com host is configured as follows:

/hst:hst:
  /hst:hosts:
    /example-env:
      hst:defaultport: 80
      /com:
        hst:showcontextpath: false
        hst:showport: false
        /example:
          /www:
            /hst:root:
            hst:mountpoint: /hst:hst/hst:sites/myproject
copy

Expected Behavior

1. Visit http://localhost:8080/site/about

   • No redirect to HTTPS should occur.
   • Reason: The host at /hst:hst/hst:hosts/dev-localhost/localhost has hst:schemeagnostic = true.

2. Visit http://www.example.com/about

   • A redirect loop occurs.
   • Reason: The custom HttpsSchemeExampleValve attempts to redirect to HTTPS, but the HST container redirects back to HTTP because the sitemap item scheme is http.

3. Set hst:customhttpssupport = true at /hst:hst/hst:hosts/example-env/com

   • Visit http://www.example.com/about. You should be redirected to https://www.example.com/about.
   • Reason: With hst:customhttpssupport = true, HTTPS requests are allowed even if the sitemap item specifies HTTP.

4. On https://www.example.com/about

   • All other menu links should be fully qualified and start with http://.

5. On https://www.example.com/about

   • All resources (CSS, JS) should be loaded over HTTPS.

6. Experience manager compatibility

   • The Experience manager should function correctly, regardless of hst:schemeagnostic = true for both localhost and cms.example.com.

Summary

Custom HTTPS support in HST allows you to enforce HTTPS based on domain-specific requirements. Use the AbstractHttpsSchemeValve to centralize your logic and handle edge cases efficiently. Always set hst:customhttpssupport = true on the relevant host to avoid redirect conflicts. Validate your implementation using the provided steps to ensure correct behavior across different environments.