Secure Your Acrolinx URL With HTTPS

In a standard installation of Acrolinx, communication between the core server and the outside world is unencrypted. By "outside world" we mean people who connect to the core server with an Acrolinx Integration, or with a web browser.

Your core server has two separate URLs, each with a different port. The core server uses one of these URLs exclusively for internal communication (between your core server and language and analytics servers), and the other for public communication. This article tells you how to secure your public URL with HTTPS.

When Integrations connect to the core server through the public internet, you might choose to use HTTPS, the internet standard for secure web communication. HTTPS communication ensures that data and passwords are unreadable during transmission.

Generally, we recommend that you always configure a cipher whitelist and disable unused and insecure SSL protocols.

By the way, setting up HTTPS, especially generating the proper public key certificate, is best done by a security professional. Some of the configuration steps aren’t for the faint-hearted. In any event, the Acrolinx Support team is happy to assist you in securing your Acrolinx Server with HTTPS.

Acrolinx only supports certificates signed by a third-party certificate authority (CA). Self-signed certificates in any form aren't supported.

Here’s a checklist of what you'll need:

  1. Your certificate (.crt) file signed by a third-party certificate authority.
  2. The key (.key) file that belongs to your certificate.
  3. All related (chain) certificate files.
  4. OpenSSL installed to generate your Java keystore.

Once you have the .crt, .key, related certificate files, and you've installed OpenSSL, you can start. If you'd like help with the following steps, contact Acrolinx Support to schedule a web meeting.

Getting Started

To secure Acrolinx for HTTPS communication, you need to define the protocol and port that you use for secure communication. You also need to define the keystore and truststore details.

  1. Stop all your Acrolinx servers.
  2. Import your certificate into a Java keystore:

    a) Combine all certificate files (chain certificates) you received together with the <CERTIFICATE_NAME>.crt file into a new <CERTIFICATE_NEW_NAME>.crt file as follows:

    • Open your main <CERTIFICATE_NAME>.crt file and select Save As… to create a <CERTIFICATE_NEW_NAME>.crt file.
    • Open each chain certificate file, Select All, Copy and then paste into your <CERTIFICATE_NEW_NAME>.crt file directly underneath the existing -----END CERTIFICATE----- line.
    • Repeat for all chain certificates.

    Your certificate file should now look like this:

    b) Combine your <CERTIFICATE_NEW_NAME>.crt file and the <KEY_NAME>.key file into a single PKCS12 file - To do this, open a command-line shell and enter the following command:

    openssl pkcs12 -inkey <KEY_NAME>.key -in <CERTIFICATE_NAME>.crt -export -out combined.pkcs12

    c) Create a <PASSWORD> when asked, verify it when prompted and make a note of it.

    d) Copy the file combined.pkcs12 from wherever it was generated into the <INSTALL_DIR>/server/bin directory of your server.

    If you use a Windows server, you might enter a command that resembles this:

    copy  C:\files\combined.pkcs12 C:\Program Files\Acrolinx\AcrolinxIQ\server\bin

    If you use a Linux server, you might enter a command that resembles this:

    cp /Users/<USERNAME>/Documents/combined.pkcs12 /home/admin/Acrolinx/server/bin

    e) Navigate to your server's <INSTALL_DIR>/server/bin directory (the location to which you just copied your combined.pkcs12 file) and import the PKCS12 file into your Java keystore using the following command:

    Here's a Windows example:

    cd C:\Program Files\Acrolinx\AcrolinxIQ\server\bin
    keytool.exe -v -importkeystore -srckeystore combined.pkcs12 -srcstoretype PKCS12  -srcstorepass <PASSWORD> -destkeystore myKeystore -deststoretype JKS -deststorepass <KEYSTORE_PASSWORD> -destkeypass <KEYSTORE_PASSWORD>

    If keytool.exe isn't found, you'll need to state the path to it - this will depend where you have Java installed. For example:

    C:\Program Files\Java\jdk1.8.0_131\bin\keytool.exe -v -importkeystore -srckeystore combined.pkcs12 -srcstoretype PKCS12  -srcstorepass <PASSWORD> -destkeystore myKeystore -deststoretype JKS -deststorepass <KEYSTORE_PASSWORD> -destkeypass <KEYSTORE_PASSWORD>

    Here's a Unix example:

    cd /home/admin/Acrolinx/server/bin
    keytool -v -importkeystore -srckeystore combined.pkcs12 -srcstoretype PKCS12  -srcstorepass <PASSWORD> -destkeystore myKeystore -deststoretype JKS -deststorepass <KEYSTORE_PASSWORD> -destkeypass <KEYSTORE_PASSWORD>


    • The variable <PASSWORD> is the password you used when you created the PKCS12 file.
    • The variable <KEYSTORE_PASSWORD> is your keystore password.

    You've now generated a keystore in your server's bin directory.

  3. Open your overlay of the core server properties file. You can find it under %ACROLINX_CONFIGURATION_ROOT%/server/bin/coreserver.properties. Add the following properties.

    endpointHost=<CORE_SERVER_NAME>
    endpointProtocol=https

    <CORE_SERVER_NAME> has to be the domain name on your certificate, and not the machine name. To use HTTPS, the core server needs a DNS name that's accessible to the clients.

    a) Update the endpointPort value if you use a different port for secure communication. By default, all Integrations connect to the core server through port 8031. If your security policy requires secure communication to go through a specific port such as 443, add the extra endpointPort as follows:

    endpointPort=443
  4. Define the keystore and truststore details by adding the following properties:

    sslKeystore=<KEYSTORE_NAME>
    sslKeystorePassword=<PASSWORD>
    sslTruststore=<KEYSTORE_NAME>
    sslTruststorePassword=<PASSWORD>

    Example:

    sslKeystore=myKeystore
    sslKeystorePassword=pRu4Hatr
    sslTruststore=myKeystore
    sslTruststorePassword=pRu4Hatr

    In most cases, the value for sslTruststore is the same as the value for sslKeystore . If you leave out the sslTruststore properties completely, the values that you entered for the sslKeystore properties are automatically used as the sslTruststore settings as well. If you created a separate truststore, use that file name and password instead.

  5. (Optional) If you use a different JVM to the one that is installed with the Acrolinx Server and want to specify a different keystore algorithm, complete this step - otherwise proceed to step 6. Add the following additional property:

    ssl.KeyManagerFactory.algorithm=<ALGORITHM_NAME>

    For example, if you use the IBM JVM, add the property as follows:

    ssl.KeyManagerFactory.algorithm=IbmX509
  6. Save your overlay of the core server properties file, and start all your Acrolinx servers.

Updating the URL in Acrolinx Integrations

After you’ve secured the Acrolinx URL with HTTPS, Acrolinx users need to update the connection details in their Integrations to use the new HTTPS address.

Instruct users to navigate to Options > Change Server and update the Acrolinx address field to:

https://<CORE_SERVER_NAME>:<PORT>

Users need to access the Dashboard through the https address as well:

https://<CORE_SERVER_NAME>:<PORT>/Dashboard.html

Acrolinx is now secured with HTTPS and ready to use.

See the following articles for optional extra steps: