Switch Keep Between HTTP and HTTPS

To help improve security, HTTPS support is enabled by default when installing Keep, and you can provide custom HTTPS certificates for the server to use.  As a result, HTTPS support is ready with minimal configuration required.

However, HTTP connectivity is also enabled, so after Keep is installed, it can be used over both HTTP and HTTPS. This enables you to test the application using either protocol and facilitates the upgrade of legacy integrations that are still using HTTP (if applicable).

We recommend that you disable or restrict access to Keep via HTTP as soon as possible. To help you do this, we have provided a command-line tool that can modify the application configuration. This page describes how to use this tool.

Configuration Tool

The http-mode-switcher.jar configuration tool is in the tools directory of the Keep installation location.

For example: C:\Program Files\Formpipe Software\Lasernet Keep\Server_<Keep version number> - [<node name>]\tools. Appropriately substitute <Keep version number> and <node name>.

Wrapper scripts are provided to make usage easier; use these wrapper scripts to run the tool. Depending on the platform that Keep is running on, run httpModeSwitcher.bat or httpModeSwitcher.sh.

Open a command prompt in the tools directory and run the relevant script. The tool will print usage documentation to screen, which you can refer to for the most accurate and up-to-date usage details.

Example

> httpModeSwitcher.bat

Usage: <cmd> <path/to/ear/file.ear> 

<cmd> may be:

  - http-and-https: Enable both HTTP and HTTPS access

  - require-https: Require HTTPS, this allows for HTTP->HTTPS redirects, or HTTPS-only if disabling the HTTPS redirect on the listener.

  - require-https-only: Require HTTPS only, this enforces the use of HTTPS via the HSTS header.

 The original .ear file will have the '.bak' extension added and be replaced with the modified version.

As indicated, the tool takes a cmd parameter and a path to the Keep .ear file. When the tool is run, the target .ear file is renamed to have a .bak extension, and a new copy of the .ear file with the requested changes applied to it takes its place.

For example, running the following command results in two files:

> httpModeSwitcher.bat http-and-https "C:\Program Files\Formpipe Software\Lasernet Keep\Server_11.0 - Production\wildfly-22.0.1.Final\standalone\deployments\pdm_app_module.ear"

• The original file renamed as a .bak file: C:\Program Files\Formpipe Software\Lasernet Keep\Server_11.0 - Production\wildfly-22.0.1.Final\standalone\deployments\pdm_app_module.ear.bak

• The newly-modified version ready for use: C:\Program Files\Formpipe Software\Lasernet Keep\Server_11.0 - Production\wildfly-22.0.1.Final\standalone\deployments\pdm_app_module.ear

We recommend either leaving the .bak version in place or moving it to a safe location. If problems occur in the future, you can restore this backup .ear file to undo any HTTP/HTTPS configuration changes.

Restart Keep After Running the Configuration Tool

After you run the cmd command and update the .ear file, you must restart the Keep server to apply your changes.

cmd Parameter Values

This section describes the valid values for the <cmd> parameter.

http-and-https

This restores the default configuration, which enables HTTP and HTTPS access. Use this option if you want to restore HTTP access after using one of the other <cmd> options.

require-https

This changes the application to require HTTPS. As a result, by default, an attempt to access the application over HTTP will cause a redirect that switches the user across to HTTPS instead. Both HTTP and HTTPS are enabled for connection, but connecting on HTTP will redirect to HTTPS.

We recommend this configuration for production environments, and when application installation has been verified and HTTPS certificates have been installed as required.

Additionally, it is possible to remove the redirect configuration from the application server, if required. In this scenario, connection attempts to HTTP will fail instead of being redirected.

require-https-only

This does the same as require-https, but additionally enables the HSTS (HTTPS Strict Transport Security) headers.

Warning

Only use this option if you understand the effect of doing so.

After HSTS headers are enabled and a user connects to the application, the browser will record that access should be via HTTPS only. Any further attempts to connect to the application via HTTP will cause the browser to change the protocol on the client side before sending the request.

This enhances security by forcing client-side protocol switching rather than relying on the redirect. However, note that if you then switch back to HTTP, the HSTS configuration will have to be manually cleared from the browser. Refer to vendor-specific documentation on how to do this.