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

When adding a certificate to the virtual appliance (VA), please keep in mind that:

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

  • To manually add a new certificate for the source to your virtual appliance's truststore, you must 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 might also 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.

Important
The certificate you copy must use PEM format.

Complete the following steps:

  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. You can use either of the following commands:

    sudo systemctl restart ccg

  3. Watch the /home/sailpoint/log/ccg-start.log file. If this is 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 that 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. Run the following command in openSSL:

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

  2. From the command, copy the output file. The top of the file will have the certificate. It will start with --BEGIN CERTIFICATE--. Copy the contents until the --END CERTIFICATE-- text.

  3. Now create a new file in the /home/sailpoint/certificates folder called cert.pem and save the certificate you copied within it.

  4. Restart 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.