Introduction
Every time that you create an application that targets a ServiceNow instance by calling REST or SOAP web services using ServiceNow APIs or custom scripted web services, you will have to keep in your application’s KeyStore the ServiceNow public key certificate to establish the TLS HTTP connection with your ServiceNow instance.
As an industry best practice, ServiceNow rotates the TLS certificates (also called leaf certificates) every 6 months. This change may impact your application if you do not update your application KeyStore with the current server certificate once it changes.
The project presented in this blog allows on-demand retrieval of the current ServiceNow server TLS certificate in PEM format and add it as an attachment to a record in a custom instance table. The certificate is pulled from the same instance URL. The project requires a MID server running on Linux OS(*) and the Openssl tool installed in the same Linux environment.
(*) Note: the same project could probably be adapted to work on Windows environments running the Windows version of Openssl, but some testing an adaptation of commands will be needed.
Implementation
Note: All the information about the script used in this project are attached as text files to this blog. Copy the code under the "script" title. Observe that for business rule "Detect Openssl End" there is also a condition for the business rule.
There are 6 main components in this solution listed below. Be aware that you need to modify the scripts to use your own MID server name. My project's MID server name is 'TinkerMid'. This name is used in script ‘GetLeafCertificate’, business rule ‘Detect Openssl end’, and business rule ‘AttachCert’.
1. A table [u_leaf_certificates] with two fields ‘u_name’ and 'u_comments’.
A new record will be added to this table having the date and time stamped every time a certificate is pulled. The record will also have the ServiceNow public PEM certificate file as attachment. Only the u_name table field is currently used, but field u_comments can be used for any additional information you may want to add.
Name...: Leaf Certificates [u_leaf_certificates]
Fields...: u_name , u_comments
Type....: String, UTF-8
2. Scheduled Script Execution ‘GetLeafCertificate’ to start the certificate pulling process.
This job creates an ecc_queue probe to run an Openssl command in the OS where the MID server is hosted. This OS command creates a file in the MID server containing the PEM certificate. The absolute file location for this example is: /usr/servicenow/mid/agent/files/sncert.txt while the relative path to MID server installation point is ~/mid/agent/files/sncert.txt. You need to change the file path and name to match yours.
The Job can be run scheduled or executed manually.
3. Business rule ‘Detect Openssl end’ on ecc_queue, on Before.
This business rule inspects ecc_queue input entries and fires once the command probe has been completed, then:
- Creates a new record on table [u_leaf_certificates].
- Stamps the name date and time on new created record.
- Changes to state ‘Processed’ the output and input command probes.
4. Business rule ‘AttachCert’ on u_leaf_certificates, After Insert.
This business rule fires when new records are inserted on table [u_leaf_certificates] and execute the following tasks:
- Encrypt password before calling MID server script includes.
- Calls MID server script includes 'fileUploader'.
- Pass parameters required to script includes like are file path, credentials, and instance URL.
The absolute file path for this example is: /usr/servicenow/mid/agent/files. You need to change the file path and file name to match yours.
5. MID server script includes ‘fileUploader’.
This is a Javascript code based on standard Java classes and techniques to read a file from disk and stream it (java.net.URL() , openConnection(), getOutputStream(), java.io.Writer, java.io.File). It also uses the ServiceNow Attachment API endpoint to upload the already captured leaf certificate as an attachment into the correspondent record in [u_leaf_cretificates] table. The URL for the attachment API endpoint is automatically built by the script based on the parameters passed by business rule ‘AttachCert’.
6. Custom System properties ‘cert_req_username’ and ‘cert_req_password’.
Keeps the username and password that will be used to call the attachment API from the MID server. For simplicity I choose not to store and encrypted the password in the system property. However, the password string will be encrypted while calling the MID server script includes so it will not be revealed in ecc_queue.
Names…….: cert_req_username, cert_req_password
Type………..: String
There are different ways to store a password already encrypted. You can modify this project at your will if needed.
Execution
To capture the certificate just manually execute the Scheduled Script ‘GetLeafCertificate’. A new record will be created in table [u_leaf_certificates] containing the attached certificate. The whole process takes a few seconds.
Executing the scheduled script:
Checking ecc_queue:
Checking system logs:
Certificate table list:
Attached Certificate:
Conclusion
This project can serve as a good start point to build something more appropriated to your needs. However, as simple as it is, gives you the capability to collect ServiceNow PEM certificate at any time and effortless. Once the certificate is captured, you can handle it to your developers so they can include it in the application's KeyStore.
