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:
- Support configuration on host, mount or sitemapitem level to mark it as http, https, or scheme agnostic
- Support of http / https URLs in a single html page out-of-the-box
- 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.
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
- hst:scheme ( String, supported values " http" and " https")
- hst:schemenotmatchresponsecode ( Long, supported values 200,301,302,303,307,403,404)
- 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:
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
- 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
- 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.
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.
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:
Accessing the URL http://www.example.org/contact (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:
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:
- 200 ( HttpServletResponse.SC_OK) : request continues as if scheme was matching
- 301 ( HttpServletResponse.SC_MOVED_PERMANENTLY) : Permanent client side redirect.
- 302 | 303 | 307 ( HttpServletResponse.SC_MOVED_TEMPORARILY | HttpServletResponse.SC_SEE_OTHER | HttpServletResponse.SC_TEMPORARY_REDIRECT) : Temporary redirect
- 403 ( HttpServletResponse.SC_FORBIDDEN) : Error page forbidden returned
- 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:
127.0.0.1 cms.example.com 127.0.0.1 www.example.com