Configure mTLS authentication for a MID Web Server

Enhance security in your MID Web Server extension by enabling mTLS authentication.

Before you begin

Ensure that you have enabled Transport Layer Security (TLS) on the agent. For details, see Connect the agent to the MID Server using mTLS.

Ensure that the insecure-skip-tls-verify parameter in the acc.yml configuration file is set to false. For details on the acc.yml file, see Configuration file options.

Note:

This procedure includes commands for both CentOS 7/Linux and Windows Server environments. Select the commands relevant for your host operating system. If working with another Linux distribution, adapt the commands as needed for your specific OS.

Role required: agent_client_collector_admin

About this task

The MID Web Server extension searches the following locations (in the specified order) to access the truststore location and password:

• Truststore location: The mid.webserver.truststore.path JVM system property.

  If that property is empty, the extension retrieves the location from the javax.net.ssl.trustStore JVM system property.

  If no location is specified, the truststore location defaults to the absolute path of the cacerts file of the JRE running the MID Server.

• Truststore password: The Truststore Password field on the extension form in the instance.

  If that field is empty, the system retrieves the password from the javax.net.ssl.trustStorePassword JVM system property.

  If no location is specified, the password defaults to changeit.

Procedure

1. In a Linux environment:
   1. Navigate to the root folder of your MID Server.
   2. Run the following command to add your certificate to the MID trust store:

      ./jre/bin/keytool -importcert -file /etc/pki/ca-trust/source/anchors/labcacert.pem -destkeystore ./jre/lib/security/cacerts -alias mtlsca

   3. Enter changeit when prompted for a password.
   4. Select yes on the confirmation message window to indicate that you trust the certificate.
   5. Run the following command to verify that your certificate was successfully added to the MID trust store:

      ./jre/bin/keytool -list -keystore ./jre/lib/security/cacerts -alias mtlsca

   6. Enter changeit when prompted for a password.
   7. In the MID Server wrapper override configuration file (wrapper-override.conf, located in the conf directory under the MID Server's home directory), configure the revocation of client certificates using the mid.webserver.cert.revocation.check.enabled property.

      If you have a custom internal certificate, set it to false by adding the following line to conf/wrapper-override.conf on the MID Server:

      wrapper.java.additional.4=-Dmid.webserver.cert.revocation.check.enabled=false

      When enabling this property (true), configure the mid.webserver.ocsp.responder.url property with the OCSP responder URL. This value overrides any URL embedded in the certificate.

   8. If you have changed properties in the wrapper override configuration file, restart the MID Server.
   9. Access the MID Server record on your ServiceNow instance and change the value of the Authentication type field to mTLS.
   10. Restart the MID Web Server.
   11. Verify that the MID Web Server and websocket endpoint are up and running.
2. In a Windows environment:
   1. Navigate to the root folder of your MID Server.
   2. Run the following command to add your certificate to the MID trust store:

      jre\bin\keytool.exe -importcert -file <path>\labcacert.pem -destkeystore jre\lib\security\cacerts -alias mtlsca

   3. Enter changeit when prompted for a password.
   4. Select yes on the confirmation message window to indicate that you trust the certificate.
   5. Run the following command to verify that your certificate was successfully added to the MID trust store:

      jre\bin\keytool.exe -list -keystore jre\lib\security\cacerts -alias mtlsca

   6. Enter changeit when prompted for a password.
   7. In the MID Server wrapper override configuration file (wrapper-override.conf, located in the conf directory under the MID Server's home directory), configure the revocation of client certificates using the mid.webserver.cert.revocation.check.enabled property.
      • If you have a custom internal certificate, set it to false by adding the following line to conf\wrapper-override.conf on the MID Server:

        wrapper.java.additional.4=-Dmid.webserver.cert.revocation.check.enabled=false

      • When enabling this property (true), configure the mid.webserver.ocsp.responder.url property with the OCSP responder URL. This value overrides any URL embedded in the certificate.
   8. If you changed properties in the wrapper override configuration file, restart the MID Server using one of the following methods:
      • Windows Services app
      • Command line using the MID Server's configured service name:

        net stop AgentClientCollector
        net start AgentClientCollector

   9. Access the MID Web Server record on your ServiceNow instance and change the value of the Authentication type field to mTLS.
   10. Restart the MID Web Server.
   11. Verify that the MID Web Server and websocket endpoint are up and running.

What to do next

Connect the agent to the MID Server using mTLS.