Skip to main content
Lantern Home
 
 
Splunk Lantern

Configuring Splunk for Common Access Card (CAC) authentication

  1. Last updated
  2. Save as PDF

 

This article contains detailed guidance on how to configure any Splunk Enterprise instance to allow access via a Department of Defense Common Access Card (CAC). It walks you through how to do this through completing the following steps:

  1. Secure communications between Splunk Enterprise users and Splunk web
  2. Configure LDAP authentication
  3. Map LDAP groups to Splunk roles
  4. Switch from Splunk’s standard authentication to CAC-enforced authentication

You can also review the key configuration files.

Preparation

Note the following before proceeding:

  • Splunk introduced native support for CAC authentication with Splunk Enterprise version 9, but prior to that, a proxy server was required to verify CAC credentials on behalf of Splunk.
  • The Splunk Enterprise instance of CAC authentication may differ from Splunk's published instructions. This article provides detailed information on the configuration, with an emphasis on items not found in Splunk's official documentation.
  • All procedures outlined in these instructions can only be performed by Splunk and Windows administrators.
  • The procedures in this guide show how CAC authentication was achieved in a real-life, specific Splunk Enterprise environment. You might need to adjust some of the commands, parameters, and field names shown to match your environment. Some details of the environment used in this environment have been removed for security reasons, and you will need to adjust these.

1. Secure communications between Splunk Enterprise users and Splunk web

All communications between Splunk Enterprise users and the Splunk instance must be secured using Transport Layer Security (TLS). TLS requires the use of certificates installed on the Splunk Enterprise server and embedded in the users’ CAC cards. Both the server certificate and any user certificates must be issued by the same Certificate Authority (CA).

$SPLUNK_HOME refers to the directory where the main Splunk Enterprise program is installed. For the Splunk instance used in this example, this refers to E:\program files\splunk\.

  1. Request a server certificate. Implement the following commands from a command prompt on the Splunk Enterprise server:

    Action Command
    Generate a private key $SPLUNK_HOME\bin\splunk cmd openssl genrsa -des3 -out mySplunkWebPrivateKey.key 2048
    Remove the password from the private key $SPLUNK_HOME\bin\splunk cmd openssl rsa -in mySplunkWebPrivateKey.key -out mySplunkWebPrivateKey.key
    Generate a Certificate Signing Request (CSR) $SPLUNK_HOME\bin\splunk cmd openssl req -new -key mySplunkWebPrivateKey.key -out mySplunkWebCert.csr

  2. Send the CSR (mySplunkWebCert.csr) to the administrators who are responsible for requesting server certificates on behalf of the Splunk team.

  3. Wait for the server certificates to be returned. The server certificates could be delivered in a variety of formats, for example, PKCS #7 format. Splunk requires all certificates be converted to “Privacy Enhanced Mail” (PEM) format, which you can do with the following commands:

    Action Command
    Convert server certificate from PKCS #7 to PEM $SPLUNK_HOME\bin\splunk cmd openssl pkcs7 -print_certs -in server_certificate.p7b -out cert.pem
    Convert server private key to PEM $SPLUNK_HOME\bin\splunk cmd openssl x509 -in mySplunkWebPrivateKey.key -out privkey.pem

  4. Transfer the cert.pem (public key) and privkey.pem (private key) files on the Splunk server. These files make up the public/private key pair used by the Splunk server to secure web traffic between itself and Splunk web users. The SSL certificate files are issued by the DOD and are normally located under a path that will look similar to $SPLUNK_HOME\etc\auth\DOD.web.certificates.

  5. Splunk maintains a file that contains the path of the root Certificate Authority that issued its server certificate. This certificate chain consists of a concatenated list of the Splunk server’s certificate, all intermediary certificates, and the root CA certificate (in that order). This file is referenced by the sslRootCAPath variable in web.conf. With the cert.pem, privkey.pem, and certificate chain in place, the following entries can be added to $SPLUNK_HOME/etc/system/local/web.conf to secure communications between Splunk users and Splunk web. Adjust the file paths according to your environment.

    [settings]
### START SPLUNK WEB USING HTTPS:8443 ###
enableSplunkWebSSL = 1
httpport = 8443
### SSL CERTIFICATE FILES ###
privKeyPath = $SPLUNK_HOME\etc\auth\DOD.web.certificates\privkey.pem
serverCert =  $SPLUNK_HOME\etc\auth\DOD.web.certificates\cert.pem
sslRootCAPath = $SPLUNK_HOME\etc\auth\DOD.web.certificates\cert_chain_created_20230113.pem

Additional information for implementing TLS certificates on the Splunk server is available in Splunk Docs: Introduction to securing the Splunk platform with TLS.

2. Configure LDAP authentication

By default, Splunk uses its native authentication, which means Splunk users log into Splunk with a username and password, both stored on the Splunk server itself. Most [removed for security reasons] information systems require centralized authentication via Microsoft’s Active Directory.

This section shows the steps you need to follow to partially transition to centralized authentication using the Lightweight Directory Access Protocol (LDAP).

Additional information for configuring LDAP authentication is available in Splunk Docs: Set up user authentication with LDAP.

  1. From the Splunk Enterprise top line menu, click Settings > Authentication Methods > LDAP > Configure Splunk to use LDAP > Add new LDAP (or edit existing) to view the following page:

  2. Choose whether to update the settings manually or paste all of the values intoauthentication.conf.
    • Update the settings manually.

      If you've chosen to update the settings manually, enter the values for the settings as follows:

      • Host: This should be a Fully Qualified Domain Name (FQDN) which is resolved to an IP address by a DNS server.
      • Port: In this example, port 636 was chosen to enforce secure communications between Splunk Enterprise and the Domain Controller.
      • Bind DN: This value contains the “Distinguished Name” of the service account used by Splunk Enterprise to query Active Directory. LDAP uses DN values to reference user accounts, groups, and all other directory objects.
      • Bind DN Password: This value is used in combination with the Bind DN to authenticate to Active Directory.
      • User Base DN: This value tells Splunk Enterprise where all user accounts are located. Fill this in with your Base DN information.
      • Group Base DN: This value tells Splunk Enterprise where all security groups are located. Fill this in with your Splunk Security groups.
      • All other values must be entered as follows:
        1. User name attribute = userprincipalname
        2. Real name attribute = cn
        3. Email attribute = mail
        4. Group mapping attribute = dn
        5. Group name attribute = cn
        6. Static member attribute = member
    • Paste the values into authentication.conf.

      If you've chosen to paste all of the values into $SPLUNK_HOME\etc\system\local\authentication.conf, copy the following and paste it in:

      [authentication]
authSettings = **** LDAP Connection
authType = LDAP
[**** LDAP Connection]
SSLEnabled = 1
anonymous_referrals = 0
bindDN = [bindDN]
bindDNpassword = [bindDNpassword]
charset = utf8
emailAttribute = mail
enableRangeRetrieval = 0

groupBaseDN = [groupBaseDN] 
groupMappingAttribute = dn
groupMemberAttribute = member
groupNameAttribute = cn
host = [host]
nestedGroups = 0
network_timeout = 20
pagelimit = -1
port = 636
realNameAttribute = cn
sizelimit = 1000
timelimit = 15
userBaseDN = [userBaseDN]
userNameAttribute = userprincipalname

3. Map LDAP groups to Splunk roles

  1. From the top line menu, select Settings and Authentication Methods > LDAP Settings. Under LDAP Strategies, select Map groups (to the right of LDAP Connection).

  2. Map the settings manually or implement them inauthentication.conf.
    • Map the settings manually.

      If you've chosen to map the settings manually, click the group names to see which Splunk roles they are currently mapped to, and make any adjustments needed.

      • The LDAP group names are populated from Active Directory.
      • The “DoD” security group has basic user permissions in Splunk Enterprise (including access to the Alert Manager app).
      • The “LDAP Users” field should be populated with user accounts for both security groups. If this field is blank, this may indicate an issue connecting with Active Directory.
    • Implement via authentication.conf.

      If you've chosen to implement the mappings via $SPLUNK_HOME\etc\system\local\authentication.conf, copy and paste the following, adjusting it according to your environment.

      Additional guidance on mapping Windows security groups to Splunk roles is available in Splunk Docs: Map LDAP groups to Splunk roles in Splunk Web.

      [roleMap_ LDAP Connection]
admin = [admin]
user = [user]

4. Switch from the Splunk native authentication to CAC-enforced authentication

With all certificate and LDAP configurations in place, update $SPLUNK_HOME/etc/system/local/web.conf to enforce CAC authentication to Splunk web.

After these settings are applied, users will no longer see the traditional Splunk Enterprise log on screen and will only be prompted for the authentication certificate from their CAC card. If there is an issue with the server certificates or any configuration files, users will not be able to access Splunk web. To restore access, an administrator will need to revert the following changes on the file system and restart Splunk Enterprise.

  1. Add the following settings, adjusting the sslRootCAPath according to your environment, to the [settings] stanza of $SPLUNK_HOME/etc/system/local/web.conf:

    [settings]

requireClientCert = true
sslRootCAPath = $SPLUNK_HOME\etc\auth\DOD.web.certificates\cert_chain_created_.pem
enableCertBasedUserAuth = true
SSOMode = permissive
trustedIP = 127.0.0.1
certBasedUserAuthMethod = PIV 
certBasedUserAuthPivOidList = Microsoft Universal Principal Name
allowSsoWithoutChangingServerConf = 1
  2. Restart Splunk Enterprise. After restarting, users should be prompted for their CAC card on their next login attempt.

Key configuration files

Configuration entries related to CAC authentication have been bolded.

<SPLUNK_HOME>/etc/system/local/web.conf

[settings]

### START SPLUNK WEB USING HTTPS:8443 ###
enableSplunkWebSSL = 1
httpport = 8443

### SSL CERTIFICATE FILES ###
privKeyPath = $SPLUNK_HOME\etc\auth\DOD.web.certificates\privkey.pem
serverCert =  $SPLUNK_HOME\etc\auth\DOD.web.certificates\cert.pem   

### CAC AUTHENTICATION ###
requireClientCert = true
sslRootCAPath = $SPLUNK_HOME\etc\auth\DOD.web.certificates\cert_chain_created_[removed for security reasons].pem
enableCertBasedUserAuth = true
SSOMode = permissive
trustedIP = 127.0.0.1
certBasedUserAuthMethod = PIV 
certBasedUserAuthPivOidList = Microsoft Universal Principal Name
allowSsoWithoutChangingServerConf = 1
  • privKeyPath contains the location of the Splunk server’s private key.
  • serverCert contains the location of the Splunk server’s public key. This key must be signed by the same certificate authority as the user’s CAC card.
  • sslRootCAPath contains the path to the root Certification Authority (CA).
  • certBasedUserAuthPivOidList contains the Object Identifier used to locate the Personal Identity Verification number on the user’s CAC card. The setting of “Microsoft Universal Principal Name” does not conform to Splunk’s documentation, but it is a valid configuration.

<SPLUNK_HOME>/etc/system/local/authentication.conf

[splunk_auth]
minPasswordLength = 8
minPasswordUppercase = 0
minPasswordLowercase = 0
minPasswordSpecial = 0
minPasswordDigit = 0

[authentication]
authSettings = LDAP Connection
authType = LDAP

[roleMap LDAP Connection]
admin = [admin]

[LDAP Connection]
SSLEnabled = 1
anonymous_referrals = 0
bindDN = [bindDN]
bindDNpassword = [bindDNpassword]
charset = utf8
emailAttribute = mail
enableRangeRetrieval = 0
groupBaseDN = [groupBaseDN]
groupMappingAttribute = dn
groupMemberAttribute = member
groupNameAttribute = cn
host = ***.***.***.***
nestedGroups = 0
network_timeout = 20
pagelimit = -1
port = 636
realNameAttribute = cn
sizelimit = 1000
timelimit = 15
userBaseDN = [userBaseDN]
userNameAttribute = userPrincipalName

<SPLUNK_HOME>/etc/system/local/server.conf

[general]
serverName = [servername]
pass4SymmKey = [pass4SymmKey]
trustedIP = 127.0.0.1

[sslConfig]
sslPassword = [sslPassword]
requireClientCert = false  

[lmpool:auto_generated_pool_enterprise]
description = auto_generated_pool_enterprise
quota = MAX
slaves = *
stack_id = enterprise

[kvstore]

Next steps

These resources might help you understand and implement this guidance: