Set up LDAP

Set up LDAP

Splunk supports authentication via its internal authentication services or your existing LDAP server.

Notes:

• You must add a CA when connecting to AD via secure LDAP. Read the section below entitled Import your CA for more information.
• Splunk is unable to follow LDAP referrals. Check the Splunk Wiki for information about ways to authenticate against an LDAP server that returns referrals.
• Be sure to read the section called "Known issues with LDAP" at the end of this topic before proceeding.

User Management

Important: Once you have switched Splunk into LDAP mode, no user administration is done within Splunk. Instead, you must administer users within your LDAP server and reload authentication configuration within Splunk. For example:

• To add an LDAP user to a Splunk role, add the user to the LDAP group on your LDAP server. Then in Splunk go to Server > Control > Reload Authentication Configuration.
• To change a user's role membership, change the LDAP group that the user is a member of on your LDAP server. Then in Splunk go to Server > Control > Reload Authentication Configuration.
• To remove a user from a Splunk role, remove the user from the LDAP group on your LDAP server. Then in Splunk go to Server > Control > Reload Authentication Configuration.

Configure LDAP

Configure LDAP through Splunk Web or via authentication.conf. If you are configuring authentication via the conf file and wish to switch back to the default Splunk auth, the simplest way is to move the existing authentication.conf file out of the way (rename to *.disabled is fine) and restart Splunk. This will retain your previous configuration unchanged if you expect to return to it later.

Determine your User and Group Base DN

Before you map your LDAP settings in Splunk, figure out your user and groupbase DN, or distinguished name. The DN is the location in the directory where authentication information is stored. If all information is contained in each user's entry, then these DNs must be the same. If group membership information for users is kept in a separate entry, enter a separate DN identifying the subtree in the directory where the group information is stored.

If you are unable to get this information, please contact your LDAP Administrator for assistance.

Set up LDAP via Splunk Web

First, set LDAP as your authentication strategy:

1. Click the Admin link in the upper right-hand corner.

2. Click the Server tab then select Authentication Configuration.

3. Select LDAP from the Set Authentication method drop-down.

Next, fill in your LDAP settings:

4. Define an LDAP strategy name for your configuration. The name cannot be LDAP, cannot start with a number and it must not contain spaces.

5. The strategy name is added to the Set Authentication Strategy drop-down once you save your LDAP configurations.

6. Specify the Host name of your LDAP server. Be sure that your Splunk Server can resolve the host name.

7. Specify the Port that Splunk should use to connect to your LDAP server.

• By default LDAP servers listen on TCP port 389.
• LDAPS (LDAP with SSL) defaults to port 636.

8. Turn on SSL by checking SSL enabled.

• Note: You must also have SSL enabled on your LDAP server.

9. Enter the Bind DN

• This is the distinguished name to bind to the LDAP server with.
• This is typically the administrator or manager user.
• This user needs to have access to all LDAP users you wish to add to Splunk.

10. Enter and confirm the Bind DN password for the binding user.

11. Specify the User base DN.

• Splunk uses this attribute to locate user information.
• You can specify multiple user base DN entries by separating them with a semicolon.
• Note: You must set this attribute or your authentication will not work.

12. Specify the User base filter for the object class you want to filter your users on.

• Default value is objectclass=*, which should work for most configurations.

13. Specify the Group base DN

• Location of the user groups in LDAP.
• You can specify multiple group base DN entries by separating them with a semicolon.

14. Input the Group base filter.

• This attribute defines the group name.
• Default value is objectclass=*, which should work for most configurations.
• Splunk can also accept a GID as a group base filter.

15. Enter the User name attribute that defines the user name.

• Note: The username attribute cannot contain whitespace. The username is case sensitive.
• In Active Directory, this is sAMAccountName.
• The value uid should work for most configurations.

16. Specify the Real name attribute (also referred to as the common name) of the user.

• The value displayName or cn should work for most configurations.

17. Input the Group name attribute.

• Set this only if users and groups are defined in the same tree.
• This is usually cn.

18. Specify the Group member attribute.

• This is usually member or memberOf, depending on whether the memberships are listed in the group entry or the user entry.

19. Enter the Group mapping attribute.

• Specify this value only if your member entries don't contain dn strings. In most cases, however, you can leave this field blank.
• If you enter this field, the value is usually dn.

20. Enter a value for pageSize.

• This determines how many records to return at one time.
• Enter 0 to disable paging and revert to LDAPv2. pageSize must be set to 0 in order to connect to Sun LDAP.

21. Specify a Failsafe user name.

• This allows you to authenticate into Splunk in the event that your LDAP server is unreachable.
• Note: This user has admin privileges within Splunk.

22. Enter and confirm a Failsafe password for your failsafe user.

Import your CA

To configure Splunk's LDAP to work with your own CA, follow these steps:

1. Export your root CA cert in Base-64 encoded X.509 format.

2. Add these lines to $SPLUNK_HOME/etc/openldap/ldap.conf:

TLS_CACERT $SPLUNK_HOME/etc/openldap/certs/$YOUR_CERT_NAME
TLS_CACERTDIR $SPLUNK_HOME/etc/openldap/certs

3. Create the directory $SPLUNK_HOMEetc/openldap/certs.

4. Place the exported CA cert at $SPLUNK_HOME/etc/openldap/certs/$YOUR_CERT_NAME.

5. Restart Splunk.

6. In Splunk Web, navigate to Admin > Server > Authentication Configuration.

• Click Save at the bottom of the page.

7. You can now map the designated AD groups to the respective roles in Splunk.

Map existing LDAP groups to Splunk roles

Once you have configured Splunk to authenticate via your LDAP server, map your existing LDAP groups to any roles you have created. If you do not use groups, you can map your LDAP users individually to Splunk roles. To do this you'll need to set userBaseDN = groupBaseDN. Please refer to the example below on how to do this.

Note: You can either map users or map groups but not both. If you are using groups, all the users you wish to have access to Splunk must be members of an appropriate group. Groups inherit capabilities from the highest level role they're a member of.

All users and groups are visible under the Users tab in the Splunk Web Admin section. Click the Edit link next to the appropriate user or group to define User Roles.

Important: If you change (and save) an existing user/group role LDAP mapping from within Splunk Web, all users currently logged in to Splunk Web will be automatically logged out of Splunk Web immediately and must log back in to proceed. This is done to ensure that any users who should no longer have access as a result of the role mapping change are indeed denied access.

Test your LDAP configuration

If you find that your Splunk install is not able to successfully connect to your LDAP server, try these troubleshooting steps:

1. Remove any custom values you've added for userBaseFilter and groupBaseFilter.

2. Check $SPLUNK_HOME/var/log/splunk/splunkd.log for any authentication errors.

3. Perform an ldapsearch to test that the variables you are specifying work:

ldapsearch -h "<host>" -p "<port>" -b "<userBaseDN>" -x -D "<bindDN>" -W"
ldapsearch -h "<host>" -p "<port>" -b "<groupBaseDN>" -x -D "<bindDN>" -W"

Note: On Solaris you have to add filter to the search.

ldapsearch -h "<host>" -p "<port>" -b "<groupBaseDN>" -x -D "<bindDN>" "<groupBaseFilter>" -W"

Example

This example steps you through obtaining LDIFs and setting up authentication.conf. You can also enter these settings in Splunk Web, as described above.

Note: The particulars of your LDAP server may be different. Check your LDAP server settings and adapt authentication.conf attributes to your environment.

Get LDIFs

You should have both the user and group LDIFs to set up authentication.conf.

User LDIF

Note On Windows systems you can extract ldifs with the ldifde command from the AD server

ldifde -f output.ldif

The ldifde command will export all entries in AD. You should then open the file in a simple text editor and find the appropriate entries.

Get the user LDIF by running the following command (use your own ou and dc):

# ldapsearch -h ldaphost -p 389 -x -b "ou=People,dc=splunk,dc=com" -D "cn=bind_user" -W

On Solaris:

# ldapsearch -h ldaphost -p 389 -x -b "ou=People,dc=splunk,dc=com" -D "cn=bind_user" "(objectclass=*)" -W

This returns:

# splunkadmin, People, splunk.com
dn: uid=splunkadmin,ou=People, dc=splunk,dc=com
uid: splunkadmin
givenName: Splunk
objectClass: top
objectClass: person
objectClass: organizationalPerson
objectClass: inetorgperson
sn: Admin
cn: Splunk Admin

Group LDIF

Get the group LDIF by running the following command (use your own ou and dc):

# ldapsearch -h ldaphost -p 389 -x -b "ou=groups,dc=splunk,dc=com" -D "cn=bind_user" -W

This returns:

# SplunkAdmins, Groups, splunk.com
dn: cn=SplunkAdmins,ou=Groups, dc=splunk,dc=com
description: Splunk Admins
objectClass: top
objectClass: groupofuniquenames
cn: SplunkAdmins
uniqueMember: uid=splunkadmin,ou=People, dc=splunk,dc=com

configure authentication.conf

Use the following instructions to set up authentication.conf. Edit this file in $SPLUNK_HOME/etc/system/local/, or your own custom application directory in $SPLUNK_HOME/etc/apps/. For more information on configuration files in general, see how configuration files work.

To set up LDAP via Splunk Web, see the instructions above.

set authentication type

By default, Splunk uses its own authentication type. Change that in the [authentication] stanza.

[authentication]
authType = LDAP
authSettings = ldaphost

• Turn on LDAP by setting authType = LDAP.
• Map authSettings to your LDAP configuration stanza (below).

map to LDAP server entries

Now, map your LDIFs to the attribute/values in authentication.conf.

[ldaphost]
host = ldaphost.domain.com
pageSize = 0
port = 389
SSLEnabled = 0
failsafeLogin = admin
failsafePassword = admin_password
bindDN = cn=bind user
bindDNpassword = bind_user_password
groupBaseDN = ou=Groups,dc=splunk,dc=com;
groupBaseFilter = (objectclass=*)
groupMappingAttribute = dn
groupMemberAttribute = uniqueMember
groupNameAttribute = cn
realNameAttribute = displayName
userBaseDN = ou=People,dc=splunk,dc=com;
userBaseFilter = (objectclass=*)
userNameAttribute = uid

map roles

You can set up a stanza to map any custom roles you have created in authorize.conf to LDAP groups you have enabled for Splunk access in authentication.conf.

[roleMap]
Admin = SplunkAdmins;
ITUsers = ITAdmins;

map users directly

If by chance you need to map users directly to Splunk role, you can do so by setting the groupBaseDN = userBaseDN. Example:

[supportLDAP]
SSLEnabled = 0
bindDN = cn=Directory Manager
bindDNpassword = #########
failsafeLogin = failsafe
failsafePassword = ########
groupBaseDN = ou=People,dc=splunksupport,dc=com;
groupBaseFilter = (objectclass=*)
groupMappingAttribute = dn
groupMemberAttribute = uniqueMember
groupNameAttribute = cn
host = supportldap.splunksupport.com
pageSize = 0
port = 389
realNameAttribute = cn
userBaseDN = ou=People,dc=splunksupport,dc=com;
userBaseFilter = (objectclass=*)
userNameAttribute = uid

[roleMap]
Admin = Tina Phi;

Convert saved searches to LDAP

If you have already configured saved searches and want to convert them to work with your new LDAP configuration, follow these steps:

1. Identify the user IDs at the Splunk CLI by typing:

./splunk list user

2. Then, modify $SPLUNK_HOME/etc/system/local/savedsearches.conf and swap the userid= field in each stanza to be the ldap userid.

3. To test that this works, create one saved search as an LDAP user so you can verify that you have the format of the LDAP userid, and then making the changes to the existing saved searches.

4. Once you finish modifying savedsearches.conf, you must restart Splunk.

Known issues with LDAP

When configuring Splunk to work with your LDAP instance, note the following:

• Will not work if LDAP server has no groups.
• Entries in Splunk Web and authentication.conf are case sensitive.
• Splunk currently supports LDAP v2 and v3; v3 allows for paging and is the default protocol used.
• Splunk does not support scrolling. LDAP servers that use scrolling, such as SUN/iPlanet Directory Server (versions 5.x and 6.x), should disable paging by setting pageSize to 0.
• Splunk only works with one LDAP server at a time.
• Splunk does not support (end user) anonymous bind. You may wish to create a user with minimal privileges for this purpose.
• Splunk Web can display a maximum of 499 LDAP groups.
  • To view and configure more than 499 groups manually configure them by editing authentication.conf.
  • If you want a group that did not make the cut for UI rendering, add the dn to the appropriate role in authentication.conf:
  • user = cn=splunk,ou=splunkgroups,ou=groups,o=company
• LDAP referrals is currently not supported.
• The LDAP strategy name can not be [LDAP], can't begin with a number and can't contain any whitespace.
• You must restart to be able to log in after switching from LDAP back to Splunk's auth.
• For situations where users and groups reside in the same base, the value of userBaseDN can't be the same as groupBaseDN. Workaround is to remove one level from the groupBaseDN (or vice versa). Example: if the userBaseDN = cn=Users,dc=domain,dc=com, set groupBaseDN = dc=domain,dc=com.
• Splunk's authentication module does not work with Domino LDAP or Apache Directory.
• If your LDAP group names contain ampersand '&', you will not be able to Edit Mappings via SplunkWeb. The workaround is to map groups to roles directly in local/authentication.conf.
• If your ldapBindPassword contains '&', or other unsafe XML, bind will fail. (SPL-18170). Workaround is to modify the ldap bind password so that it does not contain unsafe XML characters.
• When using LDAP with distributed search, the failsafe user/password should be synchronized on your distributed search nodes, as well as the splunk.secret file, and the hashed passwords in authentication.conf which must match the splunk.secret.
• When using LDAP with distributed seach, users must exist on all search nodes. This means that you must perform a reload auth or splunk restart on all the search nodes to acquire new users.
• In order for Splunk to recognize LDAP membership changes, you must reload the authentication configuration. This includes adding or removing users.

• Was this topic useful?
• Post a comment