Configuring TotalFlow BatchBuilder to use the HTTPS protocol

TotalFlow BatchBuilder provides support for using the HTTPS security protocol. The HTTPS protocol facilitates secure network communication by establishing an encrypted link between the server and the web browser user interface and ensures the privacy and integrity of all transmitted data.

This is the procedure for enabling HTTPS on Windows 10. There might be minor differences in other versions of Windows.

To enable HTTPS, you need a digital certificate. You can use a certificate signed by a certificate authority (CA) or a self-signed certificate.

    Important:
  • This procedure uses the Java keytool command. For details about using keytool, see the Java documentation or the documentation provided by the certificate authority.
  • If you changed the default installation path, make sure that you replace C:\Program Files\RICOH\TotalFlow BatchBuilder\ with the path where TotalFlow BatchBuilder is installed everywhere in the procedure.
  • Save copies of these files in a safe location in case you need to restore them in the future:
    • C:\Program Files\RICOH\TotalFlow BatchBuilder\apache-tomcat\conf\server.xml
    • C:\Program Files\RICOH\TotalFlow BatchBuilder\apache-tomcat\conf\web.xml
    • C:\Program Files\RICOH\TotalFlow BatchBuilder\conf.properties
  1. Obtain the digital certificate and store it on the computer where TotalFlow BatchBuilder is installed.
    • To use a certificate signed by a certificate authority, follow the instructions provided by the certificate authority for obtaining a signed certificate and importing it into a keystore file.
    • To create a self-signed certificate:
      1. On the computer where TotalFlow BatchBuilder is installed, open a Command Prompt window as an administrator.
      2. Generate a local keystore file and a self-signed certificate using this command:
        • "C:\Program Files\RICOH\TotalFlow BatchBuilder\jre\bin\keytool" -genkey -keyalg RSA -alias selfsigned -keystore "C:\Program Files\RICOH\TotalFlow BatchBuilder\keystore.jks" -storepass password -validity certificate_validity -keysize 2048 -ext san=dns:localhost

        Replace password with the password that you want to set for the keystore file.

        Replace certificate_validity with the number of valid days for the certificate. For example, enter 90 for 90 days.

        For the Java certificate to acknowledge non-HTTPS components, add the necessary information to the "-ext san: ..." parameter. For example:

        • Variants for localhost covering home address for IPv4 and IPv6: ip:127.0.0.1,ip:::1
        • Variants for host name: dns:USER
        • IPv4 and/or IPv6 addresses of the computer using the IP format: ip:User_IPv4,User_IPv6

      3. Export and import the generated keystore file into the Java security certificate by running these two commands:
        • "C:\Program Files\RICOH\TotalFlow BatchBuilder\jre\bin\keytool" -export -alias selfsigned -keystore "C:\Program Files\RICOH\TotalFlow BatchBuilder\keystore.jks" -storepass password -file "C:\Program Files\RICOH\TotalFlow BatchBuilder\selfsigned.crt"

          Replace password with the password that you set for the keystore file.

        • "C:\Program Files\RICOH\TotalFlow BatchBuilder\jre\bin\keytool" -import -alias selfsigned -keystore "C:\Program Files\RICOH\TotalFlow BatchBuilder\jre\lib\security\cacerts" -storepass "changeit" -file "C:\Program Files\RICOH\TotalFlow BatchBuilder\selfsigned.crt"
  2. Configure the XML and .properties files.
    1. Modify the C:\Program Files\RICOH\TotalFlow BatchBuilder\apache-tomcat\conf\server.xml file as follows:
      1. Change the lines 
        <Connector port="19080"
URIEncoding="UTF-8"
protocol="HTTP/1.1"
connectionTimeout="20000"
redirectPort="8443"
maxParameterCount="1000"/>
        into 
        <Connector port="19080"
URIEncoding="UTF-8"
protocol="HTTP/1.1"
connectionTimeout="20000"
redirectPort="19443"/>
      2. Add the following section after the paragraph modified in the previous step: 
        <Connector port="19443"
protocol="HTTP/1.1"
SSLEnabled="true"
enableLookups="true"
maxThreads="150"
scheme="https"
secure="true"
keystoreFile="LOCATION_OF_KEYSTORE_FILE"
keystorePass="KEYSTORE_PASSWORD"
clientAuth="false"
sslProtocol="TLS"
sslEnabledProtocols="TLSv1.2"/>

      Replace LOCATION_OF_KEYSTORE_FILE with the path for the keystore file and KEYSTORE_PASSWORD with the password that you set for the keystore file.

    2. Modify the C:\Program Files\RICOH\TotalFlow BatchBuilder\apache-tomcat\conf\web.xml file as follows:
      Add the following section before </web-app> (which is at the end of the file): 
      <security-constraint>
		<web-resource-collection>
		<web-resource-name>Secured</web-resource-name>
		<url-pattern>/*</url-pattern>
		</web-resource-collection>

		<user-data-constraint>
		<transport-guarantee>CONFIDENTIAL</transport-guarantee>
		</user-data-constraint>
</security-constraint>
    3. Modify the C:\Program Files\RICOH\TotalFlow BatchBuilder\conf.properties file as follows:
      1. replace http with https
      2. replace 19080 with 19443
  3. Restart the TotalFlow BatchBuilder service.
  4. Verify that requests are forwarded to the secure connection:
    1. Open a supported web browser window.
    2. Clear the web browser cache.
    3. Enter this URL in the address bar:

      http://server_address:port_number/BatchBuilder

      where server_address is the host name or the IP address of the computer whereTotalFlow BatchBuilder is installed and port_number is the web service port.

      When the page loads, the address should change to https://server_address:19443/BatchBuilder.

When users access the system, they are redirected to the secure protocol without having to take any action themselves.

However, if you use a self-signed certificate or if the certificate is not specifically tied to the server, the web browser displays a warning that the certificate is not trusted. To solve the issue, you can import the certificate to the trusted certificate storage of Windows:

  1. Go to the TotalFlow BatchBuilder installation folder.
  2. Right-click the certificate and select Install Certificate.

    The Certificate Import Wizard starts.

  3. On the Welcome to the Certificate Import Wizard screen, click Next.
  4. On the Certificate Store screen, select the Place all certificates in the following store option and click Browse.
  5. In the Select Certificate Store dialog, select the Trusted Root Certification Authorities store and click OK.
  6. Click Next.
  7. On the Completing the Certificate Import Wizard screen, click Finish.

Make sure that you repeat the procedure for enabling HTTPS whenever the certificate is about to expire.

After you repair TotalFlow BatchBuilder, if you no longer want to enable HTTPS, you must change the internal server address back to HTTP:

  1. Go to C:\Program Files\RICOH\TotalFlow BatchBuilder and edit the conf.properties file as an administrator.
  2. Replace the line "web.address": "https://server_address:19443/BatchBuilder" with "webAddress": "http://server_address:19080/BatchBuilder".
  3. Save and close the file.
  4. Restart the TotalFlow BatchBuilder service.
  5. Clear the web browser cache.

Note: When TotalFlow BatchBuilder is used together with another product, some functions, such as status tracking, might not work and would require to either have a valid CA approved certificate for both products or to import the certificate files of the products inside their respective "cacerts" files if they both use HTTPS.
Parent topic: Security