Following ServiceNow Product documentation, starting in Rome Patch 4, you can configure mutual authentication for the MID Web Server extension using the Transport Layer Security (TLS) protocol. Mutual authentication for TLS is called mTLS. During mutual authentication, the client authenticates the server's certificate, and the server authenticates the client's certificate. (link)
On ServiceNow support pages, there are many Knowledge Articles on that topic, however, every time someone wants to establish this type of connection, looks like it is not as easy as described in the KBA.
I decided to write a Community Article about that, hope you can use it to play with that functionality.
Please note, that my setup is based on a self-signed certificate! Officially connection between MID Server and the platform with self-signed certificate is not supported. Additionally, this can be used for a dev environment, but I would not recommend using a self-signed certificates in Production environment.
Said that, let's start.
First thing – CA, what it is? CA stands for a Certificate Authority – an entity that is trusted and can confirm the identity of the certificate requestor. So, if we want to establish an encrypted connection between two hosts, we need to encrypt that connection with the Public Key of the one host that is confirmed by CA that the second host trust, so the connection can be established. In my case confirmation of the identity is done based on the signed-off by the CA certificate of the host.
Now, what is a self-signed certificate?
The self-signed certificate is a certificate signed off by CA, but that CA is not known/trusted by any official CAs = can be created by anyone. If we know who created that CA, and we trust that person/organization, we can use it, but as I mentioned above, for the Production environment it is not recommended to use a self-signed certificate.
Coming to the ServiceNow platform – let's check prerequisites.
Before we start creating the certificates, we need to ensure that our platform is ready for that.
How to check this?
First thing is to check if our infrastructure is already migrated to a modern version of the load balancer – ADCv2.
We can do it using the command:
curl -I https://<instance-name>
If as a result, you can see “Server: snow_adc” – that means your instance is already migrated. If the result is different, you need to raise a support case to migrate your instance to ADCv2.
Next thing is to check if your instance has enabled TLS support. How..?
Use command:
curl https://<instance-name>/adcv2/supports_tls -w ‘\n’
If the result is ‘true’ or ‘mixed’ – your instance is ready. If the answer is different, you need to raise a support case to enable TLS support on the instance (Warning! Requires node restart).
The instance is ready, so we can move forward.
The next thing would be to install a MID Server on the Virtual Machine. All required information can be found in Product Documentation (link).
After installation of the MID Server and making it running, do not validate the MID. Check if the MID is connected to the platform, if needed allow an update, but do not validate it, as if MID has been validated, it will require additional steps to make the MID Server ‘clean’ and ready (relevant KBA with procedure how to do that you can find on Now Support).
An important pre-requisite for the MID is that java in the supported version has to be properly installed on the (virtual) machine, including set the system variables like JAVA_HOME.
Time to start playing with CA and certificates.
Note: for MID Server I propose to use an alias = a hostname – that makes it all easier for maintenance.
Regardless of the platform OS, if that is Windows or Linux, commands are the same, but if you are not working on a root account in Linux, for most of them you need to add ‘sudo’ in front. The only difference is with the format of the PEM file, but I will highlight that later.
- Stop the MID Server
./stop.shNote: command should be run from agent folder.
- Creation of the CA:
keytool -genkeypair -alias ca -keystore test_keystore.jks -dname ‘CN=CA’ -storepass <store_password> -keypass <key_password> -ext bc=ca:true -keysize 4096 -validity 1000 -keyalg RSA - Generation of the certificate for MID Server
keytool -genkeypair -alias <hostname> -keystore test_keystore.jks -dname ‘CN=<hostname>’ -storepass <store_password> -keypass <key_password> -keysize 4096 -keyalg RSA -validity 1000 -
Now, you can check if your keystore contains expected 2 entries:
-
Now we need to ask CA to sign-off the MID Server certificate
keytool -certreq -keystore test_keystore.jks -storepass <store_password> -alias <hostname> -file <hostname>.cer -
From CA stand point, we’ve received a request, so time to sign it off
keytool -gencert -keystore test_keystore.jks -storepass <store_password> -alias ca -infile <hostname>.cer -outfile <hostname>.cert -
Signed off certificate have to be added to the keystore
keytool -importcert -keystore test_keystore.jks -storepass <store_password> -file <hostname>.cert -alias <hostname> -
Now if we compare fingerprint in the keystore, we can see that for our MID it is different
-
As we need to upload to the platform certificate for CA, we need to export in in PEM format
keytool -exportcert -alias ca -keypass <key_password> -keystore test_keystore.jks -storepass <store_password> -rfc -file ca_cert.pem -
…and the same for MID certificate:
keytool -exportcert -alias <hostname> -keypass <key_password> -keystore test_keystore.jks -storepass <store_password> -rfc -file <hostname>_cert.pem -
Upload your CA key (ca_cert.pem) to the sys_ca_certificate table.
Note1: when you create a new record, you need to attach file before submitting the record, otherwise you will receive an error.
Note2: before moving to the next step, wait till Publish Status of the Certificate will be changed to ‘Active’. -
Upload your MID Server certificate to the sys_user_certificate table.
Note1: as with the CA certificate, before submitting a new record, you need to add an attachment: <hostname>_cert.pem file.
Note2: only one CA can be active in time. So if you want to play with more than one MID Server, for all MIDs the same CA needs to be used. It means that the cert created in step 3 for the 2nd MID needs to be copied to the host where CA was created, signed off there (steps 5 and 6), and finally copied back to the 2nd MID. -
Now the MID’s certificate has to be installed in MID’s keystore. The tricky part is that the file has to contain both: a private key and a signed-off certificate for MID. We can achieve that using 2 commands (convert keystore to PKCA12 format (1), and export it to PEM format required by the platform (2)):
keytool -importkeystore -srckeystore test_keystore.jks -destkeystore intermediate.p12 -deststoretype PKCS12 openssl pkcs12 -in intermediate.p12 -out <hostname>_certs.pem -nodes -
Now you need to ensure that in <hostname>_certs.pem file you have only Private Key and Certificate for MID Server based on alias <hostname>. You can do it using any text editor, like vi or notepad++.
-
Next step will be install MID’s certificate in MID’s keystore
./bin/scripts/manage-certificate.sh -a defaultsecuritykeypairhandle <hostname>_certs.pemNote: the command has to be run directly in the agent folder, because of the hardcoded path for all required classes and config files!
-
…enable mTLS authentication
./bin/scripts/manage-certificate.sh -m -
..and finally, start the MID once more time.
./start.sh -
In the platform, you should be able to see MID Server running with mTLS Authentication
And that is it.
Enjoy, I hope this article will be helpful.
