Configure Splunk Enterprise to use a common access card for authentication

On Splunk Enterprise version 9.0.2 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 normally see.

There are several configurations that you can use on the Splunk Enterprise instance to extract LDAP credential information from the CAC, depending on how you want to extract the credentials from the card.

Prerequisites for using CACs to authenticate into Splunk Enterprise

Before you can use CACs 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 CACs for authentication and the clients that connect to that instance to use that kind of authentication.

Client-side prerequisites for CAC-based authentication

Every computer that is to access the Splunk Enterprise instance must have a card reader that is physically connected to the computer. Users must insert their CAC into the card reader 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.

Splunk Enterprise prerequisites for CAC-based authentication

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 a CAC for authentication must use the lightweight directory access protocol (LDAP) as its authentication scheme. No other scheme type, including native authentication, works for this purpose
  • See Set up user authentication with LDAP to configure the scheme and connect the LDAP server to the Splunk Enterprise deployment
  • See Map LDAP groups to Splunk roles in Splunk Web to understand how to map LDAP groups to Splunk roles.
• 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 CAC-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 CACs 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 together to set up CAC-based user authentication. It is not possible to use Splunk Web to perform this configuration.

The following table describes the settings that determine the credential extraction method.

Setting name	Configuration file	Description
sslRootCAPath	web.conf	The location of the root CA (Certificate Authority) certificate store on the operating system. The value for this setting must refer to a file that is in PEM (Privacy-Enhanced Mail) format and that contains one or more root CA certificates. Multiple certificates must be concatenated. There is no default for this setting.
enableSplunkWebSSL	web.conf	Whether or not Splunk Web uses the HTTPS protocol for incoming connections from web clients. This is a requirement for CAC-based authentication. The default value for this setting is false.
requireClientCert	web.conf	Whether or not Splunk Web requires web clients to present a valid certificate upon initial connection. This is a requirement for CAC-based authentication. The default value for this setting is false.
enableCertBasedUserAuth	web.conf	Whether or not Splunk Web uses certificates to authenticate. This is a requirement for CAC-based authentication. The default value for this setting is false.
ssoMode	web.conf	The mode in which Splunk Web operates in the context of the single sign-on authentication method. It can operate either in strict mode or permissive mode. In permissive mode, Splunk Web redirects requests that originate from an untrusted IP address to a login page where users can log into Splunk Web without using SSO. In strict mode, Splunk Web restricts all requests to those that originate from a trusted IP address, except to endpoints that do not require authentication. The default value for this setting is strict, but you must use permissive for the purposes of CAC authentication.
trustedIP	server.conf, web.conf	One or more IP addresses that Splunk Web uses to validate that it is receiving data from proxy hosts for single sign-on requests. In the server.conf file, this setting establishes incoming trust by configuring the Splunk Enterprise instance to trust login requests from the local machine. In the web.conf file, this setting establishes an outgoing trust by configuring the Splunk Enterprise instance to trust a proxy, in this case, the local instance, to perform single sign-on. There is no default value, but you must use 127.0.0.1 for the purposes of CAC authentication.

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 CAC-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 the certificates that are in the CACs. 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 enabling CAC-based authentication for Splunk Web

After you configure Splunk Web to accept certificates using common access cards on an instance, it no longer displays the login screen for authentication. It is not possible to access Splunk Web on that instance 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 instance to display the login screen again, you must either connect to the instance physically or by using the SSH protocol and edit configuration files, or use the REpresentational State Transfer (REST) API to make modifications to the instance and restart it. See "Disable CAC-based authentication in Splunk Enterprise" later in this topic for specific details.

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:

   [general]
   trustedIP = 127.0.0.1
   
   [SSLConfig]
   SSLRootCAPath = <location of the root CA certificate for HTTPS connections to the instance>
   

   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 authentication

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 root CA certificate to authenticate web clients connecting to Splunk Web, overrides the setting in server.conf>
   

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. Add the following lines to control how Splunk Enterprise extracts the credentials from the CAC. For more information about these settings, see "Configure how Splunk Enterprise extracts credential information from a CAC" later in this topic:

   [settings]
   certBasedUserAuthMethod = <string>
   certBasedUserAuthPivOidList = <string>
   

7. Save the web.conf file and close it.
8. Restart the Splunk Enterprise instance.

Configure how Splunk Enterprise extracts credential information from a CAC

There are several options that Splunk Enterprise can use to extract LDAP credential information from the certificate on a CAC:

• The entire Common Name field from the certificate
• The Electronic Data Interchange Personal Identifier (EDIPI) from the Common Name field in the certificate. To extract LDAP information using the EDIPI, the Common Name must contain segments that are separated by dots, and the string "EDIPI" must be the last segment. An example of an acceptable EDIPI is "FirstName.MiddleName.Lastname.EDIPI".
• The Personal Identity Verification (PIV) identifier from the Subject Alternate Name (SAN) extension in the certificate The PIV is a 20-character alphanumeric string that has a typical format of xxxxxxxxxxxxxxxx@mil. Splunk Enterprise extracts the PIV from the "Other Name" field of the Subject Alternate Name extension within the CAC certificate. The field corresponds to one of the object identifiers (OIDs) that you supply as part of the credential extraction configuration.

Before LDAP credential extraction from CACs can work, you must have already activated CAC configuration by performing the steps that appear earlier in this topic:

• Configure Splunk Enterprise to use LDAP as an authentication scheme
• Configure Splunk Enterprise to use CACs for authentication
• Configure mTLS communication between CAC clients and Splunk Web

The web.conf configuration file controls how Splunk Enterprise extracts credential information. The following table describes the settings that determine the credential extraction method.

Setting name	Description
certBasedUserAuthMethod	Controls how Splunk Enterprise extracts LDAP-based credentials from the common access card when you insert the card into your computer card reader and subsequently connect to the instance. The following values are valid: CommonName: Uses the value that is in the Common Name field of the certificate in its entirety. EDIPI: Uses the EDIPI from the certificate Common Name field. This is a subset of the entire Common Name field. PIV: Uses the PIV identifier from the "Other Name" field of the Subject Alternate Name certificate extension, which corresponds with one of the OIDs that you configure for the purposes of looking up a person's PIV. If you give this setting a value of "PIV", then Splunk Enterprise also uses the value you set in certBasedUserAuthPivOidList to perform the credential extraction. There is no default for this setting, which means that if you don't configure it, LDAP certificate extraction won't happen.
certBasedUserAuthPivOidList	Controls the list of OIDs that Splunk Enterprise uses to look up a person's PIV identifier. For each OID you add to this list, Splunk Enterprise looks in the CAC certificate for a matching OID that contains a value. If the matched OID does contain a value, then Splunk Enterprise uses the value in the OID to log the user in. The setting can take more than one OID as a value. Separate multiple values with commas. The default value for this setting is 1.3.6.1.4.1.311.20.2.3, Microsoft Universal Principal Name. If you don't set any OIDs, Splunk Enterprise attempts credential extraction with these values.

Confirm that CAC-based authentication works

1. Insert a valid CAC into a card reader that is attached to a computer that can access the Splunk Enterprise instance.
2. On the web browser on the computer, visit the Splunk Enterprise site that has been configured to use CACs for authentication. If authentication works as expected, the Splunk Enterprise home screen loads immediately.

If the home screen doesn't load immediately upon card insertion, then there is a problem with either the card or the configuration.

• If the card does not contain a valid certificate, then Splunk Web rejects the connection and the browser displays a "Connection Refused" page.
• If the card is valid, but the user is not authorized, then Splunk Web displays a "Not authorized" page. Confirm that the card is not broken and has a valid certificate for the user who possesses it.
• If there is a problem with the configuration, such as a certificate mismatch, then the assumption is that the user doesn't have authorization to access the instance, and the web browser displays a connection error. Review the Splunk Enterprise configuration and that the instance references the correct root certificate authority certificate and certificate credential extraction method.

Disable CAC-based authentication in Splunk Enterprise

When you enable authentication with common access cards, Splunk Web on configured instances can no longer display the login page on that instance. This is because Splunk Web expects, and can only accept, a valid certificate that is on a CAC, and pulls the credentials from there.

If you want to turn off authentication using CACs, you have two options:

• Connecting to the instance physically or by using the SSH protocol, and then editing the web.conf file to disable CAC-based authentication
• Connecting to the instance using the REST API and making the change to the web.conf configuration that way

Disable CAC-based authentication by editing configuration files

1. Connect to the Splunk Platform instance either physically or by using the SSH protocol.
2. Open the $SPLUNK_HOME/etc/system/local/web.conf file for editing.
3. Under the [settings] stanza, remove references to the following settings:
   • requireClientCert
   • enableCertBasedUserAuth
   • certBasedUserAuthMethod
   • certBasedUserAuthPivOidList
   • SSOMode
   • TrustedIP
4. (Optional) You can also remove other secure settings for Splunk Web if you want by removing references to the sslRootCAPath and enableSplunkWebSSL settings from the web.conf file.
5. Save the web.conf file and close it.
6. (Optional) If you want to remove the secure settings for the Splunk Enterprise instance also, complete the following steps:
   1. Open the $SPLUNK_HOME/etc/system/local/server.conf file for editing.
   2. Remove the sslRootCAPath and trustedIP settings from the [SSLConfig] stanza that you previously added.
   3. Save the server.conf file and close it.
7. Restart the Splunk Enterprise instance.
8. Access the instance and confirm that the login screen appears.

Disable CAC-based authentication by using the REST API

You must have a minimum of network access and a Splunk user that holds an administrator role on the Splunk Enterprise instance where you want to disable CAC-based authentication.

Alternatively, if you connect physically to the instance, you can substitute <server> in the following commands with the word localhost.

1. Open a shell prompt or PowerShell window.
2. Using the curl web data transfer tool, connect to the instance where you want to disable CAC-based authentication and change the following settings:

   curl -u <user>:<password> -X POST https://<server>:8089/servicesNS/nobody/search/configs/conf-web/settings -d requireClientCert=false
   curl -u <user>:<password> -X POST https://<server>:8089/servicesNS/nobody/search/configs/conf-web/settings -d enableCertBasedUserAuth=false
   curl -u <user>:<password> -X POST https://<server>:8089/servicesNS/nobody/search/configs/conf-web/settings -d certBasedUserAuthMethod=
   curl -u <user>:<password> -X POST https://<server>:8089/servicesNS/nobody/search/configs/conf-web/settings -d certBasedUserAuthPivOidList=
   

For more information on using the REST API to manipulate configurations on Splunk Enterprise instances, see the

Fore more information

• For a more detailed explanation of configuring encryption between Splunk Web and your browser, which this procedure accomplishes as part of setting up certificate-based authentication, see About securing Splunk Web and Turn on encryption (https) using web.conf.
• For additional information on the settings that you need to configure for the web.conf configuration file, see the web.conf configuration specification file.