Now that I’ve (hopefully) convinced you that ldapsearch is your friend, let’s get down to the matter. How can you use that information to configure Splunk to authenticate against LDAP?
The file used to configure LDAP authentication: authentication.conf
If you have never attempted to configure ldap auth before then you won’t have one of these files in your $SPLUNK_HOME/etc/system/local/. You can either create it by hand or use the UI (which creates the file for you.)
Here’s a sample authentication.conf file that I will break down for you. (BTW, a lot of this explanation already exists in a file called $SPLUNK_HOME/etc/system/README/authentication.conf.spec):
* This does not change
authType = LDAP
*If you want LDAP, set it to LDAP. Other options are Splunk and Scripted.
authSettings = myldapstrategy
*the name of your LDAP strategy from
*This is the custom name you set for your LDAP configuration “strategy”. Do not use any whitespace.
SSLEnabled = 0
*disabled by default – Make sure your LDAP server supports LDAPS if enabling this.
bindDN = cn=Directory Manager
*Bind account used to make requests to LDAP server. If binding to AD, you can use a valid email address, e.g. Gina.Lee@Splunkers.com.
*If your LDAP server allows anonymous bind, you can leave this field blank.
bindDNpassword = $hashed_password
*Enter the password for the configured password. The password gets hashed when you restart Splunk. Leave blank if binding anonymously.
failsafeLogin = admin
*Select an arbitrary, failsafe userid. I like to use ‘admin’ to keep things simple.
failsafePassword = $hashed_password
*Enter your desired password for your failsafe account above. Enter in plain text and it gets hashed on restart.
groupBaseDN = ou=Groups,dc=splunksupport,dc=com;
*This is the Base of your Groups in LDAP. You can also specify multiple bases. For example: ou=Management,ou=Groups,dc=Splunkers,dc=com;ou=Consultants,ou=Groups,dc=Splunkers,dc=com;
*This is optional. It can be very useful for narrowing down search results if you have a large Directory tree to recurse (and/or large entries being returned.)
groupMappingAttribute = dn
*By default, set this to ‘dn’. I have very rarely seen this set to anything else.
groupMemberAttribute = uniquemember
*Typically, you have a list of members listed out within the group entry. This attribute is the one that stores the member’s dn (usually.)
groupNameAttribute = cn
*This is the “pretty name” for your group. Usually, ‘cn’ but can be set to something else.
host = SplunksupportLDAP
*This is the hostname, FQDN or IP address of your LDAP Server.
pageSize = 0
*This tells the LDAP server how many entries to return “per page” of request. I set this to 0 because I use Sun LDAP in-house for testing — Sun LDAP does not support paging so it has to be disabled this way. If you’re using AD, you can leave it to the default of 800.
port = 389
*The default non-SSL LDAP port is 389. LDAPS default port is 636. Yours could possibly something else.
realNameAttribute = name
*This is the “pretty name” for your users. Other possible attributes you can use are displayName, cn.
userBaseDN = ou=People,dc=splunksupport,dc=com;
*This is the Base of your Users in LDAP. You can specify multiple UserBaseDNs. Example: ou=Tech Support,ou=People,dc=Splunkers,dc=com;ou=ITOPs,ou=People,dc=Splunkers,dc=com;
*Like the groupBaseFilter, this can be very useful if you have to narrow down your search results. Here’s an example that returns only those users who are a member of the SplunkAdmins group or the SplunkUsers group in LDAP: (|(memberOf=CN=SplunkAdmins)(memberOf=CN=SplunkUsers))
userNameAttribute = uid
*This will be the user’s login id. In AD its usually sAMAccountName.
*Here’s where you will map the LDAP group to Splunk Role. This must be done before users will be able to log in. The format is usually (Splunk Role) = (LDAP group CN)
admin = Splunk Admin Users;
power = Splunk Power Users;
user = My&Group;Splunk Users;
Once you’ve got LDAP auth configured, restart Splunk and, if you’re lucky, you’ll be able to login as an LDAP user. If not, you’ll have to login as the failsafe user and figure out what went wrong.
A couple more hints: Don’t forget that handy dandy tool called ldapsearch. And, It is very helpful to have DEBUG logging enabled for ‘authenticationManagerLDAP’ when troubleshooting these LDAP issues. And you can now enable DEBUG logging right in the UI, under System Logging, without having to restart Splunk.
OK, if you MUST use an LDAP Browser then check out Apache Directory Studio which is free for OSX, Linux and Windows.
Download, install and launch. Enter your LDAP hostname and go from there.
If you’re tired, frustrated, lost and given up hope after reading this, feel free to contact Splunk Support and we’ll get you moving forward.