To ensure that data transferred to and from the server is protected, LGTM Enterprise relies on SSL/TLS encryption.
Communication between internal LGTM Enterprise components—for example, the web application and the file store—is protected using self-signed certificates that are generated during the installation process. By default, the web application is also configured to use a self-signed certificate to communicate externally. This can be useful for small trial installations, but is unsuitable for a production deployment because:
- Code review integration with Bitbucket Server will fail unless you configure Bitbucket to trust the automatically generated certificate.
- Users will see a browser security message when they attempt to access LGTM Enterprise. They may need to add a security exception for the site before they can view it (behavior varies for different browsers).
- Users will be unable to use the LGTM plugin to view alerts in their IDE.
For details of the various components of an LGTM Enterprise deployment, see Server overview.
Configuring LGTM to be recognized as secure
To configure the LGTM Enterprise web application so that it is recognized by browsers as a secure site, you specify the private key and certificate that the LGTM web application will use in the cluster configuration file. Use absolute paths, or define the locations relative to the configuration file. This ensures that the keys are deployed to all machines in the web pool and maintained during updates to LGTM.
There is no set name or path for the cluster configuration file, but by default it is
state/lgtm-cluster-config.yml. A typical path to this file is
<LGTM releases directory>/<release number>/lgtm/state/lgtm-cluster-config.yml.
The cluster configuration file is not used directly by LGTM—it is a description of a configuration. The current configuration is stored internally by LGTM. You can generate a cluster configuration file that describes the current configuration by using the
Edit the cluster configuration file on the coordination server and update the
web block to include an
ssl section. For example, to use a certificate and key file that are stored alongside the cluster configuration file on the coordinator:
- hostname: "lgtmcontrol"
For detailed information on how to locate and edit this file see, Editing and deploying the cluster configuration.
If you are also altering the URL at which users will access LGTM Enterprise, you need to set the
external_url property—see, Changing the LGTM URL.
Deploying the certificate
As with other changes to the cluster configuration, you need to generate new service configurations and deploy them to all machines in the control pool. The process is the same as for other changes to the configuration.
If a separate web pool is defined, this change must also be deployed to all machines in the web pool.
This change does not need to be deployed to machines in the work pool.
For more information about the control and web pools, see Control pool.
Verify the change
You have now changed the SSL certificate used by the LGTM web application. When you navigate to the URL for LGTM Enterprise, you should no longer see a security warning. Your browser should display a padlock icon, showing that it's a secure site.
It is important that the server name in the certificate matches the public name of the server on which LGTM Enterprise is running. So if the host name is
servername.mydomain.net, then the X509v3 subject alternative name in the server certificate must match this, either directly or with a wildcard certificate:
$ openssl x509 -in <server certificate PEM file> -text -noout
... X509v3 extensions: X509v3 Basic Constraints: CA:FALSE X509v3 Extended Key Usage: TLS Web Server Authentication X509v3 Key Usage: critical Digital Signature, Key Encipherment X509v3 Subject Alternative Name: DNS:servername.mydomain.net Signature Algorithm: sha256WithRSAEncryption ...
If the server certificate is signed by a CA using a chain of one or more intermediate certificates, both the server certificate and any intermediate certificates need to be joined into a single server certificate file. For example:
cat servername_mydomain_net.pem intermediate_certificate.pem > certificate.pem
Usually the server key and a certificate signing request (CSR) are generated on the server. The CSR is then sent to a CA which will return the required certificate files. But local practices can differ—when in doubt, refer to your existing practices for requesting SSL certificates.
It is also possible that the key and certificate have been provided in a different format from that described above—possibly inside a Java keystore. In this case, the key and relevant certificates must be extracted and saved in the required format. Refer to the relevant documentation—for example, for OpenSSL—for information on how to convert the key and certificate(s) to PEM format.
Mandating certificate-based access
You can configure the LGTM Enterprise web application so that it will only accept client connections that present a client certificate signed by a specified certificate authority.
To do this, edit the
lgtm-cluster-config.yml file on the coordination server and add a
client_ca_path setting to the
ssl section within the
web block. For example, to use a CA certificate PEM file that is stored alongside the cluster configuration file on the coordinator: