Configuring FME Flow for HTTPS: Using a Key File and .CER Certificate

Introduction

Follow these step-by-step instructions to configure your FME Flow (formerly FME Server) for HTTPS using a Keyfile and Certificate obtained from a Certificate Authority (CA). If the certificate you have obtained uses the .pfx extension, follow the Using a PFX or P12 certificate instructions instead.

FME Flow 2022.0 Linux
As of 2022.0, Linux FME Flows now include Nginx as a reverse proxy. This makes SSL configuration easier to manage. Please follow the documentation for the steps. If you have an older installation, please follow the Windows steps below. 

Key References

• <FMEFlowDir> refers to the location of the FME Flow installation folder, specified during installation. By default, this is C:\Program Files\FMEFlow on a Windows machine and /opt/fmeflow on a Linux machine.
• <FMESharedResourceDir> refers to the location of the FME Flow System Share, specified during installation. By default, this is C:\ProgramData\Safe Software\FME Flow on a Windows machine and /opt/fmeflow on a Linux machine.

Step-by-step Instructions 

Note: The following steps are not needed if you already have the key file and .cer file

1. Create a Keystore Generation Script

Open a text editor and copy the example script below.  Replace the italicised text highlighted in red with your own values, note, the storepass and keypass must be the same and at least 6 characters. For more information on the keytool arguments please see Appendix A at the bottom of this article. Please make sure that the CN value ["fmeflow.example.org" in the example below ] is also added as one of the san values [i.e. dns:fmeflow.example.org].

keytool -genkey -noprompt -keyalg RSA -keystore tomcat.keystore -alias tomcat -dname "CN=fmeflow.example.org, OU=support, O=SafeSoftware, L=Surrey, S=BC, C=CA" -storepass password1 -keypass password1 -ext san="dns:fmeflow.example.org,dns:fmeflow" -deststoretype pkcs12

2. Run Keystore Generation Script

Open the command prompt as administrator and navigate to the FME Flow installation Java bin directory:

cd \Utilities\jre\bin\ 

Execute the command you have created in step 1.

<FMEFlowDir> refers to the location of the FME Flow installation folder, specified during installation.

3. Generate a Certificate Signing Request (CSR)

In command prompt remain in <FMEFlowDir>\Utilities\jre\bin\ and run

keytool -certreq -keyalg RSA -alias tomcat -file certreq.csr -keystore tomcat.keystore -ext san="dns:fmeflow.example.org,dns:fmeflow"

Specify the certificate signing request path and filename and update the alias and san values to match that set in step 1.

4. Obtain a Certificate

According to your CA's instructions, submit the CSR (certreq.scr) generated in step 3 to obtain a certificate.

5. Import the Keystore into FME Flows Trusted Certs

In command prompt (from <FMEFlowDir>\Utilities\jre\bin\) import the keystore into FME’s trusted certs. Using the following command, first replace the srcstorepass argument with the password from step 1.

keytool -importkeystore -noprompt -srckeystore tomcat.keystore -destkeystore "\Utilities\jre\lib\security\cacerts" -deststorepass changeit -srcstorepass password1

Ignore the warning. The destination type needs to default to jks. Distributed Web Applications such as Tomcat typically use a different Java installation than FME and the cacerts file within that Java must be used instead of the FME Flow Java. 

6. Make a Backup of the Tomcat XML Configuration Files

Go to <FMEFlowDir>\Utilities\tomcat\conf and make backups of server.xml, web.xml, and context.xml. This is recommended so that you can easily revert the configuration at any point if necessary.

7. Configure Server.xml

Run a text editor as an administrator and open server.xml, located in: <FMEFlowDir>\Utilities\tomcat\conf

Locate the SSLEngine setting in the <Listener> element, including className="org.apache.catalina.core.AprLifecycleListener" and verify the value is "off".

Locate the <Connector> element that contains:

protocol="org.apache.coyote.http11.Http11NioProtocol"

and replace the entire element with:

<Connector protocol="org.apache.coyote.http11.Http11NioProtocol" 
port="443" 
minSpareThreads="5" 
enableLookups="true" 
disableUploadTimeout="true" 
acceptCount="100" 
maxThreads="200" 
maxHttpHeaderSize="16384" 
maxParameterCount="1000" 
scheme="https" 
secure="true"
SSLEnabled="true"
SSLCertificateFile="<FMEFlowDir>\<certificateFileName.cer>"
SSLCertificateKeyFile=”<FMEFlowDir>\<certificateKeyFileName.key>"
clientAuth="false" sslEnabledProtocols="TLSv1.1,TLSv1.2" 
sslImplementationName="org.apache.tomcat.util.net.jsse.JSSEImplementation" 
ciphers="TLS_AES_256_GCM_SHA384,TLS_CHACHA20_POLY1305_SHA256,TLS_AES_128_GCM_SHA256,DHE-RSA-AES256-GCM-SHA384,DHE-RSA-AES128-GCM-SHA256,ECDHE-RSA-AES256-GCM-SHA384,ECDHE-RSA-AES128-GCM-SHA256,DHE-RSA-AES256-SHA256,DHE-RSA-AES128-SHA256,ECDHE-RSA-AES256-SHA384,ECDHE-RSA-AES128-SHA256,ECDHE-RSA-AES256-SHA,ECDHE-RSA-AES128-SHA,DHE-RSA-AES256-SHA,DHE-RSA-AES128-SHA" 
URIEncoding="UTF8" />

<Connector port="80" protocol="HTTP/1.1" redirectPort="443"/>

Make sure to update the SSLCertificateFile and SSLCertificateKeyFile parameters to that of the keystore location and password set to that of step 1, similar to this server.xml reference.

Note: If the password contains invalid XML characters, these should be replaced with escape characters.

TLS 1.1 can be disabled by removing the reference from sslEnabledProtocols.

The list of ciphers is not exhaustive. If your certificate was generated with a different algorithm, it must be added. Any algorithms not in use can also be safely removed from this list. For a full list of ciphers supported by Tomcat, see Cipher (Apache Tomcat 9.0.69 API Documentation).

(Optional) To change the port for HTTPS communication, change 443 to the desired port, for both the port and redirectPort directives.

Save and close the server.xml file.

8. Configure web.xml

Open web.xml, located in <FMEFlowDir>\Utilities\tomcat\conf.

Add the following code block to the end of the file, just before the closing </web-app> element:

<security-constraint>
<web-resource-collection>
<web-resource-name>HTTPSOnly</web-resource-name>
<url-pattern>/*</url-pattern>
</web-resource-collection>
<user-data-constraint>
<transport-guarantee>CONFIDENTIAL</transport-guarantee>
</user-data-constraint>
</security-constraint>

Save and close the web.xml file.

9. Configure context.xml

Open context.xml, located in <FMEFlowDir>\Utilities\tomcat\conf.

Add the following to the end of the file, just before the closing </context> element:

<Valve className="org.apache.catalina.authenticator.SSLAuthenticator" disableProxyCaching="false" />

Save and close the context.xml file.

10. Update the FME Flow Web URL to Use HTTPS

Run a text editor as an administrator and open fmeServerConfig.txt, located at <FMEFlowDir>\Server\.

Update the FME_SERVER_WEB_URL directive by changing http to https and change the port to the same one specified in step 7. Please ensure that the Fully Qualified Domain Name [FQDN] of the host is provided in the FME_SERVER_WEB_URL directive.

Save and close the file.

11. Verify HTTPS Configuration

Restart FME Flow Application Server Service.

Note: If a 1067 error pops up when attempting to start the service, it is likely that the configuration files contain incorrect XML syntax, including invalid characters, in the password. 

Open a browser and navigate to https://localhost/. If you configured Tomcat to use a port other than the standard port 443, also specify the port (https://localhost:<port>).

You should see the FME Flow login page in a secure format.
 

12. Modify Service URLs to Use HTTPS

To be able to submit jobs on FME Flow via HTTPS, you must enable SSL for a service.

In the FME Flow Web User Interface, open the Services page under Admin > System Configuration> Network & Email

Click "Change All Hosts" and in the URL Pattern field, change HTTP to HTTPS. FME Flow may have picked up this change, in which case select OK. If required, also modify the port number. Typically, SSL is configured on either port 8443 or 443.

Run a Sample workspace with Data download and Job Submitter services to confirm your FME Flow is working with HTTPS.

Your FME Flow is now configured to work via HTTPS. However, if you are using Websockets or SSO, some additional steps are required.

Optional: The following steps are only applicable if you want to use the WebSocket Server or want to use the legacy Topic Monitoring.

13. Enable SSL on the WebSocket Server

Run a text editor as an administrator and open the fmeWebSocketConfig.txt, located in <FMEFlowDir>\Server\.

Set WEBSOCKET_ENABLE_SSL=true

Uncomment the WEBSOCKET_KEYSTORE_FILE_PATH directive and set it to reference the keystore file you have set in the Server.xml in step 7, however, this time use forward slashes.

Uncomment the WEBSOCKET_KEYSTORE_FILE_PASSWORD directive and set it to use the keystore file password you have set in the server.xml in step 7.

For example:

WEBSOCKET_ENABLE_SSL=true
WEBSOCKET_KEYSTORE_FILE_PATH=>FMEFlowDir</Utilities/tomcat/tomcat.keystore 
WEBSOCKET_KEYSTORE_FILE_PASSWORD=password1

a. Do not enclose the password or path in quotes.
b. The slashes need to be forward slashes and may be the opposite of your Server.xml path. 

14. Enable SSL on the Websocket Subscriber and Publisher

Repeat step 10 in the following files,  specifying the same settings for the WEBSOCKET_ENABLE_SSL, WEBSOCKET_KEYSTORE_FILE_PATH, and WEBSOCKET_KEYSTORE_FILE_PASSWORD directives:

• <FMEFlowDir>\Server\config\subscribers\websocket.properties

• <FMEFlowDir>\Server\config\publishers\websocket.properties

15. Update the WebSocket Protocol 

In the following files, update the protocol in the value property of the PROPERTY directive from "ws:" to "wss:"

• <FMESharedResourceDir>\localization\publishers\websocket\publisherProperties.xml

• <FMESharedResourceDir>\localization\subscribers\websocket\subscriberProperties.xml

 <FMESharedResourceDir> refers to the location of the FME Flow System Share, specified during installation.

16. Apply the Changes to the Publisher and Subscriber and Verify Configuration

Run the following .bat files, located in <FMEFlowDir>\Clients\utilities:

• addPublishers.bat

• addSubscribers.bat

Restart FME Flow to apply the changes made in steps 13-16.  

Test the configuration is complete by running jobs and viewing Topic Monitoring.   

Optional: The following steps only apply if you want to use the Single-Sign-On to access the FME Flow Web Interface.

 17. Update the SSO Authentication URL to Use HTTPS

Run a text editor as an administrator and open the propertiesFile.properties, located in <FMEFlowDir>\Utilities\tomcat\webapps\fmeserver\WEB-INF\conf\

Locate the SINGLE_SIGN_ON_AUTH_URL parameter, and update the URL's host name and port portion to match the host name through which the FME Flow Web User Interface is accessed.

For example:

<MyFMEFlowHost>:443/fmetoken/sso/generate

 Appendix A

Keytool arguments used to generate a keystore.

Troubleshooting

If you are experiencing issues please consult our FME Flow and HTTPS troubleshooting Guide, if this does not resolve your problem then contact Safe Software Support.