6.1 Integrating Splunk with LDAP

LDAP Authentication in Splunk Enterprise

Blueprint domain 6 covers integrating Splunk with LDAP, the other user authentication options, and the steps to enable multifactor authentication. This section covers the authentication framework and LDAP. The next section covers SAML, scripted authentication, ProxySSO, and MFA.

Authentication Architecture in authentication.conf

The authentication subsystem is orchestrated through $SPLUNK_HOME/etc/system/local/authentication.conf. The core [authentication] stanza declares the active authentication mode and the resolution chain:

[authentication]
authType = LDAP
authSettings = corp_ad_primary,corp_ad_dr

Supported Authentication Types (authType)

1. Splunk: Native local authentication. Splunk validates credentials against hashes stored in $SPLUNK_HOME/etc/passwd.
2. LDAP: Splunk queries external directory services over LDAP or LDAPS protocols, binding with a service account and verifying credentials against directory trees.
3. SAML: Splunk delegates authentication to an external Identity Provider (IdP) using the SAML 2.0 federated protocol.
4. Scripted: Custom external authentication through a script you supply.
5. ProxySSO: A reverse proxy authenticates the user and passes the identity to Splunk.

Precedence of Authentication Schemes

Native Splunk authentication is always tried first. If it fails for any reason other than "no such local user", Splunk does not try LDAP. Only when the user does not exist locally does Splunk attempt LDAP, and then scripted authentication.

Strategy Failover Chains (authSettings)

With LDAP you can configure several strategies, typically one per LDAP server, and list them in authSettings. When multiple strategies are enabled, Splunk searches their servers in connection order to find the user. That order is set in Splunk Web through each strategy's Connection order field, which appears when you edit a strategy after more than one is enabled.

Local Authentication Fallback & Break-Glass Architecture

A critical design principle in Splunk Enterprise is that local accounts defined in $SPLUNK_HOME/etc/passwd remain intact and functional even when external authentication (LDAP or SAML) is actively configured.

Why Local Fallback is Essential

If external network connectivity fails, directory services crash, IdP signing certificates expire, or DNS resolution breaks, administrative personnel must retain the ability to authenticate to resolve the underlying failure.

The SAML Web Bypass Workflow (loginType=splunk)

When authType = SAML is enabled, navigating to the Splunk Web root URL (https://<searchhead>:8000/) automatically issues an HTTP 302 redirect sending the browser to the external IdP SSO page.

To bypass this redirection and authenticate using a local emergency account:

1. Open a browser and navigate explicitly to:

   https://<splunk_server>:8000/en-US/account/login?loginType=splunk
   

2. Splunk Web bypasses the SAML redirection handler and displays the native Splunk username/password login dialog.
3. Enter local administrative credentials (e.g., the default admin account).
4. Splunk verifies the credentials directly against $SPLUNK_HOME/etc/passwd.

REST API & CLI Fallback

The Splunk management port (TCP 8089) and CLI commands do not utilize SAML browser redirects. Commands such as splunk search ... -auth admin:LocalPassword or REST API calls against https://<searchhead>:8089/services/authentication/ always evaluate local credentials directly, ensuring headless orchestration and configuration management tools remain operational during IdP outages.

LDAP Integration Deep Dive

LDAP integration allows Splunk to authenticate users against corporate directories (such as Microsoft Active Directory or OpenLDAP) and map directory security groups to Splunk roles.

Transport Security: Port 389 vs. Port 636

• TCP Port 389 (Plain LDAP or StartTLS): Transmits directory data. Plain LDAP should never be used across untrusted networks because credentials are sent in plaintext. If port 389 is utilized, StartTLS must be enabled.
• TCP Port 636 (LDAPS - LDAP over SSL/TLS): Industry standard for enterprise deployments. The entire session is wrapped in TLS encryption. Enable it with SSLEnabled = 1 in the strategy (or the SSL enabled checkbox), and SSL must also be enabled on the LDAP server. Splunk uses the OpenLDAP and OpenSSL libraries, so client-side certificate trust follows OpenLDAP's ldap.conf conventions (Splunk's copy is under $SPLUNK_HOME/etc/openldap/).

Stanza Structure in authentication.conf

[authentication]
authType = LDAP
authSettings = corp_active_directory

[corp_active_directory]
# Network connection parameters
host = ad.corp.example.com
port = 636
SSLEnabled = 1

# Service Bind Account credentials
bindDN = cn=splunk_svc,ou=ServiceAccounts,dc=corp,dc=example,dc=com
bindDNpassword = EncryptedSecretToken!

# User Search Configuration
userBaseDN = ou=Users,dc=corp,dc=example,dc=com
userBaseFilter = (&(objectCategory=person)(objectClass=user))
userNameAttribute = sAMAccountName
realNameAttribute = displayName
emailAttribute = mail

# Group Search Configuration
groupBaseDN = ou=Groups,dc=corp,dc=example,dc=com
groupBaseFilter = (objectCategory=group)
groupNameAttribute = cn
groupMappingAttribute = dn
groupMemberAttribute = member
nestedGroups = 1

Key Parameter Explanations

• bindDN: The distinguished name of the service account used by Splunk to query the directory. Use a dedicated, read-only service account whose password does not expire unexpectedly.
• bindDNpassword: The bind account password. If you type it in plaintext in authentication.conf, splunkd encrypts it the next time it starts.
• userNameAttribute: The directory attribute containing the user's login ID (sAMAccountName in Active Directory; uid in OpenLDAP).
• nestedGroups: When set to 1 (enabled), Splunk recursively evaluates group memberships, resolving users who belong to child groups nested within a parent security group.

Mapping Directory Groups to Splunk Roles

Group-to-role mappings are declared in a dedicated stanza formatted as [roleMap_<strategy_name>]:

[roleMap_corp_active_directory]
# Splunk Role = Directory Group 1; Directory Group 2
admin = Splunk_Enterprise_Admins;Domain Admins
power = Splunk_Power_Users;Security_Engineers
user = Domain Users;Engineering;IT_Helpdesk

• If an LDAP user belongs to multiple mapped groups (e.g., both Splunk_Power_Users and Domain Users), Splunk assigns the user both the power and user roles.
• When you map by group, every LDAP user who should log in must belong to a mapped group. A user in no mapped group gets no Splunk role and cannot use Splunk.
• You map either groups or users, not both. To map users directly, point groupBaseDN at the same location as userBaseDN in authentication.conf.
• In Splunk Web: Settings > Authentication Methods > LDAP > Configure Splunk to use LDAP, then Map groups for the strategy and move roles into Selected Roles.

Applying and Testing LDAP Changes

• Changes made in Splunk Web take effect when you save. After editing authentication.conf by hand, run splunk reload auth (or restart) so splunkd rereads the file.
• Test with a user from each mapped group and confirm the roles under Settings > Users. LDAP users appear there after they log in.

Inspecting splunkd.log for LDAP Error Codes

When troubleshooting LDAP failures, administrators search $SPLUNK_HOME/var/log/splunk/splunkd.log (index=_internal) for LDAP errors. The numbers below are standard LDAP result codes:

• LDAP Error 49 (Invalid Credentials): The bindDNpassword is incorrect, or the service account is locked out or expired in Active Directory.
• LDAP Error 32 (No Such Object): The userBaseDN or groupBaseDN path does not exist in the directory tree (check for typos in OU/DC syntax).
• LDAP Error 81 (Server Down): Splunk cannot establish a TCP socket to the host and port (check network firewalls, routing, or DNS resolution).