Configuring HTTPS for Admin and Catalog access

From ELC
Jump to: navigation, search

To configure HTTPS for the Web Admin Interface, you will need to perform the following steps:

  1. Obtaining a Signed Certificate from a Certificate Authority
  2. Importing the Signed Certificate into a Java Keystore File
  3. Configuring ELC to Use the Certificate

Obtaining a Signed Certificate from a Certificate Authority

HTTPS requires a signed certificate issued by a certificate authority to encrypt communication between the ELC Web Admin server and the client browser.

Instructions for obtaining a signed SSL certificate will depend on your preferred Certificate Authority. Please consult documentation from your preferred certificate authority for instructions on how to obtain a signed SSL certificate.

The process will generally require creating a certificate signing request. During this process, a private key file will be created. This file should be stored securely, and will need to be used in the next step.


Importing the Signed Certificate into a Java Keystore File

To enable HTTPS for ELC Web Admin, a signed certificate and its associated private key must be made available in a compatible keystore file in the JKS format. A tool called keytool is used to create the JKS keystore file. keytool is included in the ELC installation at <ELC-Installation>\Java\jre8\bin\keytool.exe for Windows, and <ELC-Installation>\Java\jre8\bin\keytool for Linux.

The JKS keystore needs to include the private key associated with the issued certificate, as well as the chain of certificates starting from the issued certificate and leading to the certificate for the root Certificate Authority. To use keytool to create a JKS keystore file, these files need to first be imported into a PKCS12 file.

To create the PKCS12 file, the openssl tool is required. This tool is included in Linux. For Windows, the tool can be found at https://wiki.openssl.org/index.php/Binaries.

To create the PKCS12 file, run the following command:

openssl.exe pkcs12 -export -in fullchain.pem -inkey privkey.pem -name elc -out elc.p12

When prompted, provide an export password for the elc.p12 file. In the above command, fullchain.pem is the file containing the full chain of certificates, provided by the certificate authority, and privkey.pem is the private key file associated with the certificate. Some certificate authorities may return the certificate chain as individual files, in which case, you will need to combine them into a single file before using the openssl command. For Windows, use the command:

copy server.pem + intermediate.pem + authority.pem fullchain.pem

For Linux, use the following command:

cat server.pem intermediate.pem authority.pem > fullchain.pem

When you have created the PKCS12 file, use the following command to create the JKS keystore file:

keytool.exe -importkeystore -srckeystore elc.p12 -srcstoretype pkcs12 -srcstorepass exportpwd -alias elc -destkeystore keystore.jks -deststoretype jks -deststorepass storepwd -destkeypass keypwd -destalias elc

Replace exportpwd with the export password you used in the openssl command, and storepwd and keypwd with your preferred keystore and key passwords. You will need the latter two passwords when configuring ELC for HTTPS.


Using a Self-Signed Certificate

During testing, you may choose to use a self-signed certificate instead of a certificate issued by a certificate authority.

keytool.exe -genkeypair -alias elc -keyalg RSA -dname CN=localhost -storepass storepwd -keypass keypwd -keystore keystore.jks -storetype jks

Replace localhost with the hostname that your client browsers will be using to access the ELC Web Interface, and storepwd and keypwd with your preferred passwords.

Note that when a self-signed certificate is used, client browsers will see a warning when connecting to the ELC Web Interface, and will have to accept the security warning before proceeding.


Configuring ELC to Use the Certificate

HTTPS is configured from the HTTP version of the ELC Web Admin Interface. To do this complete ELC installation, open the Admin Interface in a browser, and click on the Configuration Properties section on the left.

Before enabling HTTPS, you will need to copy the JKS keystore file created in Importing the Signed Certificate into a Java Keystore File to the <ELC-Installation>/conf directory.

To enable HTTPS, set the following properties:

Property Name Property Description Instructions
webAdminHttpsEnable Enable web admin HTTPS port. Set to true to enable HTTPS.
webAdminHttpsPort Set the HTTPS port for the web admin. The default value is 5583.
webAdminHttpsKeystore Set the web admin HTTPS certificate keystore file. Point this to the JKS keystore file you copied into the conf directory.
webAdminHttpsKeystorePassword Set the web admin HTTPS certificate keystore password. Specify the keystore password used in Importing the Signed Certificate into a Java Keystore File. This was shown as storepwd in the example command line.
webAdminHttpsKeyPassword Set the web admin HTTPS certificate key password. Specify the key password used in Importing the Signed Certificate into a Java Keystore File. This was shown as keypwd in the example command line.
webAdminHttpsCertAlias Set the web admin HTTPS certificate alias in the keystore. Specify the alias used in Importing the Signed Certificate into a Java Keystore File. This was shown as keypwd in the example command line.

Save the changes to the configuration properties, and restart the ELC service. Point a browser to:

https://elc.example.com:5583/admin/server_status.jsf

You should see a lock symbol in the browser address bar, indicating that HTTPS is being used, and the connection is secure. If this does not happen, refer to Troubleshooting HTTPS.


Troubleshooting HTTPS

If the browser is unable to reach the page, it indicates that the HTTPS configuration settings are invalid. To troubleshoot this, look in the <ELC-Installation>/logs/error.log file for an error message related to the HTTPS settings.

The following table shows errors that may be reported in the file, and the likely cause of the error. You can use the non-HTTPS ELC Admin Console to change the configuration settings:

http://localhost:5580/admin/server_config.jsf

Error Message in error.log Likely Cause and Remedy
HTTPS settings are invalid - File error reading keystore: C:\Program Files\Embarcadero\ELC5.36\LicenseCenter\conf\keystore.jks (The system cannot find the file specified) The configured keystore file could not be found. Check that the keystore file is present, or edit the webAdminHttpsKeystore setting to specify the correct file path and name.
HTTPS settings are invalid - File error reading keystore: Keystore was tampered with, or password was incorrect The configured keystore password was incorrect. Check that the setting webAdminHttpsKeystorePassword matches the keystore password.
HTTPS settings are invalid - Security Exception reading keystore: Cannot recover key The configured key password was incorrect. Check that the setting webAdminHttpsKeyPassword matches the key password.
HTTPS settings are invalid - Configured alias elc was not found in keystore file C:\Program Files\Embarcadero\ELC5.36\LicenseCenter\conf\keystore.jks. The following aliases were found: server. The configured alias could not be found in the keystore. Check that the setting webAdminHttpsCertAlias matches the alias (key name) used in the keystore.


If there is a warning or error in the browser when connecting to the HTTPS ELC Admin Interface, please refer to the following table for likely causes.

Browser Warning/Error Message Likely Cause and Remedy
This site can’t provide a secure connection. elc.example.com sent an invalid response. The browser is attempting to use HTTPS but the server is responding with HTTP. Check that the address used has the correct port number. It should be the HTTPS port (default 5583), instead of the HTTP port (default 5580). Check that the webAdminHttpsPort setting matches the port used in the address.
The page/site isn’t working. elc.example.com didn’t send any data. The browser is using HTTP when connecting to the HTTPS port. Check that the address starts with https:// when connecting with the HTTPS port (default 5583).
Your connection is not private. Attackers might be trying to steal your information from localhost (for example, passwords, messages, or credit cards). The certificate could not be verified by the browser when connecting to the specified address.

This may be because the host name used in the address does not match the host name used for the certificate. Ensure that you are using the hostname specified in the certificate and not “localhost”.

The same error will also be shown if the certificate was not issued by a certificate authority trusted by the browser, such as when the certificate is self-signed. To establish a secure connection, the certificate must be issued by a trusted certificate authority.

It is possible to ignore the warning and proceed with loading the HTTPS ELC Web Admin Interface. To do so, click “Advanced”, followed by “Continue to elc.example.com (unsafe)”. When this is done, the connection is insecure.