Splunk® Enterprise

Securing Splunk Enterprise

Download manual as PDF

Download topic as PDF

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 file controls how Splunk Enterprise interacts with LDAP services for authentication.

Edit authentication.conf 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.

Authentication.conf 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 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.

You must also have already set up your SSL certificates on the instance where you want to use the LDAP authentication scheme. See About creating certificates for Splunk 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 and close it.
  7. Restart the Splunk platform.

Map LDAP groups to Splunk roles

To map an LDAP strategy group to a Splunk roles, you must configure a roleMap stanza in authentication.conf 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

Configure when the LDAP cache expires

By default, the Splunk platform caches results from LDAP queries forever. You can change this by editing limits.conf and changing the ttl setting under the [ldap] stanza.

  1. Open a shell prompt or PowerShell window.
  2. Change to the $SPLUNK_HOME/etc/system/local directory.
  3. Use a text editor to open the limits.conf file for editing.
  4. Add the following lines, substituting <string> with a string that represents when you want the LDAP cache to expire:
    [ldap]
    ttl = <string>
    

    For <string>, you can specify a number by itself, which means the cache expires in that many seconds, or you can specify a number and one of the letters s, m, h, or d, which represents the unit of time in seconds, minutes, hours, or days. For example, to specify a cache expiration time of 1 hour, you can specify ttl = 1h or ttl = 60m.
  5. Save the file and close it.
  6. Restart the Splunk platform.

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 authentication.conf (for example, by renaming it to authentication.conf.disabled) and restarting the Splunk platform.

PREVIOUS
Map LDAP groups to Splunk roles in Splunk Web
  NEXT
Map LDAP groups and users to Splunk roles in the configuration files

This documentation applies to the following versions of Splunk® Enterprise: 7.3.0, 7.3.1


Was this documentation topic helpful?

Enter your email address, and someone from the documentation team will respond to you:

Please provide your comments here. Ask a question or make a suggestion.

You must be logged into splunk.com in order to post comments. Log in now.

Please try to keep this discussion focused on the content covered in this documentation topic. If you have a more general question about Splunk functionality or are experiencing a difficulty with Splunk, consider posting a question to Splunkbase Answers.

0 out of 1000 Characters