Using mutual authentication in ServiceNow: What you should keep in mind
Some third-party service providers might require a SSL-based authentication for their Web services. Mutual authentication is easier to setup than WS-Security, still there are some tricks and unexpected issues when trying to set it up. There’s no existing detailed documentation with the technical steps on how to setup an outbound SOAP Web Service using the mutual authentication. And if you are new to Web services this might turn out to be a challenge.
This blogpost from John Andersen was very helpful to start setting up a mutual authentication for the first time. Even though it is a good blogpost, its content does not apply to a Fuji or later release as it is based on an old release of ServiceNow. This is why we have collected a more comprehensive list with the necessary steps to set up mutual authentication for Fuji or newer releases:
- Export the SSL certificate of your ServiceNow instance from the browser and send it to the service provider
- Import in ServiceNow the public certificates provided to you by the service provider
- Generate a Java or PKCS12 key-store and import it into ServiceNow under the System Definition > Certificates module. After attaching the certificate file to the record, check that the key-store is valid by clicking on the “Validate Stores/Certificates” related link
- Extract the public certificate from this key-store and send it to your service provider
- Create a protocol profile record under System Security > Protocol Profiles. Give it a name such as “myhttps” and in the Keystore field select the key-store you created in step 3. The port should contain the port number on which the Web service is running.
- On your SOAP Message record, check the Use mutual authentication flag and then select the protocol profile you created in step 5 in the Protocol profile field.
- In the SOAP endpoint field in your SOAP Message function, if you are running Fuji, then setting myhttps as a protocol in the URL will work. While in Helsinki, it is not required to put myhttps, it works also with simply https.
Self-signed and CA-signed certificates
A self-signed certificate is acceptable during development in the development instance. The Web service provider will require you to always provide a CA-signed certificate for their production environment, and in some or most of the cases you might also need a CA-signed certificate for the testing environment. The generation of a CA-signed certificate might turn out to be a long process if it is not clearly defined who is responsible for providing it. Thus, make sure you define the right responsibilities at the beginning of the project. Normally, it is the ServiceNow system owners that should generate the CA-signed key-store and provide the certificate (step 4 above) to the service provider.
If you are interfacing with the back-end system through a middleware, it is the middleware that needs to import the certificate, and you have to guide your customer through how to get a CA-signed certificate. Big organizations might already have their predefined certificate authorities; this is also something that needs to be discussed at the beginning of the project. In case the customer has no internal process defined for issuing certificates, than any CA authority can be selected. As ServiceNow does not recommend any authority in particular, it is up to you to select one.
Possible issues when setting your connection to the target Test or Production system
We set up mutual authentication using Geneva release, therefore our experience is based on this release. Many of the issues we faced might be obsolete on Istanbul or Jakarta.
After deploying the configurations in the Production instance, we had to reset the two system properties mentioned in the blogpost, i.e. glide.httpclient.protocol.myhttps.class and glide.httpclient.protocol.myhttps.port, to empty because they were suspected to be interfering with normal SSL handshake. The possible reasons of such a behaviour could be as simple as the default key-store being used instead of the one defined on the protocol profile if you have more than one active java key-store in the ServiceNow instance. Setting these two properties to empty fixed the connection issue.
Once you have uploaded in ServiceNow the CA-signed certificate for connecting to the test or to the production system of the service provider, and you have created separate certificate records for them, you should simply update the key-store reference field on the existing myhttps protocol profile. If you create another protocol profile for the testing or the production environment, you might run into connection errors when trying to connect to the target system. Therefore, in order to prevent some unexpected behavior, keep only one protocol profile named myhttps, and simply update the references to the CA-signed key-store. Also, make sure the key-store file name contains only small letters, as you might end up having authentication issues.
In order to avoid service disruption, it is very important to set up reminders for the renewal of the certificates. By clicking the Expiration notification flag on the certificate record in ServiceNow, you can define some users in the Notify on expiration field that will be notified when the expiration date is approached. You should be aware of this at least one month in advance before the expiration, because the service provider might have a formal process in place for importing new certificates in their production environment where approvals might be required.
Keeping the above mentioned points in mind will make your mutual authentication project much easier. Have you already set up a mutual authentication in ServiceNow? Tell us about your experience in the comment section below.