How To: Enable Mutual TLS (mTLS) Authentication Between a MID Server and the ServiceNow Instance

Will Hallam · 2 hours ago

ServiceNow Community • Technical How-To

⚠️ Disclaimer

This article is an independent community contribution and is not official ServiceNow documentation. It is provided as-is for educational purposes and does not represent the views of ServiceNow, Inc.

The author assumes no responsibility for any issues, outages, or security implications arising from following this guide. Always test in a sub-production environment before applying changes to production instances or MID Servers.

Refer to the official ServiceNow product documentation and contact ServiceNow Support for authoritative guidance on mutual authentication configuration.

Overview

By default, MID Servers authenticate to the ServiceNow instance using basic credentials (a dedicated service account username and password). Mutual TLS (mTLS) replaces this with certificate-based authentication: during the TLS handshake, the MID Server presents a client certificate to the instance, and the instance validates it against a trusted CA chain. This eliminates the need for stored credentials on the MID Server and prevents unauthorized MID Servers from connecting to the instance.

This article covers the complete end-to-end process for enabling mTLS between a MID Server and the ServiceNow instance, including all instance-side configuration steps. It covers both fresh MID Server installations (where mTLS is configured from the outset, with no basic auth bootstrap required) and converting existing MID Servers from basic auth to mTLS. It uses Active Directory Certificate Services (ADCS) as the example Certificate Authority, but the same approach applies to any private or commercial CA. (CAVEAT: the specific commands for performing PKI operations can be highly variable depending on your internal PKI setup and policies; hopefully you and your team can extrapolate as needed from the commands I've included here from my home lab setup.)

Both OpenSSL (cross-platform) and Windows-native commands (certreq, certutil) are provided throughout, so you can use whichever toolchain fits your environment.

ℹ️ Note: This guide covers MID Server → ServiceNow instance authentication only. For mTLS between the MID Server and third-party endpoints (e.g., LDAP, REST APIs), refer to the separate Outbound Mutual Authentication documentation.

How MID Server mTLS Authentication Works

Understanding the trust model is important before proceeding with the configuration steps.

When a MID Server connects to the instance using mTLS, the instance validates the client certificate presented during the TLS handshake against the CA chain uploaded to sys_ca_certificate.list. The leaf certificate uploaded to sys_user_certificate.list is associated with a user identity on the instance — this is how the MID Server authenticates. The instance does not need a pre-existing MID Server record; it authenticates the incoming connection based on the certificate-to-user mapping, and the MID Server record is created through that authenticated session.

This means mTLS can be configured as the initial authentication method for a brand-new MID Server. There is no requirement to bootstrap with basic auth credentials first. The MID Server installer natively supports selecting mutual authentication at install time, providing the PEM bundle path, and starting the MID Server with certificate-based authentication from its very first connection.

This is particularly important for environments where MID Servers are dynamically provisioned (containers, auto-scaling groups, ephemeral infrastructure), where there is no opportunity for an interactive basic auth bootstrap.

Prerequisites

Instance Requirements

1. ADCv2 Load Balancer: Your instance must be on the ADCv2 infrastructure. Verify by running:

curl -I https://<instance>.service-now.com

Look for Server: snow_adc in the response headers. You can also verify via the ADCv2 endpoint:

curl -I https://<instance>.service-now.com/adcv2/server

If your instance is not on ADCv2, open a case with ServiceNow Support to request migration.

2. TLS Support Enabled: Certificate-based authentication requires TLS support on the instance. Verify by browsing to:

https://<instance>.service-now.com/adcv2/supports_tls

If the result is "true" or "mixed", your instance is ready. If not, open a case with ServiceNow Support to request TLS support be enabled. This may require a node restart.

3. Certificate Based Authentication Plugin: The com.glide.auth.mutual plugin must be activated. Navigate to System Applications → All Available Applications → All, search for "Certificate based authentication", and activate it. Requires the admin role.

4. Contact ServiceNow Support: Open a case to request mutual authentication be enabled for MID Server connections on your instance. This is a prerequisite that Support must configure at the infrastructure level.

MID Server Host Requirements

Administrative/root access to the MID Server host
OpenSSL installed (for CSR generation and certificate conversion), OR Windows certificate tools (certreq, certutil) on a domain-joined machine
The MID Server installation package (downloaded from the instance), either freshly extracted or an existing installation

Certificate Authority Requirements

A private CA (e.g., ADCS) or a commercially trusted CA
Self-signed certificates are not supported for MID Server mutual authentication
The CA must be able to issue certificates with the Client Authentication EKU (OID 1.3.6.1.5.5.7.3.2)

⚠️ Important: Self-signed certificates are explicitly not supported for MID-to-instance mutual authentication. The certificate must be signed by a private or commercial CA.

Network Requirements

⚠️ Important: If the MID Server connects to the instance through an HTTP proxy that performs SSL/TLS inspection (e.g., Zscaler, Palo Alto SSL Decryption, BlueCoat), the proxy will terminate and re-establish the TLS session, which breaks mutual authentication. The proxy replaces the MID Server's client certificate with its own during the re-encryption, so the instance never sees the MID's certificate. You must configure a proxy bypass or SSL inspection exclusion for the ServiceNow instance URL (*.service-now.com) to allow the mTLS handshake to pass through end-to-end. Consult your network security team to configure this exemption.

Step 1: Generate a Certificate Signing Request (CSR)

Generate a private key and CSR with the Client Authentication Extended Key Usage. Two approaches are provided: OpenSSL (cross-platform) and certreq (Windows-native).

Option A: OpenSSL (Linux, macOS, or Windows with OpenSSL)

openssl req -new -newkey rsa:2048 -nodes \
  -keyout midserver-mtls.key \
  -out midserver-mtls.csr \
  -subj "/CN=MID Server mTLS Client/O=YourOrg/OU=ITOM" \
  -addext "keyUsage = digitalSignature, keyEncipherment" \
  -addext "extendedKeyUsage = clientAuth"

Verify the CSR:

openssl req -in midserver-mtls.csr -noout -text

Option B: certreq (Windows, Domain-Joined)

Create an INF file that defines the certificate request parameters:

; midserver-mtls.inf
[Version]
Signature = "$Windows NT$"

[NewRequest]
Subject = "CN=MID Server mTLS Client,O=YourOrg,OU=ITOM"
KeySpec = 1
KeyLength = 2048
Exportable = TRUE
MachineKeySet = TRUE
SMIME = FALSE
PrivateKeyArchive = FALSE
UserProtected = FALSE
UseExistingKeySet = FALSE
ProviderName = "Microsoft RSA SChannel Cryptographic Provider"
ProviderType = 12
RequestType = PKCS10
KeyUsage = 0xa0   ; digitalSignature (0x80) + keyEncipherment (0x20)
HashAlgorithm = SHA256

[EnhancedKeyUsageExtension]
; Client Authentication
OID = 1.3.6.1.5.5.7.3.2

Generate the CSR from the INF:

certreq -new midserver-mtls.inf midserver-mtls.csr

Verify the CSR with certutil:

certutil -dump midserver-mtls.csr

Confirm that the output shows the correct Subject, Key Usage, and the Client Authentication Enhanced Key Usage.

✅ Tip: Both options produce a .csr file ready for submission to your CA.

Step 2: Submit the CSR to Your CA and Obtain the Signed Certificate

Submit the CSR to your CA. Multiple methods are shown for ADCS environments.

Option A: certreq Submit (Windows, Domain-Joined)

Submit directly to the CA from the command line. If your ADCS environment has a dedicated client authentication certificate template, use that template name:

certreq -submit -attrib "CertificateTemplate:ClientAuth" midserver-mtls.csr midserver-mtls.crt

✅ Tip: If your CA does not have a dedicated Client Authentication template, you can use WebServer or another template that includes the Client Authentication EKU (OID 1.3.6.1.5.5.7.3.2). Consult your PKI administrator for the correct template name in your environment.

If the CA requires manual approval, retrieve the certificate after approval:

certreq -retrieve <RequestID> midserver-mtls.crt

Option B: ADCS Web Enrollment

Browse to https://<ca-server>/certsrv.
Select Request a certificate → Advanced certificate request.
Paste the contents of midserver-mtls.csr into the Base-64 encoded certificate request field.
Select the appropriate template and submit.
Download the issued certificate (Base64 format preferred).

Option C: Certification Authority MMC Snap-in

Open the Certification Authority MMC on the CA server, right-click Pending Requests (or use All Tasks → Submit new request), locate and approve the request, then export the issued certificate from Issued Certificates.

Step 3: Prepare the PEM Bundle

The MID Server mutual authentication mechanism requires a PEM bundle containing the certificate chain and the private key in PKCS#8 format. This step converts and assembles the required files.

3a. Export the Certificate and Private Key

If You Used OpenSSL for the CSR: You already have the private key (midserver-mtls.key) and the CA has issued a .crt or .cer file. Proceed to 3b.

If You Used certreq for the CSR: The private key is stored in the Windows certificate store. You need to export it as a PFX, then extract the PEM components.

Accept the issued certificate into the store first (if not already done):

certreq -accept midserver-mtls.crt

Export the certificate and private key as a PFX using certutil. You must specify the certificate's Common Name (or thumbprint) to identify which certificate to export:

certutil -exportpfx -p "YourPfxPassword" my "MID Server mTLS Client" midserver-mtls.pfx

ℹ️ Note: The my store name in certutil -exportpfx is typically case-insensitive, but behavior can vary across Windows Server versions. If the command fails, try My (capitalized) instead. If the "My" store contains multiple certificates with similar names, use the certificate thumbprint instead of the CN to avoid ambiguity. You can find the thumbprint with: certutil -store my

Alternatively, export via the Certificates MMC snap-in (certmgr.msc😞 locate the certificate under Personal → Certificates, right-click → All Tasks → Export, select "Yes, export the private key", choose PKCS#12 (.PFX) format, and set a password.

Then extract the PEM components from the PFX using OpenSSL:

# Extract the private key
openssl pkcs12 -in midserver-mtls.pfx -nocerts -nodes -out midserver-mtls.key

# Extract the certificate
openssl pkcs12 -in midserver-mtls.pfx -clcerts -nokeys -out midserver-mtls.crt

# Extract the CA chain (if included in the PFX)
openssl pkcs12 -in midserver-mtls.pfx -cacerts -nokeys -chain -out ca-chain.crt

ℹ️ Note: If you are using OpenSSL 3.x (default on Ubuntu 22.04+, RHEL 9+, and most modern Linux distributions), and the PFX was generated with legacy encryption (common when exported from Windows), you may need to add the -legacy flag to the openssl pkcs12 commands above (e.g., openssl pkcs12 -in midserver-mtls.pfx -nocerts -nodes -legacy -out midserver-mtls.key). OpenSSL 3.x dropped default support for the older RC2/3DES encryption algorithms that Windows certutil uses when creating PFX files. If you see errors like "unsupported algorithm" or "PKCS12 routines::pkcs12 pbe crypt error", the -legacy flag will resolve them. The -legacy flag is not recognized on OpenSSL 1.x and can be safely omitted on older systems.

3b. Convert the Private Key to PKCS#8 Format

The MID Server requires the private key in PKCS#8 format. Check the header of your key file:

BEGIN RSA PRIVATE KEY → PKCS#1 format. Must be converted.
BEGIN PRIVATE KEY → already PKCS#8. No conversion needed.
BEGIN ENCRYPTED PRIVATE KEY → PKCS#8 encrypted format. Must be decrypted. Run: openssl pkcs8 -topk8 -nocrypt -in midserver-mtls.key -out midserver-mtls-pkcs8.key (same command as the conversion below; it handles both decryption and format conversion).

Convert from PKCS#1 to PKCS#8:

openssl pkcs8 -topk8 -nocrypt -in midserver-mtls.key -out midserver-mtls-pkcs8.key

⚠️ Important: If the key header says BEGIN RSA PRIVATE KEY, it must be converted. If it says BEGIN ENCRYPTED PRIVATE KEY, it must be decrypted (use the same command above). If it already says BEGIN PRIVATE KEY (unencrypted PKCS#8), skip this step. Using the wrong format causes a "Could not find valid private key" error.

3c. Export the Root and Intermediate CA Certificates

You need separate PEM files for the root CA and any intermediate CAs. If you don't already have these:

Using certutil (Windows)

# View the CA chain to identify certificates
certutil -verify midserver-mtls.crt

# Export the root CA certificate (run on the CA server only)
certutil -ca.cert root-ca.cer

# Convert DER to PEM if needed
certutil -encode root-ca.cer root-ca.pem

ℹ️ Note: The certutil -ca.cert command queries the local CA service and must be run directly on the ADCS CA server. If you are on a different machine, download the CA certificate from the certsrv web enrollment page (https://<ca-server>/certsrv), or export it from the local certificate store with: certutil -store Root

Using OpenSSL

# View the chain in the issued certificate
openssl x509 -in midserver-mtls.crt -noout -issuer

# Convert DER (.cer) to PEM if needed
openssl x509 -inform DER -in root-ca.cer -out root-ca.pem

3d. Assemble the PEM Bundle

Combine the leaf certificate, any intermediate certificates, the root CA certificate, and the PKCS#8 private key into a single PEM file. The order must be:

Leaf certificate (the MID Server's client certificate)
Intermediate CA certificate(s), if any
Root CA certificate
PKCS#8 private key

ℹ️ Note: The official documentation states the certificate chain order must be: leaf, intermediates, then root. The private key is placed at the end of the bundle. Some ServiceNow documentation variants and KB articles describe placing the private key immediately after the leaf certificate (before the CA chain), and both orderings have been reported to work in practice. The leaf → intermediates → root → key order shown here is the most widely documented and is recommended. Some ServiceNow documentation variants describe splitting the PEM into separate files for the CA chain and the leaf+key bundle; the manage-certificates script accepts either a combined single-file bundle (shown here) or separate files.

Linux / macOS

cat midserver-mtls.crt intermediate-ca.pem root-ca.pem midserver-mtls-pkcs8.key > midserver-bundle.pem

Windows (PowerShell)

Get-Content midserver-mtls.crt, intermediate-ca.pem, root-ca.pem, `
  midserver-mtls-pkcs8.key | Set-Content -Encoding ASCII `
  midserver-bundle.pem

Windows (Command Prompt)

copy /a midserver-mtls.crt + intermediate-ca.pem + root-ca.pem + midserver-mtls-pkcs8.key midserver-bundle.pem

ℹ️ Note: Use copy /a (ASCII mode) rather than copy /b (binary mode) for PEM files. Binary mode can insert 0x1A (EOF) markers between concatenated files, which may corrupt the bundle. Note that plain copy without a flag defaults to /a for text files on most Windows versions, so the flag is technically optional but explicit is better for clarity. The PowerShell approach is generally the safest on Windows.

⚠️ Important (Cross-Platform): If you assemble the PEM bundle on Windows and then transfer it to a Linux MID Server host, ensure the file uses Unix-style line endings (LF, \n) rather than Windows-style (CRLF, \r\n). Windows line endings can cause PEM parsing failures on Linux. Convert with: dos2unix midserver-bundle.pem or sed -i 's/\r$//' midserver-bundle.pem.

✅ Tip: Open the resulting midserver-bundle.pem in a text editor and verify it contains the correct sequence of BEGIN CERTIFICATE / END CERTIFICATE blocks followed by a single BEGIN PRIVATE KEY / END PRIVATE KEY block. Ensure there are no blank lines or extra whitespace between sections.

Step 4: Configure the ServiceNow Instance

This step configures the instance to trust your CA and recognize the MID Server's client certificate. Complete this step before installing or starting the MID Server — the instance must be ready to accept certificate-based connections before the MID Server attempts to connect.

4a. Upload the CA Certificate Chain

Navigate to Certificate Based Authentication → CA Certificate Chain (sys_ca_certificate.list).
Click New.
Fill in the following fields:
- Name: A descriptive name for the CA chain (e.g., "HOMELAB Root CA" or "Corporate PKI Chain").
- Type: Select CA Cert.
- Format: Select PEM.
Before submitting, attach the CA chain PEM file. Use the paperclip icon in the form header bar (or right-click the header bar and select Attach a file) to add the PEM file as an attachment. The attachment must be added before the initial save — if you submit the record first without the attachment, the certificate will not be processed correctly.
Click Submit.
Wait for the Publish Status to change to "Active" before proceeding. This can take a few minutes as the certificate propagates to the load balancer infrastructure.

ℹ️ Note: If uploading certificates individually rather than as a bundle, upload the root CA first, then any intermediate CAs. It is preferable to upload as a single PEM bundle with the type set to CA Cert. Only one CA chain can be active at a time — all MID Servers using mTLS must use certificates signed by the same CA. This also means you cannot run old and new CA chains simultaneously during a CA rotation; plan accordingly (see CA Chain Rotation below).

4b. Upload the MID Server's Leaf Certificate

Navigate to sys_user_certificate.list (User Certificates).
Click New.
Fill in the following fields:
- Name: A descriptive name (e.g., "MID-01 mTLS Client Cert").
- User: Select the MID Server service account user (the same user the MID Server would use for basic auth, e.g., "mid.server"). This field maps the certificate to a user identity — without it, the instance cannot authenticate the MID Server's certificate to a valid session. The user must have the mid_server role.
- Format: Select PEM.
Attach the leaf certificate only (the MID Server's client certificate, without the private key) using the paperclip icon in the form header bar before saving.
Click Submit.

ℹ️ Note: The table sys_user_certificate.list is where MID Server mTLS leaf certificates are uploaded. This table associates certificates with user identities — the certificate maps to a user, not directly to a MID Server record. This is how the MID Server authenticates to the instance: it presents a certificate that the instance maps to a user with the appropriate MID Server roles. Do not confuse this with the "User to Certificate Mapping" table (Certificate Based Authentication → User to Certificate Mapping), which is used for PIV/CAC login or inbound REST API authentication — that is a different use case.

4c. Certificate-to-MID Server Mapping: Shared vs. Unique Certificates

ℹ️ Note: Multiple MID Servers can share a single leaf certificate mapped to the same service account user on sys_user_certificate.list. The instance authenticates the connection to a user, not to a specific MID Server record — individual MID Server identity is established by the MID Server name in config.xml after authentication. However, using unique certificates per MID Server is recommended for production environments: it enables granular revocation (you can revoke one MID Server's certificate without affecting others), simplifies troubleshooting, and provides a clearer audit trail. Each unique leaf certificate requires its own record in sys_user_certificate.list, but all can map to the same service account user.

⛔ Critical: Do not include the private key in the certificate uploaded to sys_user_certificate. Only the leaf (public) certificate should be uploaded to the instance.

Step 5: Install the Certificate on the MID Server

This step installs the PEM bundle into the MID Server's keystore. The approach differs depending on whether you are setting up a new MID Server or converting an existing one.

Option A: New MID Server Installation with mTLS (Recommended)

The MID Server installer natively supports mutual authentication as a first-class installation option. When mTLS is selected during installation, the installer skips all username/password prompts, imports the PEM bundle into the keystore, configures config.xml with only the instance URL (no credentials), and starts the MID Server with certificate-based authentication from its very first connection. No basic auth bootstrap is required.

Interactive Installation (Linux)

Run the installer from the agent directory:

cd /opt/servicenow/<mid_server_name>/agent
./installer.sh

The installer will prompt for the instance URL, proxy configuration, and then ask:

Do you want to use Mutual Authentication? [Enter Y or N] : Y
Enter the certificate path : /path/to/midserver-bundle.pem

When you answer Y, the installer skips the MID username and password prompts entirely. It imports the PEM bundle via manage-certificates.sh, configures config.xml with the instance URL, and proceeds to start the MID Server service.

Silent Installation (Linux)

For automated or headless deployments, use the silent installation mode. Note that -MID_USERNAME and -MID_PASSWORD are not required when -MUTUAL_AUTH Y is specified:

cd /opt/servicenow/<mid_server_name>/agent

./installer.sh -silent \
  -INSTANCE_URL https://<instance>.service-now.com/ \
  -MUTUAL_AUTH Y \
  -CERTIFICATE_PATH /path/to/midserver-bundle.pem \
  -USE_PROXY N \
  -CERTIFICATE_REVOCATION N \
  -MID_NAME "My_MID_Server" \
  -APP_NAME mid \
  -APP_LONG_NAME "ServiceNow_MID_Server" \
  -NON_ROOT_USER <service_account>

The installer validates the certificate path, imports the bundle, configures config.xml, and starts the MID Server service — all without any basic auth credentials.

ℹ️ Note: The -CERTIFICATE_REVOCATION N flag in the example above disables CRL/OCSP revocation checking and is shown for simplicity. Production environments should evaluate whether certificate revocation checking is appropriate for their CA infrastructure and set this to Y if CRL Distribution Points or OCSP responders are available.

✅ Tip: The silent installation mode is ideal for configuration management tools (Ansible, Puppet, Chef), container images, and auto-scaling group launch scripts. Place the PEM bundle on the host (or mount it as a secret) before invoking the installer.

Windows Installation

The Windows installers will not install the certificate bundle. To install the certificate bundle, copy it to the MID host, then invoke the following after the Windows installer completes:

cd "C:\ServiceNow\<mid_server_name>\agent"

bin\scripts\manage-certificates.bat ^
  -a defaultsecuritykeypairhandle ^
  "C:\path\to\midserver-bundle.pem"

Option B: Converting an Existing MID Server to mTLS

If you have a MID Server that is currently running with basic auth credentials and you want to switch it to mTLS:

Invalidate the MID Server First

If the MID Server is currently validated, invalidate it before installing the certificate. Navigate to the MID Server record in the instance and select Invalidate from the Related Links. This prevents the MID Server from attempting to connect with basic auth while the keystore is being modified, and avoids potential race conditions during the authentication switchover.

Install the PEM Bundle

Copy the PEM bundle file (midserver-bundle.pem) to the MID Server host, then run the manage-certificates script from the agent directory. The alias must be defaultsecuritykeypairhandle for MID-to-instance mutual authentication.

Windows

cd "C:\ServiceNow\<mid_server_name>\agent"

bin\scripts\manage-certificates.bat ^
  -a defaultsecuritykeypairhandle ^
  "C:\path\to\midserver-bundle.pem"

Linux

cd /opt/servicenow/<mid_server_name>/agent

./bin/scripts/manage-certificates.sh \
  -a defaultsecuritykeypairhandle \
  /path/to/midserver-bundle.pem

⛔ Critical: The manage-certificates script must be run from the agent directory root. It relies on relative paths to the required JAR files and configuration. Running it from any other directory will fail with a classpath error.

The script will:

Create the agent/security directory if it does not exist
Create or update agent/security/agent_keystore.jks
Import the certificate chain and private key under the alias defaultsecuritykeypairhandle

Verify the Keystore Contents

Regardless of which installation option you used, verify the keystore contents with the MID Server's bundled keytool:

Windows

.\jre\bin\keytool.exe -list -v -keystore security\agent_keystore.jks -storepass changeit

Linux

./jre/bin/keytool -list -v -keystore security/agent_keystore.jks -storepass changeit

Confirm you see a PrivateKeyEntry with alias defaultsecuritykeypairhandle, a valid certificate chain, and the correct expiry date.

ℹ️ Note: The changeit password used above is the default MID Server keystore password. In hardened environments, consider changing this password. If the keystore password has been changed, substitute the actual password in all keytool commands. The keystore password can be configured via the mid.keystore.password parameter or through the MID Server's security configuration.

Step 6: Basic Auth Credential Cleanup

For new MID Servers installed with mTLS (Option A): No action is required. The installer does not write username/password credentials to config.xml when mutual authentication is selected. The YOUR_INSTANCE_USER_NAME_HERE and YOUR_INSTANCE_PASSWORD_HERE placeholders are left untouched (or absent), and the MID Server authenticates exclusively via certificate.

For converted MID Servers (Option B): The mid.instance.username and mid.instance.password parameters in config.xml may be left in place for rollback purposes, but they are not used once mTLS is active. On the instance side, the MID Server user record can optionally be locked down to prevent password-based access.

To revert a MID Server to basic auth if needed, use the manage-certificates script:

manage-certificates -b <username> <password>

ℹ️ Note: After reverting to basic auth with manage-certificates -b, you must restart the MID Server service for the change to take effect. The MID Server does not pick up credential changes dynamically.

ℹ️ Note: MID Servers created with mutual authentication from the outset do not receive capabilities automatically. An administrator must manually add capabilities to the MID Server record on the instance. Existing MID Servers that had capabilities under basic auth retain them when switched to mTLS.

Step 7: Restart and Validate

For new MID Servers installed with mTLS (Option A): The installer starts the MID Server service automatically. Proceed directly to the validation steps below.

For converted MID Servers (Option B): Restart the MID Server service.

Restart the MID Server

Windows

# PowerShell
Restart-Service "ServiceNow MID Server_<mid_server_name>"

# Alternative: net stop/start
net stop "ServiceNow MID Server_<mid_server_name>"
net start "ServiceNow MID Server_<mid_server_name>"

Linux

sudo systemctl restart <mid_service_name>

ℹ️ Note: The systemd service name varies by installation. Common names include mid, snc_mid, or a custom name configured during setup. Check with: systemctl list-units | grep -i mid

Validate the MID Server

Navigate to the MID Server record on the instance.
The MID Server should come up and show a status of Up.
Review agent/logs/agent0.log.0 on the MID Server host to confirm a clean startup with no TLS handshake errors.

ℹ️ Note: A MID Server using mutual authentication cannot be re-keyed or validated via UI action in the same way as a basic auth MID. The validate action will re-validate the certificate trust chain.

Certificate Expiry and Renewal

Once mTLS is active, the MID Server's connection to the instance depends entirely on a valid client certificate. If the certificate expires, the MID Server will fail to authenticate and go Down with no graceful fallback — unless basic auth credentials are present in config.xml and the instance still accepts them (applicable only to converted MID Servers where the credentials were retained).

Monitoring Expiry

Check the certificate expiry date in the keystore at any time:

Windows

.\jre\bin\keytool.exe -list -v -alias defaultsecuritykeypairhandle ^
  -keystore security\agent_keystore.jks -storepass changeit | findstr "Valid"

Linux

./jre/bin/keytool -list -v -alias defaultsecuritykeypairhandle \
  -keystore security/agent_keystore.jks -storepass changeit | grep "Valid"

You can also check the expiry on the instance side by viewing the certificate record in sys_user_certificate.list, which displays the Valid to date.

✅ Tip: Set a calendar reminder or monitoring alert for at least 30 days before the certificate's expiry date. For environments with many MID Servers, consider building a scheduled job or report on sys_user_certificate to flag upcoming expirations.

Renewal Process

To renew the certificate before it expires:

Generate a new CSR (Step 1) and submit it to the CA (Step 2).
Prepare a new PEM bundle with the renewed certificate and the same (or a new) private key (Step 3).
Upload the new leaf certificate to sys_user_certificate.list on the instance (Step 4b) and wait for "Active" status. If the CA chain has not changed, you do not need to re-upload it.
Re-run the manage-certificates script on the MID Server host with the new bundle (Step 5, Option B procedure). The script will overwrite the existing keystore entry for the defaultsecuritykeypairhandle alias.
Restart the MID Server service (Step 7).

ℹ️ Note: You can optionally remove the old leaf certificate record from sys_user_certificate.list on the instance after confirming the renewed certificate is active and the MID Server has reconnected successfully.

CA Chain Rotation

If your CA's root or intermediate certificate is also approaching expiry (or your organization is migrating to a new CA), the CA chain on the instance must be updated as well. Because only one CA chain can be active at a time on sys_ca_certificate.list, plan the transition carefully: upload the new CA chain, wait for Publish Status "Active", then re-issue MID Server leaf certificates from the new CA and update each MID Server's keystore before decommissioning the old chain. During the transition window, MID Servers still using certificates signed by the old CA will lose connectivity once the old chain is replaced, so coordinate the cutover to minimize downtime.

Troubleshooting

Symptom	Resolution
"Could not find valid private key" error	The private key is not in PKCS#8 format. Convert it using: `openssl pkcs8 -topk8 -nocrypt -in key.key -out key-pkcs8.key`. The header must read `BEGIN PRIVATE KEY`, not `BEGIN RSA PRIVATE KEY` or `BEGIN ENCRYPTED PRIVATE KEY`.
Publish Status stays at "Pending" on sys_ca_certificate	The certificate is propagating to the ADCv2 load balancer. This can take several minutes. If stuck for more than 15 minutes, verify the PEM format and confirm ADCv2 migration is complete.
SSLHandshakeException in agent log	The instance does not trust the MID's client certificate CA. Verify the CA chain was uploaded to `sys_ca_certificate.list` and its Publish Status is "Active". Also verify that no TLS-intercepting proxy (Zscaler, Palo Alto, BlueCoat) is stripping the client certificate — see Network Requirements in Prerequisites.
MID Server shows Down after restart	Check `agent0.log.0` for keystore errors. Common causes: wrong alias (must be `defaultsecuritykeypairhandle`), corrupted PEM bundle, or manage-certificates script run from the wrong directory.
"Certificate chain is not end with a CA cert"	The CA chain uploaded to the instance is incomplete or in the wrong order. Ensure the PEM bundle ends with the root CA certificate.
Capabilities missing after mTLS setup	MID Servers created under mTLS do not receive capabilities automatically. Manually add required capabilities on the MID Server record. This applies to both new installations and is not an error.
manage-certificates script fails with classpath error	The script was not run from the agent directory root. `cd` to the agent directory and re-run.
certreq: "No certificate authority found"	The machine is not domain-joined or cannot reach the CA. Use the `-config` flag to specify the CA explicitly: `certreq -submit -config "CA-Server\CA-Name" midserver-mtls.csr midserver-mtls.crt`
MID Server goes Down unexpectedly (no config changes)	The client certificate may have expired. Check the expiry with keytool (see Certificate Expiry and Renewal above) and renew if necessary.
New MID Server fails to connect on first start (mTLS install)	Verify that instance-side configuration (Step 4) was completed before starting the MID Server. The CA chain must have Publish Status "Active" and the leaf certificate must be "Active" before the MID attempts to connect.
Silent installer exits with certificate path error	The `-CERTIFICATE_PATH` value does not point to a valid file. Verify the path is absolute and the file exists on the MID Server host. The installer validates the file exists before proceeding.
OpenSSL 3.x: "unsupported algorithm" or "pkcs12 pbe crypt error" when extracting PFX	The PFX was created with legacy encryption (common from Windows `certutil`). Add the `-legacy` flag to your `openssl pkcs12` commands. See the note in Step 3a for details.
PEM parsing errors on Linux MID Server (bundle created on Windows)	The PEM file likely has Windows-style line endings (CRLF). Convert to Unix line endings: `dos2unix midserver-bundle.pem` or `sed -i 's/\r$//' midserver-bundle.pem`.

Enable Debug SSL Logging

For detailed TLS handshake tracing, add the following JVM argument to the MID Server's wrapper configuration (wrapper-override.conf on Windows, or the equivalent on Linux):

-Djavax.net.debug=ssl,handshake

Restart the MID Server and review agent0.log.0 for full handshake details. Remove this flag after troubleshooting as it generates significant log volume.

Useful manage-certificates Commands

Command	Purpose
`manage-certificates -a <alias> <file>`	Add or replace a certificate entry in the keystore
`manage-certificates -g <alias>`	Display certificate details for the specified alias
`manage-certificates -m`	Show the current keystore menu/status
`manage-certificates -b <user> <pass>`	Revert to basic auth credentials (requires MID restart afterward)

Known Limitations

Self-signed certificates are not supported. The certificate must be signed by a private or commercial CA.
Only one CA chain can be active on the instance at a time. All MID Servers using mTLS must use certificates from the same CA. Old and new CA chains cannot coexist during rotation.
A MID Server using mutual authentication cannot be re-keyed or validated via UI action in the same way as basic auth MIDs.
New MID Servers created under mTLS do not inherit capabilities automatically; an admin must add them manually.
MID Server mutual authentication requires the PEM bundle format with a PKCS#8 private key. PFX/PKCS#12 is not directly supported by the manage-certificates script.
TLS-intercepting proxies break mTLS. Proxies that perform SSL inspection (Zscaler, Palo Alto SSL Decryption, BlueCoat, etc.) will strip the MID Server's client certificate. A proxy bypass must be configured for the ServiceNow instance URL.

Quick Reference: End-to-End Checklist

Instance Preparation (Complete Before MID Server Installation)

Verify instance is on ADCv2 (curl -I, look for Server: snow_adc; also check /adcv2/server)
Verify TLS support is enabled (browse to /adcv2/supports_tls, confirm "true" or "mixed")
Activate the com.glide.auth.mutual plugin
Contact ServiceNow Support to enable MID mutual authentication

Certificate Preparation

Generate a CSR with Client Authentication EKU (openssl req or certreq -new)
Submit CSR to CA and obtain the signed certificate (certreq -submit or web enrollment)
Export private key from Windows store if needed (certutil -exportpfx -p "YourPfxPassword" my "CN" file.pfx; add -legacy to openssl pkcs12 if using OpenSSL 3.x)
Convert private key to PKCS#8 (openssl pkcs8 -topk8 -nocrypt)
Export root/intermediate CA certs (certutil -ca.cert on CA server, or openssl x509 -inform DER)
Create PEM bundle: leaf cert + intermediates + root CA + PKCS#8 key (cat or Get-Content); convert line endings if transferring cross-platform

Instance Configuration

Upload CA chain to instance (sys_ca_certificate.list, type: CA Cert), wait for Publish Status "Active"
Upload leaf certificate to instance (sys_user_certificate.list), wait for Publish Status "Active"

MID Server Installation / Conversion

New MID: Run installer with mutual authentication option and PEM bundle path, OR
Existing MID: Invalidate, then run manage-certificates -a defaultsecuritykeypairhandle midserver-bundle.pem from the agent directory
Verify keystore contents with keytool
Start (new) or restart (existing) the MID Server service and validate the connection
Manually add capabilities to the MID Server record if this is a new installation
Note the certificate expiry date and set a renewal reminder (30+ days before expiry)

How To: Enable Mutual TLS (mTLS) Authentication Between a MID Server and the ServiceNow Instance

Overview

How MID Server mTLS Authentication Works

Prerequisites

Instance Requirements

MID Server Host Requirements

Certificate Authority Requirements

Network Requirements

Step 1: Generate a Certificate Signing Request (CSR)

Option A: OpenSSL (Linux, macOS, or Windows with OpenSSL)

Option B: certreq (Windows, Domain-Joined)

Step 2: Submit the CSR to Your CA and Obtain the Signed Certificate

Option A: certreq Submit (Windows, Domain-Joined)

Option B: ADCS Web Enrollment

Option C: Certification Authority MMC Snap-in

Step 3: Prepare the PEM Bundle

3a. Export the Certificate and Private Key

3b. Convert the Private Key to PKCS#8 Format

3c. Export the Root and Intermediate CA Certificates

Using certutil (Windows)

Using OpenSSL

3d. Assemble the PEM Bundle

Linux / macOS

Windows (PowerShell)

Windows (Command Prompt)

Step 4: Configure the ServiceNow Instance

4a. Upload the CA Certificate Chain

4b. Upload the MID Server's Leaf Certificate

4c. Certificate-to-MID Server Mapping: Shared vs. Unique Certificates

Step 5: Install the Certificate on the MID Server

Option A: New MID Server Installation with mTLS (Recommended)

Interactive Installation (Linux)

Silent Installation (Linux)

Windows Installation

Option B: Converting an Existing MID Server to mTLS

Invalidate the MID Server First

Install the PEM Bundle

Windows

Linux

Verify the Keystore Contents

Windows

Linux

Step 6: Basic Auth Credential Cleanup

Step 7: Restart and Validate

Restart the MID Server

Windows

Linux

Validate the MID Server

Certificate Expiry and Renewal

Monitoring Expiry

Windows

Linux

Renewal Process

CA Chain Rotation

Troubleshooting

Enable Debug SSL Logging

Useful manage-certificates Commands

Known Limitations

Quick Reference: End-to-End Checklist

Instance Preparation (Complete Before MID Server Installation)

Certificate Preparation

Instance Configuration

MID Server Installation / Conversion

References