Josh Nerius

3 minute read

I’ll start with the good stuff. Starting with Jakarta, SNI is supported! If you need to enable it, create a system property named glide.outbound.tls_sni.enabled and set the value to true. After you set this property, it make take up to 30 seconds for the change to take effect. If you’re using a MID server, create a MID server property with the same name and restart the MID Server.

If you don’t know what SNI is, don’t worry, you’re not alone. I didn’t know what it was until I started getting handshake errors when attempting to make outbound API calls using RESTMessageV2. If you found this post after running into an integration issue, there’s a chance you’re discovering SNI the same way I did.

What Exactly is SNI?

SNI stands for Server Name Indication. SNI is an extension to the TLS protocol that allows a single server/IP address to serve certificates for many hosts. With the emergence of high density application hosting environments where many services are hosted on a single IP address, an increasing number of APIs require the clients calling them to have SNI support.

To learn more, check out TechBytes Episode 34: Web Services. silas and bryanbarnard discuss the technical details behind SNI and why it’s becoming more popular.

What an SNI Issue Looks Like in ServiceNow

When making outbound HTTP calls to a 3rd party service (via RESTMessageV2, HTTP Data Sources, etc.), if that service requires SNI and SNI isn’t enabled on the ServiceNow side, this will manifest as an SSL Handshake error. The error will look something like this:

javax.net.ssl.SSLHandshakeException: Received fatal alert: handshake_failure.

If you encounter this, there’s a good chance you will need to enable SNI. Not every handshake error is related to SNI, but if you have reason to believe the certificate associated with the service you’re calling is otherwise valid, try enabling SNI.

Amazon API Gateway and Google Cloud Functions are two examples of services that require SNI support, so if you encounter a handshake error and you’re using one of these services, enabling SNI is one of the first things to try.

Digging Deeper b is it Really an SNI Issue?

You can use the openssl command line utility to determine if a particular endpoint requires SNI.

Step 1 b try connecting without SNI.

openssl s_client -state -debug -connect api.provider.com:443.

If api.provider.com utilizes and requires SNI, you’ll see output similar to this (note the error: SSL3 alert read:fatal:handshake failure):

SSL_connect:SSLv2/v3 write client hello A

read from 0x7fc699703c80 [0x7fc69b806600] (7 bytes => 7 (0x7))

0000 - 15 03 01 00 02 02 28B B B B B B B B B B B B B B B B B B B B B B B B B B B B B ……(

SSL3 alert read:fatal:handshake failure

SSL_connect:error in SSLv2/v3 read server hello A

If you do not see a handshake failure in the output, the issue you’re dealing with is probably not an SNI issue.

Step 2 b try connecting with SNI.

openssl s_client -state -debug -connect api.provider.com:443 -servername api.provider.com.

This time, you should see a large amount of output from the SSL handshake, and you should find a response from the server itself:

HTTP/1.1 200 Server: api.provider.com …etc…

Backwards Compatibility

Enabling SNI is backwards compatible and should not impact other code that makes API calls to non-SNI endpoints. With that said, you should always take time to test existing integrations after making property changes of this nature.


Comments