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 VA.

Sources that Support TLS

The following sources can be configured to communicate over a TLS connection:

Manually Uploading a Certificate to a Virtual Appliance

Import a Certificate and Keychain to the Virtual Appliance

Important

When adding a certificate to the virtual appliance (VA), ensure that the certificate you copy is in Privacy-Enhanced Mail (PEM) format.

  • Before manually adding a new certificate for the source to your virtual appliance's truststore, ensure the following:

    • The virtual appliance (VA) is not connected to the source.

    • Connection testing between the source and VA is suspended.

    • Scheduled aggregations are temporarily paused, if necessary.

  • The source server has been configured for TLS.

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

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

    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 gets from the source.

    2. Restart the CCG using the following command:

      sudo systemctl restart ccg

    3. Watch the /home/sailpoint/log/ccg-start.log file. If successful, the import should log messages from the 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 you're using a PEM format for your certificate and then try again.

    Sometimes the export of a certificate may not work properly with the VA. Using the openSSL command to get the certificate is a good way to get the latest certificate.

    1. Use the openSSL command to get the latest certificate:

      1. Run the following command in openSSL:

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

      2. From the command output file, copy the certificate content between --BEGIN CERTIFICATE-- and --END CERTIFICATE--.

      3. Create a new file called cert.pem in the /home/sailpoint/certificates folder.

      4. Save the copied certificate contents in the new cert.pem file.

    2. Restart the CCG using the following command:

      sudo systemctl restart ccg

Using an External Certificate Authority (CA)

Add the Certificate to the Virtual Appliance

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

Prerequisites:

  • The ability to use TLS 1.0 - 1.2

  • You have created at least one virtual appliance cluster

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

  • The certificate is on the source

Complete the following steps:

  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 you are using Active Directory with IQService enabled, the Hostname cannot be an IP Address.

  2. Change the Port to 636.

  3. If available, select the Advanced Options checkbox.

  4. In the Use TLS field, select the Enable checkbox.

  5. Test the connection.

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

Replace an Expired Certificate Issued by an External Certificate Authority

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

Prerequisites

Complete the following steps:

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

  2. Restart CCG. You can use either of the following commands:

    sudo systemctl

    restart ccg

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

Using an Internal Certificate Authority

Add the Certificate to the Virtual Appliance

If you're using your own certificate authority, you will 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

Complete the following steps:

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

  2. Restart the CCG. You can use either of 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 you are using Active Directory with IQService enabled, the Hostname cannot be an IP Address.

  4. Change the Port to 636.

  5. If available, select the Advanced Options checkbox.

  6. In the Use TLS field, select the Enable checkbox.

  7. Test the connection.

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

Replace an Expired Certificate Issued by an Internal Certificate Authority

If you're using an internal CA, you need to add the new certificate on both the source and the VA with a new name.

Prerequisites:

Complete the following steps:

  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 Import a Certificate and Keychain to the Virtual Appliance.

  3. Restart CCG. You can use either of the following commands:

    sudo systemctl

    restart ccg

  4. Test the connection.