TLS Configuration on Virtual Appliances (2024)

When adding a certificate to the Virtual Appliance, ensure that:

• You must complete the following steps for every virtual appliance on the virtual appliance cluster that is connected to the source.

• To manually add a new certificate for the source to your virtual appliance's truststore, you need to ensure that the virtual appliance does not connect to the source before you complete the steps listed here. Do not test the connection between the source and virtual appliance. This also might require temporarily suspending scheduled aggregations.

• The source server has been configured for TLS.

• The va-config-<va_id>.yaml file has been configured for your virtual appliance.

  Note
  The certificate you copy must use PEM format.

Perform the following:

1. Copy the PEM-encoded certificates to the /home/sailpoint/certificates directory. This directory might not be empty because it’s where the VA adds any certificates it grabs from the source.

2. Restart Connector Gateway using the following commands:

   ‘sudo systemctl restart ccg’

3. Watch the /home/sailpoint/log/ccg-start.log. If this is successful, import should log messages of the following form:

   {"@timestamp":"2017-04-21 06:57:12 +0000","level":"INFO","type":"ccg","message":"Checking CCG Sources certificates"}

   {"@timestamp":"2017-04-21 06:57:12 +0000","level":"INFO","type":"ccg","message":"Cert files found: [\"/home/sailpoint/certificates/411818.pem\"]"}

   06:57:12 +0000","level":"INFO","type":"ccg","message":"Importing cert /home/sailpoint/certificates/411818.pem"}

If you are using an external certificate authority, you only have to connect to the VA from the source to import the certificate.

Perform the following:

1. In the source, ensure that the following are true:

   • The Hostname for the source matches the hostname in the virtual appliance's configuration.

   • The source is connected to the virtual appliance you configured to use TLS.

     Note
     If using Active Directory with IQService enabled, the Hostname cannot be an IP Address.

2. Change the Port to 636.

3. If available, enable the Use TLS option.

4. Test the connection.

The source's certificate is auto-imported to the VA.

When your certificate has expired, you can replace it on the source and then reboot your VA.

Perform the following:

1. Add the new certificate on the source with a new name.

2. Restart the Connector Gateway using the following commands:

   sudo systemctl restart ccg

   The source's certificate is auto-imported to the VA.

If you are using your own certificate authority, you need to add the root and intermediate certificates to the VA.

Note
This process might also be required if your source is not automatically uploading the certificate from the VA.

Prerequisites

• You have created at least one virtual appliance cluster

• The certificate is on the source

Perform the following:

1. Import certificate and entire key chain (Root and Intermediate Certificates) to VA as described in Importing a Certificate and Keychain to the Virtual Appliance.

2. Restart Connector Gateway using the following commands:

   sudo systemctl restart ccg

3. In the source, ensure that the following are true:

   • The Hostname for the source matches the hostname in the virtual appliance's configuration.

   • The source is connected to the virtual appliance you configured to use TLS.

   Note
   If using Active Directory with IQService enabled, the Hostname cannot be an IP Address.

4. Change the Port to 636.

5. If available, enable the Use TLS option.

6. Test the connection.

The source's certificate is auto-imported to the VA.

When your certificate has expired, you need to add the new certificate on both the source and the VA with a new name.

Perform the following:

1. Add the new certificate on the source with a new name.

2. Import certificate and entire key chain (Root and Intermediate Certificates) to VA as described in Importing a Certificate and Keychain to the Virtual Appliance.

3. Restart the Connector Gateway using the following commands:

   sudo systemctl restart ccg

4. Test the connection.

   The source's certificate is auto-imported to the VA.

If DNS is not configured for your network, you need to edit the hosts.yaml file on the virtual appliance to specify the hostname. This is because the sources that support TLS communication use IQService which cannot connect to TLS over an IP address.

Note
By default, the virtual appliance obtains the TLS certificate automatically from the source the first time it connects to the source. If you want to manually load the certificate to your virtual appliances, you need to do so before the source successfully connects to the virtual appliance.

Perform the following:

1. Open your virtualization platform and start the VA.

2. Log in to the virtual appliance.

   

3. Open the attached hosts.yaml file to edit it.

4. Uncomment lines 3-6 and replace 4-6 with actual values, according to the following requirements:

   

   • The spacing and indentation must be precise.

   • The fourth line must start with 2 spaces followed by a valid IP address matching the IP address configured for the host.

   • The fifth line must start with 2 spaces followed by a dash and 1 additional spaces. It must contain a fully-qualified hostname.

   • The sixth line must must start with 2 spaces followed by a dash and 1 additional spaces. It must contain a hostname, and must match the hostname configured for the source. Both are required.

   Note
   If you have IQService configured for your source, you cannot use an IP address for a hostname.

5. Repeat step 4 as needed for multiple entries.

6. Copy (hosts.yaml) file to the VM, using scp, as follows:

   1. Find the IP address for the VA by running ifconfig -a.

   2. Copy the file by running the scp command on your local workstation, as follows:

      scp <download_path>/hosts.yaml sailpoint@<ip_address>:/home/sailpoint/hosts.yaml

      Note
      If you want to manually upload a TLS certificate to your VA, do so now. See Manually Uploading a certificate to a VA for instructions.

7. Choose one of the following:

   • If you are editing an existing virtual appliance, continue to step 8.

   • If you are configuring a new virtual appliance, continue configuring the virtual appliance here Virtual Appliance Administrator's Guide​.

8. Enable TLS for the source.