Set up user authentication with LDAP

Set up user authentication with LDAP

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

Splunk supports LDAP v2 and v3, but does not support LDAP referrals. LDAP v3 is the default protocol used. Check the Splunk Community Wiki for information about ways to authenticate against an LDAP server that returns referrals (such as Active Directory).

Overview of the process

This topic provides procedures to do the following. Both steps are required to use LDAP authentication with Splunk:

• Configure Splunk to use LDAP authentication
• Map existing LDAP groups to Splunk roles
• Optionally, import your CA if your LDAP server requires it for SSL use.
• Be sure to read the section called "Things to know about Splunk and LDAP" at the end of this topic before proceeding.

User Management

Once you have switched Splunk to use LDAP authentication, no user administration is done within Splunk. Instead, you must manage users within your LDAP server. 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 Web, go to Manager > Authentication method and click 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 Manager > Authentication method and click 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 Web, go toManager > Authentication method and click Reload Authentication Configuration.

Important: In order for Splunk to recognize any LDAP membership changes, you must reload the authentication configuration. This includes adding or removing users. This is because Splunk caches its LDAP user information when you start Splunk.

Configure LDAP

This topic describes how to configure LDAP through Splunk Web. If you want to configure LDAP by editing authentication.conf, you can see complete configuration examples in the Admin manual's configuration file reference and the Splunk Community Wiki topic "Authenticate against an LDAP server that returns referrals".

If you are configuring authentication via the configuration file and wish to switch back to the default Splunk authentication, 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 Manager in the upper right-hand corner.

2. Under System configurations, click Authentication method.

3. Click Configure Splunk to work with LDAP.

Next, fill in your LDAP settings:

4. Define an LDAP strategy name for your configuration. The name cannot be LDAP and cannot 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. You can specify multiple user base DN entries by separating them with a semicolon.

• Splunk uses this attribute to locate user information.

• 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. You can specify multiple group base DN entries by separating them with a semicolon.

• Location of the user groups in LDAP.

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 name 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.

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 users individually.

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/groups re visible in the Users page in Splunk Manager. Click 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 confirm that the variables you are specifying will return the expected entries:

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

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

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

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

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.

You can see a complete example authentication.conf here, and another example configuration in the Splunk Community Wiki topic: "Authenticate against an LDAP server that returns referrals".

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. For 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 = Gina Lee;

Convert saved searches to LDAP

If you have existing saved searches you will need to convert them to work with your new LDAP configuration by following these steps:

1. Refer to your existing savedsearches.conf file(s). You will need to match the numeric userid to its corresponding LDAP id by referring to the $SPLUNK_HOME/etc/passwd file.

2. From CLI, run ./splunk list user. You may need to compare this output against the passwd file in order to verify the correct LDAP id for each user.

3. Modify $SPLUNK_HOME/etc/apps/<app_name>/metadata/local.meta and swap the owner = # field under each savedsearch permission stanza to the corresponding LDAP id and save your changes.

4. Restart Splunk for your changes to take effect.

Things to know about Splunk and LDAP

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

• Entries in Splunk Web and authentication.conf are case sensitive.
• 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 Web can display a maximum of 499 LDAP groups.
  • To prevent Splunk from listing unnecessary groups, use the groupBaseFilter. Example: groupBaseFilter = (|(cn=SplunkAdmins)(cn=SplunkPowerUsers)(cn=Help Desk))
  • If you must role map more than 499 groups, you can hand edit the authentication.conf:

[roleMap]
Admin = SplunkAdmins;
Power = SplunkPowerUsers;
User = Help Desk;

• You must restart to be able to log in after switching from LDAP back to Splunk authentication.
• The value of userBaseDN can not be set to the same value as groupBaseDN, even in situations where users and groups reside in the same base. 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.

• Was this topic useful?
• Post a comment