TLS Configuration on Virtual Appliances

Enabling a source to communicate with a virtual appliance using a TLS connection encrypts all data sent between the source and the Virtual Appliances (VA).

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"}

Note

  • If you see an error instead of the log messages above, this is an indication that your certificate is in an invalid format. Verify that a PEM format is used for your certificate and try again.

  • Sometimes export of a certificate may not work properly with the Virtual Appliance. Using the openssl command to get the certificate is a good way to get the latest certificate.

    1. `openssl s_client -connect server.example.com:636 > output < /dev/null`

    2. From the above command, grab the output file and the top of the file has the certificate. It starts with --BEGIN CERTIFICATE--. Copy the contents between that and --END CERTIFICATE--.

    3. Create a new file in the /home/sailpoint/certificates directory called cert.pem, for example with the contents you copied from step 2.

    4. Restart connector gateway using sudo systemctl restart ccg command.

Using an External Certificate Authority (CA)

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

  • The ability to use TLS 1.0 to 1.2

  • You have created at least one virtual appliance cluster

  • CA root and intermediate certificates are in the Java CA certificates keystore

  • certificate is on the source

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.

Complete the process as described in Adding an external Certtificate Authority (CA) to the Virtual Appliance.

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.

Using an Internal Certificate Authority (CA)

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.

Complete the process as described in Adding an external Certtificate Authority (CA) to the Virtual Appliance.

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.

  • At least one virtual appliance cluster has been configured and connected successfully.

  • Best Practice: The instructions contained in this section are most effective when executed as a virtual appliance is being created, before configuring the proxy.yaml file. For more information, see Virtual Appliance Reference Guide​.

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.