Enable MID Server mutual authentication

---
title: Enable MID Server mutual authentication
description: Configure the MID Server to use a client certificate for authenticating to the instance. This avoids the need to create a basic authentication credentials in the Key Store for the MID Server's configuration.
locale: en-US
canonical_url: https://www.servicenow.com/docs/r/servicenow-platform/mid-server/install-mid-mutual-auth.html
release: brazil
product: MID Server
classification: mid-server
topic_type: task
last_updated: "2026-10-08"
reading_time_minutes: 12
breadcrumb: [Securing and encrypting MID Server data, MID Server, Manage instance data sources, Extend ServiceNow AI Platform capabilities]
---

# Enable MID Server mutual authentication

Configure the MID Server to use a client certificate for authenticating to the instance. This avoids the need to create a basic authentication credentials in the Key Store for the MID Server's configuration.

## Before you begin

Role required: admin

<table id="table_jjd_jmj_bpb"><tbody><tr><td>

![Set-up indicator for security phase](../image/ProgressBarSecure.png)

</td></tr></tbody>
</table>## About this task

MID Server mutual authentication removes the MID Server user name and password and provides a client certificate for authentication. Whenever a server requests authentication, this certificate is sent instead. To use mutual authentication, certificate based authentication must be enabled. See Set up Certificate-based authentication for the procedure.

If a new MID Server is created with mutual authentication, it does not add capabilities automatically. An administrator must add capabilities to its record on the instance. However, existing MID Servers using basic authentication with capabilities are preserved when switching to mutual authentication.

A MID Server using mutual authentication cannot be re-keyed or validated as a UI action on the instance.

Self-signed certificates are not supported with mutual authentication. Internally signed certificates are only supported when signed by a private certificate authority. Commercially signed certificates are supported when signed by a commonly trusted certificate authority, such as those trusted by browsers and operating systems.

The ServiceNow instance must be able to reach the certificate's OCSP and CRL endpoints. Certificate revocation checks require this access. An internally signed certificate whose OCSP or CRL endpoints are reachable only on an internal network is not supported, and validation fails. You cannot disable the CRL check selectively or suppress log messages for unreachable CRL endpoints.

In the Quebec release, a MID Server using the Health Log Analytic application cannot be configured with mutual authentication.

As a general guideline, use a unique mTLS certificate for each MID Server to limit the impact if a single certificate is compromised.

**Note:** Certificate-based authentication is not supported on On-Prem or edge encryption-enabled instances.

## Procedure

1.  Verify that the instance is set up with ADCv2 load balancers.

    Run the following command and check the response's `Server` header: `curl -I https://<instance>.service-now.com`

    -   If the `Server` header value is `snow_adc`, the instance is on ADCv2. Continue to the next step.
    -   If the value is anything else, the instance isn't on ADCv2. Contact ServiceNow Support to request migration to ADCv2 load balancers before you continue.
    For additional technical details and troubleshooting information, see [KB1116112](https://support.servicenow.com/kb?id=kb_article_view&sysparm_article=KB1116112).

2.  Obtain a certificate and private key from the certificate authority.

    RSA is the only supported key algorithm, and the key length must be 2048 bits. Keys shorter than 2048 bits fail validation with the error `Insufficient key length`.

    MID Server mutual authentication only supports the PEM bundle format and private key in PKCS\#8 format. The bundle must have both the private key and certificate. Open the certificate using a text editor and see if it is in text format. The header and footer of the PEM syntax is the following:

    ```
     -----BEGIN CERTIFICATE----- 
    ```

    ```
     -----END CERTIFICATE----- 
    ```

    \[Omitted image "install-mid-mutual-auth-bundle.png"\] Alt text: The bundle contains the correct formatting and both the private key and certificate.

    You can read the contents of a PEM certificate using the `openssl` command on Linux or Windows as follows: `openssl x509 -in cert.crt -text`. The private key must be in the PKCS\#8 format. The header and footer of the PKCS\#8 syntax is the following:

    ```
     -----BEGIN PRIVATE KEY----- 
    ```

    ```
     -----END PRIVATE KEY----- 
    ```

      You can check the contents of a private key using the `openssl` command on Linux or Windows as follows: `openssl rsa -in private.key -check`

    **Note:** If your certificate is not in PKCS\#8 format, you get an error: `- main SEVERE *** ERROR *** Could not find valid private key`

3.  Split up the PEM certificate into 3 different PEM files.

    1.  Private key and leaf certificate
    2.  Leaf certificate
    3.  Intermediate certificates and root certificate
4.  On the instance, upload file containing the intermediate and root certificates to the CA Certificate Chain table: **sys\_ca\_certificate.list**.

    **Note:** It is preferable to upload the root certificate and intermediate certificates as a single PEM bundle with the type set to CA Cert, rather than uploading them separately. If you choose to upload them individually, start with the root certificate followed by the intermediate certificates, and verify that the type is set to CA Cert for each, not Intermediate, as this is a platform requirement.

5.  Check the uploaded CA Cert record on the instance and wait for the **Publish Status** to change to **Exists**.

    **Warning:** Do not proceed until the publish status is updated to **Exists**.

6.  On the instance, navigate to **sys\_user\_certificate.list**.

7.  Attach only the leaf certificate to **sys\_user\_certificate.list** without including the private key.

8.  If the MID Server is validated, invalidate the MID Server before continuing.

9.  Create a new record.

    **Note:** The record must have the MID Server's name and the **User Role** must be **mid\_server**.

10. Attach the original, unsplit PEM certificate to the record.

    \[Omitted image "mid-mtls-user-cert-record.png"\] Alt text: The attachment is in the top corner of the record.

    **Note:** Ensure that the attached file contains only the certificate.

11. If the MID Server is running, stop the MID Server.

12. On the MID Server host machine, run the following commands to install and manage the certificate and private key.

    Run the script from the root of the agent directory because it requires the jar files in the class path. The security directory is then created in the agent root folder and is used by MID Server. For example: `bin\scripts\manage-certificates.bat -m.`

    The **manage-certificates** has the following functions and the scripts must be run from the agent folder.

    -   **Enable mutual authentication​**

        For Windows, use the command: `bin\scripts\manage-certificates.bat -m`

        For Linux, use the command: `./bin/scripts/manage-certificates.sh -m`

    -   **Remove mutual authentication and restore back basic authentication**

        For Windows, use the command: `bin\scripts\manage-certificates.bat -b <myUserName myPassword>`

        For Linux, use the command: `./bin/scripts/manage-certificates.sh -b <myUserName myPassword>`

    -   **Add new certificates and certificate chains with a specified alias​**

        For Windows, use the command: `bin\scripts\manage-certificates.bat -a <alias> <fileName>`

        For Linux, use the command: `./bin/scripts/manage-certificates.sh -a <alias> <fileName>`

        The `alias` is a unique name given to the certificate being imported. The MID Server requires a custom certificate for mutual authentication, with the default alias name `defaultsecuritykeypairhandle`. To configure MTLS communication between the MID Server and instance, the certificate entry must be added to the key store using the alias name `defaultsecuritykeypairhandle`.

        The `fileName` is the path to a PEM bundle file that contains one or more certificates and a private key in PKCS\#8 format. Include the private key and certificates in the following order:

        ```
         -----BEGIN CERTIFICATE-----
        Leaf certificate
        -----END CERTIFICATE-----
        
         -----BEGIN CERTIFICATE-----
        Intermediate certificate
         -----END CERTIFICATE-----
        
         -----BEGIN CERTIFICATE-----
         Root certificate
         -----END CERTIFICATE-----
        
         -----BEGIN PRIVATE KEY-----
         Private key
         -----END PRIVATE KEY----- 
        ```

        The private key can go at the top or the bottom of the file. If the file contains multiple certificates, order them as follows: leaf certificate, intermediate certificates, then root certificates. The system throws an exception if the certificate chain fails validation.

    -   **Display certificate details for the specified alias**

        For Windows, use the command: `bin\scripts\manage-certificates.bat -g <alias> ​`

        For Linux, use the command: `./bin/scripts/manage-certificates.sh -g <alias> ​`

        This command displays information such as subject distinguished name, issuer name, and expiry date from the certificate.

    -   **List all existing aliases**

        For Windows, use the command: `bin\scripts\manage-certificates.bat -l`

        For Linux, use the command: `./bin/scripts/manage-certificates.sh -l`

        This command lists all the alias names available in the **agent\_keystore**.

    -   **Delete certificates using an alias​**

        For Windows, use the command: `bin\scripts\manage-certificates.bat -d <alias>`

        For Linux, use the command: `./bin/scripts/manage-certificates.sh -d <alias>`

        This command deletes the alias and record from the keystore. The entry for alias **DefaultSecurityKeyPairHandle** can be deleted using this command.

    -   **Remove all entries from the keystore**

        For Windows, use the command: `bin\scripts\manage-certificates.bat -r ​`

        For Linux, use the command: `./bin/scripts/manage-certificates.sh -r ​`

        This command deletes the existing entries from the keystore, except alias **DefaultSecurityKeyPairHandle**. ​

13. Start the MID Server.


**Parent Topic:**[Securing and encrypting MID Server data](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/brazil/markdown/servicenow-platform/mid-server/mid-server-security-encryption.md)

**Related topics**  


[MID Server certificate check policies]()

[Encrypt or decrypt MID Server configuration file values]()

[MID Server configuration file security]()

[MID Server authentication methods comparison]()

[MID Server authentication credentials and SOAP requests]()

[MID Server unified key store]()

[MID Server Azure Key Vault integration]()

[MID Server command audit log]()

[Rekey a MID Server]()

[Add SSL certificates for the MID Server]()

[MID Server SSH cryptographic algorithms]()

[Attach a script file to a file synchronized MID Server]()

[MID Server FIPS Enforced Mode]()

[MID Server Governance]()

[MID Server IPKI authentication]()

[Install custom certificates in the MID Server unified key store](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/brazil/markdown/servicenow-platform/mid-server/mid-unified-keystore.md)

[MID Server unified key store](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/brazil/markdown/servicenow-platform/mid-server/mid-unified-keystore.md)