Configuring for HTTPS

Note: The task described here should be undertaken by advanced users only. Before proceeding, consider your options for alternative solutions until you are certain you wish to proceed. For additional resources, consult the FME Community or FME Support.

  • Skill Level: Advanced
  • Estimated Time Required: 45-60 minutes
  • Prerequisites:
    • Test jobs and services to ensure FME Server is fully functional. For more information, see:

    • Familiarity with the Certificate Authority (CA) instructions from your certificate provider, particularly for generating the Certificate Signing Request (CSR).

    • (Recommended) Familiarity with your web application server's SSL configuration and certificates. (Apache Tomcat is the servlet for an Express or Fault-Tolerant installation of FME Server, and as an option with certain Distributed installations.)
    • (Recommended) Access to the person who generates your certificates.

Note: If using Microsoft IIS Application Request Routing (ARR), refer to this FME Community article.

Configuring for HTTPS

HTTPS ensures that communication between the client and server is encrypted, so that if it is intercepted, a third party cannot easily view or use the information. You can use HTTPS with FME Server to ensure that sensitive login information is not exposed.

The following are two supported methods for securing FME Server with HTTPS. For alternative methods, such as using a self-signed certificate, see Configuring FME Server for HTTPS in the FME Community.

Note: The following instructions provide steps for setting up SSL for Apache Tomcat, which is the application server included with an Express or Fault-Tolerant installation of FME Server, and as an option with certain Distributed installations. Instructions to set up SSL on different web application servers vary.

For more information about configuring Apache Tomcat for HTTPS, or if you are using a different version of Apache Tomcat, see the documention for your version on http://tomcat.apache.org/.

Using a CA-issued Certificate

This method requires you to generate a certificate signing request from FME Server, which your IT team can use to create a CA certificate with the .cer or .crt extensions. If the certificate uses the .pfx extension, follow Using a PFX or P12 Certificate (below) instead.

  1. Create a Keystore Generation Script

    2. Open a text editor and copy the example script below, replacing the argument values with your own.

    Note: The storepass and keypass arguments must be the same and at least 6 characters.

    keytool -genkey -noprompt -keyalg RSA -keystore tomcat.keystore -alias <alias> -dname "<dname>" -storepass <storepass> -keypass <keypass> -ext san="<san>" -deststoretype pkcs12

    Argument

    Description
    genkey The keytool program command to generate a new keystore.
    noprompt

    Using this argument in the command removes any interaction with the user.
    keyalg The algorithm to generate a private/public key pair.

    keystore

    		 The keystore file name.
    deststoretype Keystore type, pkcs12 or jks.
    dname The CN name, Organization Unit, Organization, Location (city), State, and two-letter country code. The distinguished name is a set of values used to create the certificate and should be entered as you would like them to be presented to FME Server users and visitors.
    storepass, keypass The password of the key and keystore. The value must be a minimum of six characters and must be the same for both arguments.
    ext san The subject alternative name is a structured way to indicate all of the domain names and IP addresses that are secured by the certificate.
    alias The name of the key inside the keystore being created.

    Example:

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

  2. Run the Keystore Generation Script
    1. Open a command prompt as administrator and navigate to the FME Server installation Java bin directory:

      2. cd <FMEServerDir>\Utilities\jre\bin\

      Where <FMEServerDir> is the location of the FME Server installation folder.

    2. Execute the command created in step 1.
  3. Generate a Certificate Signing Request (CSR)

    4. In the command prompt, remain in <FMEServerDir>\Utilities\jre\bin\ and run:

    keytool -certreq -keyalg RSA -alias <alias> -file <filename> -keystore tomcat.keystore -ext san="<san>"

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

    Example:

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

  4. Obtain a Certificate

    5. Submit the CSR (for example, certreq.csr) generated in step 3 to your CA to obtain a certificate, according to your CA's instructions.

  5. Import the Certificate into the Keystore

    6. If you have multiple certificates, install them in the following order, and be sure to update the alias and certificate path for each.

    1. Import the root certificate (if you have one):

      2. keytool -import -alias root -keystore tomcat.keystore -trustcacerts -file <path/certificate_filename>

    2. Import the intermediate certificate (If you have one):

      3. keytool -import -alias intermediate -keystore tomcat.keystore -trustcacerts -file <path/certificate_filename>

    3. Import the certificate:

      4. keytool -import -alias tomcat -keystore tomcat.keystore -trustcacerts -file <path/certificate_filename>

  6. Import the Keystore into FME Server's trusted certs

    7. In a command prompt, from <FMEServerDir>\Utilities\jre\bin\, use the following command to import the keystore into FME Server's trusted certs, specifying the srcstorepass argument with the password from step 1.

    keytool -importkeystore -noprompt -srckeystore tomcat.keystore -destkeystore "<FMEServerDir>\Utilities\jre\lib\security\cacerts" -deststorepass changeit -srcstorepass <password>

    Note: Ignore the warning that the destination type must default to jks.

  7. Back up the Tomcat XML Configuration Files

    8. Navigate to <FMEServerDir>\Utilities\tomcat\conf and make backups of server.xml, web.xml, and context.xml. We recommend this step so that you can easily revert the configuration at any point if necessary.

  8. Configure server.xml
    1. Run a text editor as an administrator and open server.xml, located in <FMEServerDir>\Utilities\tomcat\conf.
    2. Locate the SSLEngine setting in the <Listener> element, including className="org.apache.catalina.core.AprLifecycleListener" and change the "on" value to "off".
    3. Locate the <Connector> element that contains protocol="org.apache.coyote.http11.Http11NioProtocol" and replace the entire element with:

      4. Copy 
      <Connector protocol="org.apache.coyote.http11.Http11NioProtocol" 
      port="443" 
      minSpareThreads="5" 
      enableLookups="true" 
      disableUploadTimeout="true" 
      acceptCount="100" 
      maxThreads="200" 
      maxHttpHeaderSize="16384"
      scheme="https" 
      secure="true"
      SSLEnabled="true"
      keystoreFile="<file>"
      keystorePass="<password>"
      clientAuth="false" sslEnabledProtocols="TLSv1.1,TLSv1.2" 
      sslImplementationName="org.apache.tomcat.util.net.jsse.JSSEImplementation" 
      ciphers="TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256,TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA,TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA384,TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA,TLS_RSA_WITH_AES_128_GCM_SHA256,TLS_RSA_WITH_AES_256_GCM_SHA384,TLS_RSA_WITH_AES_128_CBC_SHA256,TLS_RSA_WITH_AES_256_CBC_SHA256,TLS_RSA_WITH_AES_128_CBC_SHA,TLS_RSA_WITH_AES_256_CBC_SHA,SSL_RSA_WITH_3DES_EDE_CBC_SHA" 
      URIEncoding="UTF8" />

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

      Make sure to update the keystoreFile and keystorePass parameters to the keystore location and password set in step 1. For an example, see this server.xml reference.

    4. (Optional) To change the port for HTTPS communication, change 443 to the desired port, for both the port and redirectPort directives.
    5. Save and close the server.xml file.
  9. Configure web.xml
    1. Open web.xml, located in <FMEServerDir>\Utilities\tomcat\conf.
    2. Add the following code block to the end of the file, just before the closing </web-app> element:

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

    3. Save and close the web.xml file.
  10. Configure context.xml
    1. Open context.xml, located in <FMEServerDir>\Utilities\tomcat\conf.
    2. Add the following to the end of the file, just before the closing </context> element:

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

    3. Save and close the context.xml file.
  11. Update the FME Server Web URL to Use HTTPS

    12. a. Run a text editor as an administrator and open fmeServerConfig.txt.

    b. Update the FME_SERVER_WEB_URL directive by changing http to https and change the port to the same one specified in step 8.

    c. Save and close the file.

  12. Verify the HTTPS Configuration
    1. Restart FME Server.
    2. Open a web 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>).
    3. You should see the FME Server login page in a secured format.
  13. Modify Service URLs to Use HTTPS

    14. To submit jobs on FME Server via HTTPS, you must enable SSL for the FME Server Web Services.

    1. In the FME Server Web User Interface, open the Services page.
    2. Click Change All Hosts and, in the URL Pattern field, change HTTP to HTTPS. (FME Server may have already set this change.) If required, modify the port number—typically SSL is configured on either port 8443 or 443. When finished, click OK.
    3. Run a sample workspace with the data download and job submitter services to confirm your FME Server is working with HTTPS.

    Your FME Server is now configured to work via HTTPS. However, if you are using the WebSocket Server or Integrated Windows Authentication, some additional steps are required.

  14. (Optional) Enable SSL on the WebSocket Server

    15. The FME Server WebSocket Server supports insecure (ws://) or secure connections (wss://). This configuration is only required if you want to use the WebSocket Server or Topic Monitoring (legacy).

    1. Run a text editor as an administrator and open the fmeWebSocketConfig.txt file in your FME Server installation directory (<FMEServerDir>\Server).
    2. Set WEBSOCKET_ENABLE_SSL=true.
    3. Uncomment the WEBSOCKET_KEYSTORE_FILE_PATH directive and set it to reference the keystore file set in server.xml in step 8. For example:

      4. WEBSOCKET_KEYSTORE_FILE_PATH=<FMEServerDir>/Utilities/tomcat/tomcat.keystore

      Note: Use forward slashes, which may be different from the path in server.xml.

    4. Uncomment the WEBSOCKET_KEYSTORE_FILE_PASSWORD directive and set it to reference the keystore file password set in server.xml in step 8. For example:

      5. WEBSOCKET_KEYSTORE_FILE_PASSWORD=password1

      Note: Do not enclose the password in quotes.

    5. Specify the same settings for the WEBSOCKET_ENABLE_SSL, WEBSOCKET_KEYSTORE_FILE_PATH, and WEBSOCKET_KEYSTORE_FILE_PASSWORD directives in the following files:
      • <FMEServerDir>\Server\config\subscribers\websocket.properties
      • <FMEServerDir>\Server\config\publishers\websocket.properties
    6. 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 Server System Share, specified during installation.

    7. Run the following .bat files, located in <FMEServerDir>\Clients\utilities:
      • addPublishers.bat
      • addSubscribers.bat
    8. Restart FME Server.
    9. To test that the configuration is complete, run jobs and view Topic Monitoring.
  15. (Optional) Update the SSO Authentication URL to use HTTPS

    16. Note: This step is applicable only if you want to use Integrated Windows Authentication (single sign-on) to access the FME Server Web Interface.

    1. Run a text editor as an administrator and open the fmeserver propertiesFile.properties, located in <FMEServerDir>\Utilities\tomcat\webapps\fmeserver\WEB-INF\conf\.
    2. Locate the SINGLE_SIGN_ON_AUTH_URL parameter, and update the host name and port portion of the URL to match the host name through which the FME Server Web User Interface is accessed.

      3. For example:

      SINGLE_SIGN_ON_AUTH_URL=https://<MyFMEServerHost>:443/fmetoken/sso/generate

Using a PFX or P12 Certificate

Use these instructions to configure your FME Server for HTTPS using a .pfx or .p12 certificate obtained from a Certificate Authority (CA). If you do not have a certificate, follow the instructions for Using a CA-issued Certificate (above) instead.

  1. Import your PFX keystore into the FME Server Keystore
    1. Open a command prompt as an administrator and navigate to the FME Server installation Java bin directory:

      2. cd <FMEServerDir>\Utilities\jre\bin\

      Note: <FMEServerDir> refers to the location of the FME Server installation folder, specified during installation.

    2. Run the following command to create a new keystore file to an updated PFX path and filename:

      3. keytool -importkeystore -srckeystore <certpath>\<certificate_name>.pfx -srcstoretype pkcs12 -destkeystore tomcat.keystore -deststoretype pkcs12

    3. You are prompted for the source and destination keystore password. These must be the passwords provided with the PFX, and must both be the same.
  2. Make a backup of the Tomcat XML configuration files

    3. Go to <FMEServerDir>\Utilities\tomcat\conf and make backups of server.xml, web.xml, and context.xml.

  3. Configure server.xml
    1. Run a text editor as an administrator and open server.xml, located in <FMEServerDir>\Utilities\tomcat\conf.
    2. Locate the SSLEngine setting in the <Listener> element, including className="org.apache.catalina.core.AprLifecycleListener" and change the "on" value to "off".
    3. Locate the <Connector> element that contains protocol="org.apache.coyote.http11.Http11NioProtocol" and replace the entire element with:

      4. Copy 
      <Connector protocol="org.apache.coyote.http11.Http11NioProtocol" 
      port="443" 
      minSpareThreads="5" 
      enableLookups="true" 
      disableUploadTimeout="true" 
      acceptCount="100" 
      maxThreads="200" 
      maxHttpHeaderSize="16384"
      scheme="https" 
      secure="true"
      SSLEnabled="true"
      keystoreFile="<file>"
      keystorePass="<password>"
      clientAuth="false" sslEnabledProtocols="TLSv1.1,TLSv1.2" 
      sslImplementationName="org.apache.tomcat.util.net.jsse.JSSEImplementation" 
      ciphers="TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256,TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA,TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA384,TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA,TLS_RSA_WITH_AES_128_GCM_SHA256,TLS_RSA_WITH_AES_256_GCM_SHA384,TLS_RSA_WITH_AES_128_CBC_SHA256,TLS_RSA_WITH_AES_256_CBC_SHA256,TLS_RSA_WITH_AES_128_CBC_SHA,TLS_RSA_WITH_AES_256_CBC_SHA,SSL_RSA_WITH_3DES_EDE_CBC_SHA" 
      URIEncoding="UTF8" />

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

      Make sure to update the keystoreFile and keystorePass parameters to the keystore location and password set in step 1. For an example, see this server.xml reference.

    4. (Optional) To change the port for HTTPS communication, change 443 to the desired port, for both the port and redirectPort directives.
    5. Save and close the server.xml file.
  4. Configure web.xml
    1. Open web.xml, located in <FMEServerDir>\Utilities\tomcat\conf.
    2. Add the following code block to the end of the file, just before the closing </web-app> element:

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

    3. Save and close the web.xml file.
  5. Configure context.xml
    1. Open context.xml, located in <FMEServerDir>\Utilities\tomcat\conf.
    2. Add the following to the end of the file, just before the closing </context> element:

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

    3. Save and close the context.xml file.
  6. Update the FME Server Web URL to Use HTTPS

    7. a. Run a text editor as an administrator and open fmeServerConfig.txt.

    b. Update the FME_SERVER_WEB_URL directive by changing http to https and change the port to the same one specified in step 3.

    c. Save and close the file.

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

    8. Note: Instructions may differ slightly in a browser other than Chrome.

    a. Restart the FME Server Application Server service

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

    c. View the certificate from the browser.

    d. Open Details and click Copy to File.

    e. Save as Base-64 encoded X.509 (CER) to local disk (for example, <certpath>\mycert.cer)

    f. Import the keystore into FME Server's trusted certs

    In a command prompt from <FMEServerDir>\Utilities\jre\bin\, use the following command to import the keystore into FME Server’s trusted certs:

    keytool -import -trustcacerts -keystore <FMEServerDir>\Utilities\jre\lib\security\cacerts -storepass changeit -noprompt -file <certpath>\mycert.cer

  8. Verify the HTTPS Configuration
    1. Restart FME Server.
    2. Open a web 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>).
    3. You should see the FME Server login page in a secured format.
  9. Modify Service URLs to Use HTTPS

    10. To submit jobs on FME Server via HTTPS, you must enable SSL for the FME Server Web Services.

    1. In the FME Server Web User Interface, open the Services page.
    2. Click Change All Hosts and, in the URL Pattern field, change HTTP to HTTPS. (FME Server may have already set this change.) If required, modify the port number—typically SSL is configured on either port 8443 or 443. When finished, click OK.
    3. Run a sample workspace with the data download and job submitter services to confirm your FME Server is working with HTTPS.

    Your FME Server is now configured to work via HTTPS. However, if you are using the WebSocket Server or Integrated Windows Authentication, some additional steps are required.

  10. (Optional) Enable SSL on the WebSocket Server

    11. The FME Server WebSocket Server supports insecure (ws://) or secure connections (wss://). This configuration is only required if you want to use the WebSocket Server or Topic Monitoring (legacy).

    1. Run a text editor as an administrator and open the fmeWebSocketConfig.txt file in your FME Server installation directory (<FMEServerDir>\Server).
    2. Set WEBSOCKET_ENABLE_SSL=true.
    3. Uncomment the WEBSOCKET_KEYSTORE_FILE_PATH directive and set it to reference the keystore file set in server.xml in step 3. For example:

      4. WEBSOCKET_KEYSTORE_FILE_PATH=<FMEServerDir>/Utilities/tomcat/tomcat.keystore

      Note: Use forward slashes, which may be different from the path in server.xml.

    4. Uncomment the WEBSOCKET_KEYSTORE_FILE_PASSWORD directive and set it to reference the keystore file password set in server.xml in step 3. For example:

      5. WEBSOCKET_KEYSTORE_FILE_PASSWORD=password1

      Note: Do not enclose the password in quotes.

    5. Specify the same settings for the WEBSOCKET_ENABLE_SSL, WEBSOCKET_KEYSTORE_FILE_PATH, and WEBSOCKET_KEYSTORE_FILE_PASSWORD directives in the following files:
      • <FMEServerDir>\Server\config\subscribers\websocket.properties
      • <FMEServerDir>\Server\config\publishers\websocket.properties
    6. 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 Server System Share, specified during installation.

    7. Run the following .bat files, located in <FMEServerDir>\Clients\utilities:
      • addPublishers.bat
      • addSubscribers.bat
    8. Restart FME Server.
    9. To test that the configuration is complete, run jobs and view Topic Monitoring.
  11. (Optional) Update the SSO Authentication URL to use HTTPS

    12. Note: This step is applicable only if you want to use Integrated Windows Authentication (single sign-on) to access the FME Server Web Interface.

    1. Run a text editor as an administrator and open the fmeserver propertiesFile.properties, located in <FMEServerDir>\Utilities\tomcat\webapps\fmeserver\WEB-INF\conf\.
    2. Locate the SINGLE_SIGN_ON_AUTH_URL parameter, and update the host name and port portion of the URL to match the host name through which the FME Server Web User Interface is accessed.

      3. For example:

      SINGLE_SIGN_ON_AUTH_URL=https://<MyFMEServerHost>:443/fmetoken/sso/generate

See Also