Splunk® Enterprise

Securing Splunk Enterprise

Acrobat logo Download manual as PDF


Acrobat logo Download topic as PDF

Configure Splunk Enterprise to use a common access card for authentication

On Splunk Enterprise version 9.0 and higher only, you can configure Splunk Web to use a certificate that comes on a common access card (CAC) to perform authentication for users of a Splunk Enterprise deployment. Authentication using CACs is not currently available on Splunk Cloud Platform deployments.

A common access card is a smart card that the United States Department of Defense (DoD) distributes to authorized personnel to grant access to its buildings, controlled spaces, computer systems, and networks, only for uses it authorizes. Each CAC is about the size of a credit card, and prominently lists a user's name, rank, service agency, and pay grade, among other information.

In the context of Splunk Enterprise, an authorized user can insert their CAC into a card reader that is connected to their DoD-authorized computer to authenticate into a Splunk Enterprise deployment that has been configured for authentication through CACs. When the user inserts the card and connects to the Splunk Enterprise instance, the browser retrieves the certificate from the card and presents it to Splunk Enterprise. When Splunk Enterprise receives the certificate, it logs the user in immediately, without displaying the login page that users without these certificates would normally see.

Prerequisites for using CACs to authenticate into Splunk Enterprise

Before you can use hardware to authenticate into a Splunk Enterprise instance, you must satisfy the following requirements. There are requirements for both the Splunk Enterprise instance on which you want to use hardware for authentication and the clients that connect to that instance to use that kind of authentication.

Client-side prerequisites

Every computer that is to access the Splunk Enterprise instance must have a card reader physically connected to the computer. Users must insert their CAC into the card reader to be able to access the Splunk Enterprise instance.

  • Every user of the instance must be in possession of a valid CAC
  • The CAC must have a valid certificate embedded in it
  • You must configure the client browser that is to access Splunk Web so that it uses the certificate on the CAC

There are many options to configure clients to use CACs. There are many different types of card readers that work on different operating systems and web browsers. Consult the documentation for the card reader that you use to install the correct hardware drivers and confirm that the web browser you use can see and access the CAC through the card reader.

Prerequisites for Splunk Enterprise

You must configure the Splunk Enterprise instance to use certificates on CACs in lieu of standard login credentials.

  • Every Splunk Enterprise deployment where you want to use hardware for authentication must use the lightweight directory access protocol (LDAP) as an authentication scheme. No other scheme type, including native authentication, works for this purpose
  • You must configure Splunk Web to use the HTTPS protocol to encrypt connections with clients
  • You must configure Splunk Web to require clients to authenticate themselves by presenting a valid certificate when they connect. This is known as mutually authenticated transport layer security (mutual TLS or mTLS), mTLS must be active for hardware-based authentication to work
    • The client certificate must be signed by the same certificate authority (CA) as either:
      • The certificates that you use to secure Splunk Web, or
      • If you do not use certificates to secure Splunk Web, the certificates that you use to secure the Splunk daemon
    • It is not necessary for a third party to issue the certificates
    • Certificate files that you reference in configuration files can contain multiple root CA certificates if you concatenate them beforehand

Configure encryption and secure settings for Splunk Web

To use hardware for authentication, configure encryption and secure operations on every machine in your Splunk Enterprise deployment that runs Splunk Web. This includes configuring Splunk Web to use mTLS for incoming connections from web clients.

The web.conf configuration file controls how Splunk Web handles and encrypts incoming connections from web clients on each instance in the deployment. The server.conf configuration file controls how the Splunk daemon handles and encrypts connections between various Splunk Enterprise nodes. You must use these configuration files to set up certificate based user authentication. It is not possible to use Splunk Web to perform this configuration.

This procedure assumes you have no encrypted communication between Splunk components and your web browser and establishes a root CA certificate path for communication between Splunk Web and hardware-based clients, which is a best practice. If you already have a root CA certificate for use in securing communications between Splunk Enterprise nodes, you can use that certificate as long as the same CA signed it. Some steps in the procedure might be optional, based on your current configuration.

Perform these procedures on the Splunk search heads where you want to configure Splunk Web to use CACs.

Ramifications of configuring secure settings for Splunk Web

After you configure Splunk Web to accept certificates, Splunk Web no longer displays the login screen. It is not possible to access Splunk Web on that node unless you insert a CAC with a valid certificate into a card reader that is connected to a machine that has a properly configured browser.

If you need to revert the configuration, you must either use the REST API to make modifications to the instance and restart it, or you must connect to the instance either physically or by using the SSH protocol.

Configure TLS communication between clients and Splunk Web

  1. Using a text editor, open the $SPLUNK_HOME/etc/system/local/server.conf file for editing. If this file does not exist, create it.
  2. Add the following lines to establish a root CA certificate path to ensure that communication between the machine that runs Splunk Web and the client uses TLS: 
    [SSLConfig]
SSLRootCAPath = <location of root CA certificate for HTTPS connections to the instance>
trustedIP = 127.0.0.1

    If a [SSLConfig] stanza already exists, add the lines under that stanza. Do not create a second [SSLConfig] stanza.

  3. Save the server.conf file and close it.

Configure mTLS communication between clients and Splunk Web and enable card-based authorization

  1. Open the $SPLUNK_HOME/etc/system/local/web.conf file for editing. If this file does not exist, create it.
  2. Add the following line to the [settings] stanza to enable SSL for incoming connections to Splunk Web:
    [settings]
enableSplunkWebSSL = true

    If a [settings] stanza already exists, add the lines under that stanza. Do not create a second [settings] stanza.

  3. Add the following lines to the [settings] stanza to ensure that any client that connects to the Splunk Web instance must present a valid certificate. This ensures that communication from the client to the server is mutually authenticated (mTLS):: 
    [settings]
requireClientCert = true
sslRootCAPath = <location of the second root CA certificates to authenticate clients connecting to the instance>
  4. Add the following line to let the instance authenticate users using only the certificates they present on their CACs:
    [settings]
enableCertBasedUserAuth = true
  5. Add the following lines to control how Splunk Web handles single sign-on web requests: 
    [settings]
SSOMode = permissive
trustedIP = 127.0.0.1
  6. Save the web.conf file and close it.
  7. Restart the Splunk Enterprise instance.
Last modified on 05 May, 2022
PREVIOUS
Troubleshoot reverse-proxy SSO 		  NEXT
Set up user authentication with external systems

This documentation applies to the following versions of Splunk® Enterprise: 9.0.0

Was this documentation topic helpful?


You must be logged into splunk.com in order to post comments. Log in now.

Please try to keep this discussion focused on the content covered in this documentation topic. If you have a more general question about Splunk functionality or are experiencing a difficulty with Splunk, consider posting a question to Splunkbase Answers.

0 out of 1000 Characters