Sitemap/Mount level HTTPS support

Before we introduced seamless http/https support, the HST used to be scheme agnostic: It did not matter whether a request was over http or https. The HST would just serve the response regardless its scheme. Making sure some requests were only available over https was typically done by adding a servlet filter before the HST filter. See for example the forge httpsfilter. However, this led to client side redirects from http to https and from http to https whenever a request was done with the wrong scheme.

For complete integrated cross http/ https support in the HST we require:

  1. Support configuration on host, mount or sitemapitem level to mark it as http, https, or scheme agnostic
  2. Support of http / https URLs in a single html page out-of-the-box
  3. Support configurable response code (e.g. 301, 302, 403, 404, etc) when a request with the wrong scheme hits the application

With the introduction of seamless https support in the HST, the above features are covered, and more.

If you have configured SSL support on container (tomcat) level, from now on, you either have to set on the hst:host the default scheme 'hst:scheme = https' or you have to configure the host to be scheme agnostic with 'hst:schemeagnostic = true'

Support configuration on host, mount or sitemapitem level to mark it as http, https, or scheme agnostic

Per hst:virtualhost, hst:mount and/or hst:sitemapitem you can configure the properties

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

On hst:virtualhosts you can configure hst:scheme and hst:schemenotmatchresponsecode as well, but not hst:schemeagnostic.

Values are inherited from ancestor items if not configured explicitly. For example, a hst:sitemapitem that does not have property hst:scheme inherits it from its parent sitemapitem or from the mount.

Defaults on hst:virtualhosts are:

hst:scheme: http
hst:schemenotmatchresponsecode: 301

Default on hst:virtualhost is:

hst:schemeagnostic: false 

Marking a hst:mount with hst:scheme = https, and assuming you do not override hst:scheme in a sitemapitem, results in the entire channel being set to be accessed over https. A request for that channel over http results in a permanent redirect ( 301) to https, assuming you did not set hst:schemenotmatchresponsecode to some other value.

If your site is in general accessed over http, but only for example the contact page should be accessed over https, you mark only the sitemapitem for contact to have hst:scheme = https.

Usage of hst:schemeagnostic


  1. When some of your URLs on production must be over https, but you also want to be able to access the production site via some internal host for which you do not have a SSL certificate, you can mark that internal host with hst:schemeagnostic = true. When hst:schemeagnostic is set to true, the scheme of the request does not matter, even if the sitemapitem that matches is marked with hst:scheme = https
  2. When for some sitemapitem it does not matter whether the request is over http or https, you can mark that item as hst:schemeagnostic = true. For example, binaries on an HTML page should always be fetched over the same scheme as the HTML page was fetched. If these binaries are served via some sitemapitem, this sitemapitem should be marked with hst:schemeagnostic = true.

Support Strict-Transport-Security

If you have configured on host or mount level that the channel must be accessed over https, then most likely the entire website must be accessed over https. In that case, you might want Strict-Transport-Security response header to be set as well. You can achieve this easily by setting on the hst:virtualhost or hst:mount the following property:

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

the hst:reponseheaders is a multi-valued property. If it already exists on the hst:virtualhost or hst:mount, add the above. The max-age can of course be set to an appropriate value for your site.

Support http / https URLs in a single html page out-of-the-box

When visiting some page, say 

then all links on that page that result in a page that would match a hst sitemapitem that is marked with hst:scheme = https, will automatically be fully qualified links and start with https.

If vice versa, you are visiting 

then all links on that page that result in a page that would match a hst sitemapitem that is marked with hst:scheme = http ( http is default when missing), will automatically be fully qualified links and start with http.

Cross http/ https links are supported seamlessly, and also work for cross host / channel links

Support configurable response code when the request has the wrong scheme

Assume you hit the application with the following request 

and assume you want this contact page is accessed over https because it contains a form. The sitemapitem belonging to contact thus has the property:

hst:scheme: https

Accessing the URL (not https) then results in a HttpServletResponse.SC_MOVED_PERMANENTLY ( 301) , which is a permanent redirect to 

Note the http s in the URL above.

If you do not want a 301, but for example a 302 (temporary redirect) or a 403 (forbidden), 404 (not found) etc, you can to the sitemapitem (or hst:mount or hst:virtualhost) also set for example:

hst:schemenotmatchresponsecode: 403

The property hst:schemenotmatchresponsecode can be used to indicate what the HST should do if the scheme of the request does not match the scheme of the sitemapitem that matches. With the configuration above, then instead of a redirect to https, you'll get a HttpServletResponse.SC_FORBIDDEN.

The following hst:schemenotmatchresponsecode values are supported:


  1. 200 ( HttpServletResponse.SC_OK) : request continues as if scheme was matching
  2. 301 ( HttpServletResponse.SC_MOVED_PERMANENTLY) : Permanent client side redirect.
  3. 302 | 303 | 307 ( HttpServletResponse.SC_MOVED_TEMPORARILY | HttpServletResponse.SC_SEE_OTHER | HttpServletResponse.SC_TEMPORARY_REDIRECT) : Temporary redirect
  4. 403 ( HttpServletResponse.SC_FORBIDDEN) : Error page forbidden returned
  5. 404 ( HttpServletResponse.SC_NOT_FOUND) : Error page not found returned

Web Server / Reverse Proxy

Make sure to configure Apache HTTP Server properly.

You may have to add a mapping such as the following to your hosts file: 
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?