- Overview
- Default self-signed certificate
- Installing a new certificate
- Importing a root CA certificate
- Switching back to self-signed certificates
- Troubleshooting
Overview
Login Enterprise uses certificates to provide increased security as a standard part of its infrastructure.
It is common for enterprises to use their own Certificate Authority (CA) and therefore Login Enterprise lets you customize which certificates are used.
Certificates are used by browsers for the Web UI and internal communications between the launchers and the targets being tested. The launcher installs it automatically and the target engine ignores SSL errors by default. However, the target engine stops ignoring SSL errors after importing your own certificate.
Default self-signed certificate
By default, Login Enterprise runs with a self-signed certificate on the virtual appliance. This lets you get Login Enterprise up and running quickly and requires you to proceed even though the certificate is untrusted.
To verify the certificate status, in the Login Enterprise sidebar menu, navigate to Other > About.
The certificate status will be available in the Information section:
Installing a new certificate
If your new certificate was issued by an internal Enterprise or Standalone CA, we recommend importing the root CA certificate and any intermediary certificates before proceeding with the new certificate install. This will ensure that the certificate chain is trusted on the appliance. For more information, see Importing a root CA certificate. For the certificate requirements, see Encryption technology.
Please note that the PFX should only contain the server certificate and server key.
To install a new certificate:
- Log in to the appliance console or use SSH to connect as admin. For more information, see the Maintenance menu.
- Use WinSCP or an equivalent SFTP client to upload the pfx certificate to the /certificates folder in the root of the appliance, e.g. /certificates/mycert.pfx
- If using WinSCP, select the SFTP protocol for the connection type
- Select Apply new certificate from the appliance console menu.
a. Specify the full path to the pfx file, including the filename, e.g. /certificates/mycert.pfx, and press Enter.
b. Specify the password for the pfx file and press Enter. - This will automatically switch the product to use the Trusted SSL mode. To verify the certificate status, refresh the Web UI to see that it is trusted, or in the Login Enterprise sidebar menu, navigate to Other > About. The certificate status will be available in the Information section:
Importing a root CA certificate
Login Enterprise lets you import root Certificate Authority (Root CA) certificates. This functionality is useful when you have an internal CA that generates certificates for your organization. Once a valid certificate is imported—if you use an internal CA—SSL can be enabled for the AD authentication, Email, and Database configuration settings.
There are 3 areas in the Login Enterprise where you can enable SSL:
- Access control
- External notifications > Email alerting
- System > Database configuration
To import a root CA certificate:
- Use WinSCP or an equivalent SFTP client to upload a root CA certificate to the /certificates folder in the appliance, e.g. /home/admin/mycert.crt
- Log in to the appliance console. For more information, see the Maintenance menu.
- Navigate to Main > System > Import root CA certificate.
- Specify the full path to the newly uploaded .crt file, e.g. /home/admin/myCert.crt
- Restart the Login VSI services when prompted to apply the changes.
Switching back to self-signed certificates
At times certificate installation may fail. If this is the case and you'd like to reuse the self-signed certificate supplied with the appliance, take the following steps:
- Log in to the appliance console. For more information, see the Maintenance menu.
- Select Regenerate self-signed certificates from the appliance console menu.
- This will automatically reset the product to accept any SSL certificate.
Troubleshooting
Problems after applying a new certificate
For problems after applying a new certificate, first make sure your root CA and any intermediate certificates are properly imported/installed on the appliance.
If the certificate being applied was issued by an External CA (DigiCert, Sectigo, GlobalSign, etc.), make sure your appliance public certificates are up to date. For this, run apt install ca-certificates from Bash.
If the certificate was issued by an Internal Enterprise or Standalone CA, ensure the certificates in the trust chain (root and intermediates) have been uploaded to the appliance in the .pem (base64) format with the .crt extension and imported through the pdmenu > Import root CA certificate.
When a certificate is successfully imported, it should show 1 or more was “added.”
If it shows “0 added”, it could mean the certificate was already imported or that the certificate file extension was not .crt.
When using the Import root CA certificate option through pdmenu, the certificate will be copied to /usr/local/share/ca-certificates/, and a symbolic link to that file is created with the .pem extension in /etc/ssl/certs/. To verify that the certificates exist in the proper directory, run the commands below in Bash.
ls -la /usr/local/share/ca-certificates/
ls -la /etc/ssl/certs/ | grep "local/share"
Login Enterprise services not starting
If you've applied a new certificate and find that the Login Enterprise services are not starting or that services are started but do not get past the “starting x service” status, we recommend checking the list of allowed URLs along with the Appliance Guard (pi_guard) status. For more information, see the Login Enterprise 5.x 'Services not starting' common issues.
Allowed URLs
The allowed URLs list contains a list of URLs that are allowed to be used to access the Login Enterprise and can be modified in the System > pdmenu. The first entry in the allowed URLs list should contain the FQDN of the certificate that was applied to the appliance. The appliance uses the first entry in the allowed URLs list as the ServerURL in the appsettings.json file for applications like the launcher, eventlogger, and appliance guard.
Some certificate requirements
Whatever the SANs of your certificate are, they must be:
- DNS resolvable to your appliance, and
- One of them must be the first entry in your ALLOWED_URLS key in the /loginvsi/.env file.
If your local hostname is not listed in the SAN field, and you can't regenerate the certificate to include it, consider changing the hostname to match the certificate. However, your ALLOWED_URLS, and any client attempting to access the appliance, must use a name in the SAN field, if SAN exists. Otherwise, it must match the Subject field.
If you change the hostname, make sure you reset pi_guard along with restarting services to get the containers recomposed.
systemctl restart pi_guard
loginvsid restart
Ignoring certificate errors on Debian
We understand that some customers operate in environments where SSL communications are inspected or intercepted, leading to certificate verification errors when downloading packages with apt or our ISO with curl. These errors can disrupt your workflow and make it difficult to manage software packages efficiently.
To address this, we've introduced a feature in the PDMenu that detects SSL certificate issues during the update process. When a certificate problem is identified, you'll be prompted to allow insecure connections if needed. This feature modifies the commands to ignore certificate errors, specifically by adding the --insecure flag to curl and adjusting the configuration for apt.
The following sections provide step-by-step instructions on how to enable and disable the “Ignore certificate errors” option for both apt and curl.
Enabling "Ignore certificate errors" option
1. Open PDMenu.
- Launch the PDMenu from your application menu or by running pdmenu from the terminal.
2. Navigate to the Troubleshooting section.
- Use the arrow keys to select Troubleshooting and press Enter.
3. Select "Ignore certificate errors".
- Find the option labeled “Ignore certificate errors” and press Enter.
4. Configure certificate validation settings.
- You will see the following submenus:
- Set apt config
- Set curl config
Ignoring certificate errors for apt
1. Select "Set apt config".
- Use the arrow keys to highlight Set apt config and press Enter.
2. Enable ignoring certificate errors.
- Follow the on-screen prompts to configure apt to ignore certificate errors. This will add the necessary configuration to the apt settings.
After configuring apt to ignore certificate errors, you can verify the changes by performing operations that involve SSL connections. In cases where a certificate is expired, untrusted, or cannot be validated, appropriate error messages will be displayed, confirming that certificate validation is enabled.
Ignoring certificate errors for curl
1. Select "Set curl config".
- Use the arrow keys to highlight Set curl config and press Enter.
2. Enable ignoring certificate errors.
- Follow the on-screen prompts to configure curl to use the --insecure flag. This will adjust the curl command settings accordingly.
After configuring curl to ignore certificate errors, you can verify the changes by performing operations that involve SSL connections. In cases where a certificate is expired, untrusted, or cannot be validated, appropriate error messages will be displayed, confirming that certificate validation is enabled.
Disabling "Ignore certificate errors" option
1. Open PDMenu.
- Launch the PDMenu from your application menu or by running pdmenu from the terminal.
2. Navigate to the Troubleshooting section.
- Use the arrow keys to select Troubleshooting and press Enter.
3. Select "Ignore certificate errors".
- Find the option labeled “Ignore certificate errors” and press Enter.
4. Configure certificate validation settings.
-
- You will see the following submenus:
- Set apt config
- Set curl config
- You will see the following submenus:
Restoring certificate validation for apt
1. Select "Set apt config".
- Use the arrow keys to highlight Set apt config and press Enter.
2. Disable ignoring certificate errors.
- Follow the on-screen prompts to remove or comment out the configuration that ignores certificate errors for apt.
The certificate validation will be ignored.
Restoring certificate validation for curl
1. Select "Set curl config".
- Use the arrow keys to highlight Set curl config and press Enter.
2. Disable ignoring certificate errors.
- Follow the on-screen prompts to remove the --insecure flag from curl commands.
By following these instructions, you can effectively manage SSL certificate issues using the PDMenu interface, ensuring smooth package management. Remember to re-enable certificate validation once the immediate issues are resolved to maintain the security and integrity of your system.
If you have questions or need additional information about the certificates, feel free to contact our support at support@loginvsi.com.