LGTM Enterprise 1.22.1

Installing an SSL certificate


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 production systems, you need to obtain an SSL certificate for LGTM that matches the requirements described in Certificate details below. Then update the cluster configuration file to include it.

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 convention it is state/lgtm-cluster-config.yml. The state directory is typically held under version control and checked out into the LGTM releases directory. A complete path might therefore be: /home/lgtmadminuser/lgtm-releases/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 lgtm-config-gen.jar tool's init action.

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"
  external_url: "https://lgtm.example.com/"
    certificate_path: "server.crt"
    key_path: "server.key"

For detailed information on how to locate and edit this file see, Editing and deploying the cluster configuration.

If you're 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 a new set of files for the updated configuration 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.

Certificate details

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:

    client_ca_path: "client_ca.pem"

Related topicsRelated topics