Configure communication and bundle download authentication for deployment servers and clients

You can enhance the security between Splunk platform deployment clients and servers by changing a configuration file so that deployment servers and clients perform authentication checks when they communicate with one another, as well as when deployment clients download configuration bundles. These enhancements further secure your deployment by ensuring that deployment clients accept handshake, subscription, and heartbeat messages only from deployment servers.

The restmap.conf configuration file controls authentication enhancement. You can configure authentication only by editing the configuration file and specifying the appropriate setting and value. This means you can only perform this configuration on Splunk Enterprise, or on collection and forwarding infrastructure for Splunk Cloud Platform that you manage.

The requireAuthentication setting controls the authentication feature. When you give this setting a value of "true", deployment clients verify messages that they receive from deployment servers during the handshake, channel subscription, and heartbeat phases of their sessions. If these kinds of messages do not appear to have originated from a deployment server, then the deployment client drops the message and does not process it.

Prerequisites to configuring authentication between deployment servers and clients

You must satisfy the following requirements before you can configure authentication between deployment servers and clients:

• All Splunk platform instances where you want to enable authentication of communications and bundle downloads between deployment servers and clients must run Splunk Enterprise or universal forwarder versions 8.1.10.1 and higher, 8.2.6.1 and higher, or 9.0.0 and higher.
  • You must at least upgrade deployment servers to these versions or higher. This enables mutual authentication for connections between deployment servers and clients.
  • For mutual authentication for bundle downloading to be available, you must also upgrade deployment clients to these versions or higher.
• You must have configured your deployment servers and deployment clients with a pass4symmKey. Typically, you configure a pass4SymmKey in the [general] or [deployment] stanzas in the server.conf configuration file, but your specific configuration might differ. For more information on how to configure pass4SymmKeys, see Secure Splunk Enterprise services with pass4SymmKey.

Additional securement configurations

While the following items are not a specific requirement for configuring bundle download and handshake authentication, having them in place greatly increases the security of your deployment servers and clients.

• Secure your Splunk platform instances with valid, current certificates that you either created or obtained from a third party. The certificates cannot be the ones that Splunk ships with Splunk platform installation packages. See What is a valid certificate? for specifics on what a valid certificate is.
• Install the certificates on all Splunk platform instances in your deployment. The configuration for each instance must reference the correct certificates.

Configure communication and bundle download authentication between deployment servers and clients

Before you attempt to configure authentication between deployment servers and clients, confirm you have met all the requirements to do so. You can only configure authentication using configuration files. It is not possible to do this using Splunk Web.

The authKeyStanza value in this procedure assumes you have configured the pass4symmKey in the [deployment] stanza of the server.conf configuration file. If you have configured it in another stanza within the file, set the value for authKeyStanza to that stanza.

1. Confirm that you have installed the certificates on all your Splunk platform instances.
2. On the deployment server, edit the $SPLUNK_HOME/etc/system/local/restmap.conf configuration file.
3. In the restmap.conf file, add the following settings and values to enable communication and bundle download authentication:
   

   [broker:broker]
   authKeyStanza=deployment
   requireAuthentication = true
   
   [streams:deployment]
   authKeyStanza=deployment
   requireAuthentication = true
   

   
   

   If these stanzas already exist in the file, add the settings and values under the existing stanzas. Do not add new stanzas.

4. Restart the deployment server. It is not possible to reload this configuration.
5. Monitor the splunkd.log log files on deployment clients to confirm that there are no errors like the following:
   

   Error message	What it means
   Received message that did not originate from deployment server, ignoring. connectionId=\"%s\"	The deployment client received a message that did not come from a deployment server and ignored the message.
   Phonehome from connectionId=\"%s\" attempted to publish to a restricted channel, channel=	The deployment server received a message from a deployment client that attempted to publish itself to a channel to which it wasn't authorized.