Configure SSL/TLS

TLS (Transport Layer Security) is a protocol that establishes encrypted, authenticated communication between machines, devices, applications, and servers. The TLS handshake involves three processes: authenticating the client and server, negotiating the cipher suite and TLS version, and exchanging keys.

Certificate exchange and validation

During the TLS handshake, the client and server exchange SSL certificates to establish trust. This process may also require a CA file to validate the certificate against. Once certificates are exchanged and validated, a secure connection is established.

For example, when an Itential adapter makes a request to an external system that uses SSL, the external system responds with its SSL certificate. The adapter then validates that certificate.

In development and testing environments, self-signed certificates are common because obtaining a CA file is more complex. Configuring the adapter to accept invalid certificates bypasses this validation entirely — the adapter accepts any certificate without checking it.

Validate an SSL certificate

Three options are available:

Publicly-signed certificate — obtain a CA file for the certificate and set the path in ssl.ca_file in the service instance configuration.

Self-signed certificate — obtain a CA file for the certificate and set the path in ssl.ca_file in the service instance configuration.

Skip validation — set ssl.accept_invalid_certs to true in the service instance configuration. Use this only in development and testing environments.

For full SSL property details, see SSL properties.

TLS overhead

TLS handshakes add latency to adapter calls. The time required depends on what needs to be validated — a simple CA file validation may take about one second, while validating three large certificate files can take closer to ten seconds.

Troubleshooting SSL failures

The external system uses SSL but the adapter does not have SSL enabled.

Set ssl.enabled to true in the service instance configuration. You must also either provide a ca_file or set accept_invalid_certs to true.

The adapter has SSL enabled but cannot validate the certificate.

For development and testing, set ssl.accept_invalid_certs to true in the service instance configuration. Confirm with a system administrator before changing this setting.

For production environments, obtain the CA file, place it on theItential Platform server, and set ssl.ca_file to the file path in the service instance configuration. This is the recommended approach for production.

If you need additional support, contact the Itential Adapters Team.