Configuring FME Flow for HTTPS: Using a PFX or P12 Certificate

Introduction

Follow these step-by-step instructions to configure your FME Flow (formerly FME Server) for HTTPS using a wildcard certificate or a .pfx / .p12 certificate obtained from a Certificate Authority (CA). If you do not have a certificate yet follow the Using a CA 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. 

Video

Key References

<FMEFlowDir> refers to the location of the FME Flow installation folder, specified during installation. By default, this is C:\Program Files\FME Flow 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 

There are two methods for implementing a PFX certificate. The steps shared in this article involve directly referencing the PFX file as the Keystore. They are applicable to any version and are the method Safe Software Support would recommend. However, an alternative method may be found in older versions of the documentation. The steps shared in those versions involve generating a keystore file from the PFX certificate. While completing the configuration steps please make sure to follow only one set of instructions otherwise you may encounter errors during or after set-up.

1. 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. It's helpful to have a copy of these so that if you encounter a problem, it's easy to reverse the configuration until you can resolve it. 

2. Configure Server.xml

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

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

c. 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" maxParameterCount="1000" 

scheme="https" secure="true" SSLEnabled="true"

keystoreFile="<filePath>\<certificateName>.pfx"

keystorePass="<password>" keystoreType="PKCS12"

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"/>

We recommend storing your PFX certificate in FME Flow's tomcat directory <FMEFlowDir>\Utilities\tomcat\. Make sure the keystorePass is set to the password for your pfx certificate. 
Note: If the password contains invalid XML characters, these should be replaced with escape characters. 

Note: 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).

d. (Optional) To change the port for HTTPS communication, change 443 to the desired port, for both the port and redirectPort directives. If using a port other than the default port 443, you'll need to specify this port in the web URL when accessing FME Flow. 

e. Save and close the server.xml file.

3. Configure web.xml

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

b. 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>

c. Save and close the web.xml file.

4. Configure context.xml

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

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

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

c. Save and close the context.xml file.
 

5. Update the FME Flow Web URL to Use HTTPS

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

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

c. Save and close the file.

6. Export the certificate from the browser in base 64 format and import it into the cacerts trust store

Note: this step is only required if your certificate wasn't obtained from a Trusted Certificate Authority. For example, if your organization issued the certificate or you created your own self-signed certificate. If you receive the error 'There was an error submitting the job' when trying to run a workspace after completing the other steps in this article, please return and complete this step.

a. Restart the FME Flow Application Server service
Note: If there is a 1067 error when attempting to start the service likely the configuration files contain incorrect XML syntax, including invalid characters in the password. 

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

c. View the certificate from the browser. Note: Instructions were written for Chrome and may differ slightly if you use another browser.


d. Export as a Base64-encoded ASCII, single certificate (CRT) file to local disk (e.g. <certpath>\<certname>.crt)




e. Import the keystore into FME Flows trusted certs

In a command prompt, as an administrator, go to this location: <FMEFlowDir>\Utilities\jre\bin\. Import the keystore into FME’s trusted certs using the following command:

keytool -import -trustcacerts -keystore "<FMEFlowDir>\Utilities\jre\lib\security\cacerts" -storepass changeit -noprompt -alias <mycert> -file <certpath>\mycert.crt

Note: The alias argument in the command above is optional and may be removed from the command unless required by the certificate or other setup requirements. 

Note: 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. 

7. Verify HTTPS Configuration

a. Restart FME Flow.

b. Open a browser and navigate to your FME Flow's fully-qualified domain. For example, https://myfmeflow.com. Certificates are issued for a domain, so if you go to localhost (without providing a top-level domain like .com), then your browser will display a security warning. If you configured Tomcat to use a port other than the standard port 443, also specify the port (https://myfmeflow.com:<port>).

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

8. Modify Service URLs to Use HTTPS

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

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

b. 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.

c. 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.
 

9. Enable SSL on the WebSocket Server

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

b. Set WEBSOCKET_ENABLE_SSL=true

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

d. 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 2.

For example:

WEBSOCKET_ENABLE_SSL=true
WEBSOCKET_KEYSTORE_FILE_PATH=<filePath>/<certificateName>.pfx
WEBSOCKET_KEYSTORE_FILE_PASSWORD=<password>

Important Notes: 

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

10. Enable SSL on the Websocket Subscriber and Publisher

Repeat step 9 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

11. 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

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

12. Apply the changes to the Publisher and Subscriber and verify configuration

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

• addPublishers.bat

• addSubscribers.bat

b. Restart FME Flow to apply the changes made in steps 9-14.  

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

13. Update the SSO Authentication URL to use HTTPS

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

b. Locate the SINGLE_SIGN_ON_AUTH_URL parameter, and update the hostname and port portion of the URL to match the hostname through which the FME Flow Web User Interface is accessed.

For example:

SINGLE_SIGN_ON_AUTH_URL=https://<hostname>:<port>/fmetoken/sso/generate

Troubleshooting

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