Configure LDAP using configuration files

You can make changes to how Splunk Enterprise authenticates with servers that run the Lightweight Directory Access Protocol (LDAP). The authentication.conf configuration file controls how Splunk Enterprise interacts with LDAP services for authentication.

Edit the authentication.conf file in $SPLUNK_HOME/etc/system/local/. For general information on editing configuration files, see About configuration files In the Admin Manual.

If you prefer to configure LDAP with Splunk Web, see Configure LDAP with Splunk Web.

How authentication.conf works with LDAP and LDAP strategies

When you change the authentication scheme on the Splunk platform from native to LDAP, you must specify at least one LDAP strategy for the instance to connect to when it performs authentication.

The authentication.conf file represents this as the authSettings setting, where you specify at least one strategy, and a group of settings under a stanza for each strategy that you specify in the authSettings setting. The stanza names for any LDAP strategies you specify must match the names that you specified in authSettings. For example, if you configured authSettings=ad_ldap, then there must be a stanza called ad_ldap where the Splunk platform can look for settings and values for the ad_ldap strategy.

When you configure an LDAP strategy stanza, you must specify a minimum of the following settings and values:

• host = <LDAP server name>
• port = <LDAP port>
• groupBaseDN = <string representation of the group base Distinguished Name (DN), ex: 'ou=Groups,dc=example,dc=com'>
• groupMemberAttribute = <group entry attribute whose values are the group members, ex: 'uniqueMember'>
• groupNameAttribute = <group entry attribute whose value stores the group name, ex: 'cn'>
• realNameAttribute = <user entry attribute whose value is their real name, ex.: 'displayName' or 'cn'>
• userBaseDN = <string representation of user base DN, ex: ou=People,dc=example,dc=com>
• userNameAttribute = <user entry attribute whose value is the username, ex: 'uid'>

Either you or your LDAP administrator must provide the minimum setting values described here. There are additional settings that you can configure; see the authentication.conf specification file for those settings and their descriptions.

On Windows, there is no support for IPV6 address formats for the host setting.

For examples of how to create authentication.conf, see the authentication.conf spec file.

Configure multiple LDAP strategies

The Splunk platform can search across multiple LDAP servers, as described in How Splunk works with multiple LDAP servers. To configure multiple LDAP strategies, set the authSettings setting to a comma-separated list of all strategies, in the order in which you want to query the strategies. Then, specify separate stanzas for each strategy.

Set the authentication type and configure LDAP strategy names and settings

This is a generic procedure for configuring authentication.conf for LDAP. Depending on your LDAP strategy settings, you might need to specify additional settings and values in the strategy-specific stanzas.

1. Open a shell prompt.
2. Change to the $SPLUNK_HOME/etc/system/local directory.
3. (Optional) Create the authentication.conf file if it does not already exist.
4. Open the authentication.conf file for editing.
5. Add the following lines to the file:

   [authentication]
   authType = LDAP
   authSettings = <ldap_strategy1>,<ldap_strategy2>
   

   In this example, <ldap_strategy#> represents one or more LDAP strategies. You can separate multiple strategies with commas.
6. Configure a stanza for each of the LDAP strategies that you specified in the authSettings setting, with the stanza name matching the strategy that you specified.

   [authentication]
   authType = LDAP
   authSettings = ldap_strategy1
   [ldap_strategy1]
   

7. Add a minimum of the following lines for each strategy stanza:

   [ldap_strategy]
   host = <LDAP server name>
   port = <LDAP port>
   groupBaseDN = <string representation of the group base Distinguished Name, ex: 'ou=Groups,dc=example,dc=com'>
   groupMemberAttribute = <group entry attribute whose values are the group members, ex: 'uniqueMember'>
   groupNameAttribute = <group entry attribute whose value stores the group name, ex: 'cn'>
   realNameAttribute = <user entry attribute whose value is their real name, ex.: 'displayName' or 'cn'>
   userBaseDN = <string representation of user base Distinguished Name, ex: ou=People,dc=example,dc=com>
   userBaseFilter = <user search filter, ex: (objectclass=*)>
   userNameAttribute = <user entry attribute whose value is the username, ex: 'uid'>
   

8. Save the authentication.conf file and close it.
9. Restart the Splunk platform.

Set authentication type and configure LDAP strategies with SSL

If you have enabled SSL for your LDAP strategy, you must edit two files: authentication.conf, where you set the authentication type to LDAP and configure your LDAP strategy, and ldap.conf, where you configure the Splunk platform to use your SSL certificates to connect to your LDAP strategy.

The ldap.conf file you use to enable your LDAP strategy is not stored with other Splunk Enterprise configuration files in the local or default configuration file directories. It must be stored in $SPLUNK_HOME/etc/openldap/. If you store it anywhere else, Splunk software is unable to set up your LDAP strategy.

You must also have already set up your SSL certificates on the instance where you want to use the LDAP authentication scheme. See Steps for securing your Splunk Enterprise deployment with TLS for additional information and procedures.

1. Complete steps 1 to 7 of the previous procedure, "Set authentication type and configure LDAP strategy names and settings".
2. For each LDAP strategy that you want to use SSL certificates to connect, add the following line in the strategy stanza:

   [ldap_strategy1]
   ...
   SSLEnabled = 1
   

3. Save the authentication.conf file and close it.
4. (Optional) Create the ldap.conf file if it does not already exist.
5. Add the following lines to the file:

   TLS_REQCERT demand 
   TLS_CACERT <path to your SSL certificate, for example: /opt/splunk/etc/auth/LDAProotcert.crt> 
   TLS_CIPHER_SUITE <your cipher suite>
   

6. Save the ldap.conf file in $SPLUNK_HOME/etc/openldap/ and close it.
7. Restart the Splunk platform.

Map LDAP groups to Splunk roles

To map an LDAP strategy group to a Splunk role, you must configure a roleMap stanza in the authentication.conffile for that strategy. Each strategy requires its own roleMap_ stanza. The following example maps LDAP groups in the "ldaphost1" strategy to Splunk roles. For each mapping, the syntax is <Splunk RoleName> = <LDAP group string>.

[roleMap_ldaphost1]
admin = SplunkAdmins
itusers = ITAdmins

Map LDAP users to Splunk roles

If you need to map an LDAP user directly to a Splunk role, in the stanza for the LDAP strategy where you want to do the mapping:

1. Set the value of the groupBaseDN setting to the value of the userBaseDN setting.
2. Set the values for the groupMappingAttribute, groupMemberAttribute, and groupNameAttribute settings to the same value as the userNameAttribute setting.

For example:

[authentication]
authType=LDAP
authSettings=supportLDAP
[supportLDAP]
SSLEnabled = 0
bindDN = cn=Directory Manager
bindDNpassword = #########
groupBaseDN = ou=People,dc=splunksupport,dc=com
groupBaseFilter = (objectclass=*)
groupMappingAttribute = uid
groupMemberAttribute = uid
groupNameAttribute = uid
host = supportldap.splunksupport.com
port = 389
realNameAttribute = cn
userBaseDN = ou=People,dc=splunksupport,dc=com
userBaseFilter = (objectclass=*)
userNameAttribute = uid
[roleMap_supportLDAP]
admin = rlee;bsmith

Disable LDAP authentication and return to native authentication

If you configure LDAP authentication and decide later to return to using the default Splunk authentication scheme, the fastest way is to rename the authentication.conf file to something else, for example, by renaming it to authentication.conf.disabled, and restarting the Splunk platform.