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:
- Secure communications between Splunk Enterprise users and Splunk web
- Configure LDAP authentication
- Map LDAP groups to Splunk roles
- Switch from Splunk’s standard authentication to CAC-enforced authentication
You can also review the key configuration files.
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
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
Send the CSR (
mySplunkWebCert.csr) to the administrators who are responsible for requesting server certificates on behalf of the Splunk team.
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
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 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
web.conf. With the
privkey.pem, and certificate chain in place, the following entries can be added to
$SPLUNK_HOME/etc/system/local/web.confto 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.
- 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:
- Choose whether to update the settings manually or paste all of the values into
- 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:
- User name attribute =
- Real name attribute =
- Email attribute =
- Group mapping attribute =
- Group name attribute =
- Static member attribute =
- User name attribute =
- Paste the values into
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
- Update the settings manually.
3. Map LDAP groups to Splunk roles
- From the top line menu, select Settings and Authentication Methods > LDAP Settings. Under LDAP Strategies, select Map groups (to the right of LDAP Connection).
- Map the settings manually or implement them in
- 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
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]
- Map the settings manually.
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.
Add the following settings, adjusting the
sslRootCAPathaccording to your environment, to the
[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
- 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.
[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
privKeyPathcontains the location of the Splunk server’s private key.
serverCertcontains 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.
sslRootCAPathcontains the path to the root Certification Authority (CA).
certBasedUserAuthPivOidListcontains 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_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
[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]
These resources might help you understand and implement this guidance:
- Splunk Docs: Configure Splunk Enterprise to use a common access card for authentication
Splunk OnDemand Services: Use these credit-based services for direct access to Splunk technical consultants with a variety of technical services from a pre-defined catalog. Most customers have OnDemand Services per their license support plan. Engage the ODS team at OnDemand-Inquires@splunk.
com if you require assistance.