Implementation Guide: How to Set Up Certificate-Based AuthenticationSummaryPrerequisites: 1. The instance should be on the ADCv2. Run the below command and make sure the response has "Server: snow_adc" or not. curl -I https://<Instancename>.service-now.com 2. mTLS should be enabled on the instance level. The below URL should return "true" https://<instancename>.service-now.com/adc/supports_tls 3. Certificate based authentication plugin (com.glide.auth.mutual) has to be activated in the instance. ReleaseAll releasesInstructionsBelow are steps that need to be followed to set up Certificate-Based Authentication in ServiceNow. A. Create a Certificate Ideally, during setup, the third-party app team integrating with ServiceNow should provide these necessary certificates. We are sharing the commands below for informational purposes only. If you encounter any issues while running the commands, please work with your internal teams for assistance. Step 1. Create a Key Store (Certificate pair) using the keytool genkeypair command. The below command creates a key store that will have a public key and a private key. keytool -genkeypair -alias letstestcba -keyalg RSA -keysize 2048 -validity 365 -keypass ServiceNow123 -keystore letstestcba.jks -storepass ServiceNow123 Step 2. Once the Key store is created, we need to generate a CSR and get it signed by an external CA. keytool -certreq -alias letstestcba -file mycsr.pem -keystore letstestcba.jks Step 3. When you create a Certificate Signing Request (CSR) and submit it to a Certificate Authority (CA), you will typically receive the following certificates Server CertificateIntermediate Certificate(s)Root Certificate Step 4. In order to set up the Key store, we need to upload Certificates back to the Key Store. Use the below commands to upload the received certificates back to the key store. Import the Root Certificate: keytool -import -trustcacerts -alias root -file root.pem -keystore letstestcba.jks -storepass ServiceNow123 Import the Intermediate Certificate(s): keytool -import -trustcacerts -alias intermediate -file intermediate.pem -keystore letstestcba.jks -storepass ServiceNow123 Note: If there are multiple intermediate certificates, repeat this step for each, giving each a unique alias (e.g., intermediate1, intermediate2, etc.). Import the Signed Server Certificate: keytool -importcert -alias letstestcba -file SignedServerCert.pem -keystore letstestcba.jks -storepass ServiceNow123 Note: Ensure that the alias used in the above import command (Import the Signed Server Certificate) matches the alias used when you originally created the keystore and generated the CSR(.i.e alias used in Step 1 & Step 2). This binds the server certificate to the corresponding private key within the keystore. Please note that "ServiceNow123" is a sample password used in the above commands. When using these commands, please use your own passwords. Now the key store is ready for use. You can upload this key store on your third-party app so that it makes outbound calls to ServiceNow using 2 way SSL. Step 5. To use a self-signed certificate for this integration for testing purposes, run the following command to export the public certificate from the keystore directly after Step 1 (there is no need to run the commands mentioned in Steps 2, 3, and 4). Please note that it is not recommended to use self-signed certificates. It is always recommended to use CA-signed certificates.Self-signed certificates can be used only for testing purposes; however, they are not suitable for production use due to the lack of trust and validation they provide. Using CA-signed certificates ensures a higher level of security, trust, and compliance. keytool -exportcert -alias letstestcba -file ServerCert.pem -keystore letstestcba.jks -storepass ServiceNow123 -rfc openssl x509 -inform der -in ServerCert.pem -out ServerCertNew.pem B. Upload the CA Certificate Chain > Navigate to Certificate Based Authentication -> CA Certificate Chain > Click on New > Configure the Name. > Make sure the type is CA Cert. > Attach the root certificate. > Click on Submit. > Repeat the same steps for the intermediate certificate as well. While uploading the intermediate certificate, set the type to 'CA Cert' so that the intermediate certificate will also be synced to the load balancer. Note: You can also upload both Root and Intermediate certificates as a single certificate and select type as CA Cert. > As soon as we upload the certificate with the type set to 'CA Cert', it takes some time to sync the certificate to the ServiceNow load balancer. The publish state will be set to active once the certificate is uploaded to the load balancer. > Please find below the sample certificate that we uploaded for testing purposes. C. Upload the Server Certificate and map it with a user: > Navigate to Certificate Based Authentication -> User to Certificates Mapping > Click on New > Configure the Name. > Select the User > Click on the Manage Attachment on the grey header and upload the Server Certificate. > Click on Submit. > Please find below the sample certificate that we uploaded for testing purposes. D. Enable certificate based authentication > Navigate to Certificate Based Authentication -> Properties > Enable "Certificate Based Authentication" > Click on "Save" Now the Certificate-Based Authentication setup is ready. You can test it using the below CURL command. E. Test using the CURL command: > In order to test this from curl, we need private key of the keystore. Exporting a private key from a keystore using keytool directly is not supported, as keytool is primarily designed for managing certificates and keys within the keystore and does not provide an option to export private keys directly for security reasons. However, you can achieve this using the openssl tool along with keytool by following these steps: Step 1: First, convert the Java KeyStore (JKS) to PKCS12 format using keytool. PKCS12 format is compatible with OpenSSL. keytool -importkeystore -srckeystore letstestcba.jks -destkeystore letstestcba.p12 -deststoretype PKCS12 -srcalias letstestcba -deststorepass ServiceNow123 -srcstorepass ServiceNow123 Step 2: Use openssl to extract the private key from the PKCS12 keystore. openssl pkcs12 -in letstestcba.p12 -nocerts -nodes -out private_key.pem -passin pass:ServiceNow123 > Using the CURL command below, we can test the Certificate-Based Authentication setup. Please find the screenshot captured during the testing. curl -v -k -GET --key private_key.pem --cert ServerCert.pem "https://<Instancename>.service-now.com/api/now/table/incident?sysparm_limit=1" Related LinksThis is an inbound scenario to ServiceNow where ServiceNow acts as the server and the third-party app initiating the API call to ServiceNow is the client. During mutual authentication in the SSL handshake, the server (i.e., ServiceNow) sends a "Certificate Request" message containing a list of Distinguished Names (DNs) that were uploaded to the ServiceNow load balancer in Section B (Upload the CA Certificate Chain). Upon receiving this message, the client application (i.e., the third-party application) responds with a "Certificate" message. This message includes the client certificate, which was mapped to the user in Section C (Upload the Server Certificate and map it with a user). Upon receiving the "Certificate" message, the ServiceNow load balancer validates it against its trust store, allows further communication, and forwards the request to the application node for further processing. Below is the 2-way SSL handshake diagram. For more information about the setup and how it works, please refer to the articles below. https://support.servicenow.com/kb?id=kb_article_view&sysparm_article=KB0993615 https://docs.servicenow.com/bundle/washingtondc-platform-security/page/integrate/authentication/task/set-up-mutual-auth.html