Set up user authentication with LDAP

Set up user authentication with LDAP

Splunk ships with support for three types of authentication systems:

• Splunk's own built-in system, described in "Set up user authentication with Splunk's built-in system".
• LDAP, described in the topic you're now reading.
• A scripted authentication API for use with an external authentication system, such as PAM or RADIUS, described in Configure Splunk to use scripted authentication.

Important: Splunk's built-in system always takes precedence over any external systems. This is the order in which Splunk authenticates a user:

1. Splunk built-in authentication

2. LDAP authentication (if enabled)

3. Scripted authentication (if enabled)

Splunk supports LDAP v3, but does not support LDAP referrals. 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:

• Configure Splunk to use LDAP authentication
• Map existing LDAP groups to Splunk roles

In addition, see how to import your CA if your LDAP server requires it for SSL use.

Be sure to read "Things to know about Splunk and LDAP" at the end of this topic before proceeding.

User Management

You cannot add, edit, or delete LDAP users with 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.
• To change a user's role membership, change the LDAP group that the user is a member of on your LDAP server.
• To remove a user from a Splunk role, remove the user from the LDAP group on your LDAP server.

Note: Beginning with 4.1, Splunk automatically checks LDAP membership information when a user attempts to log into Splunk. You no longer need to reload the authentication configuration when adding or removing users.

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 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 group base DN, or distinguished name. The DN is the location in the directory where authentication information is stored. 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 your LDAP tree does not have group entries, you can set the group base DN to the same as the user base DN to treat users as their own group. This requires further configuration, described later.

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

Set up LDAP via Splunk Web

First, set LDAP as your authentication strategy:

1. Click Manager in Splunk Web.

2. Under System configurations, click Access controls.

3. Click Authentication method.

4. Select the LDAP radio button.

5. Click Configure Splunk to work with LDAP.

6. Click New.

7. Enter an LDAP strategy name for your configuration.

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

9. Enter 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.

10. To turn on SSL, check SSL enabled.

• Important: This setting is recommended for security.
• Note: You must also have SSL enabled on your LDAP server.

11. Enter the Bind DN.

• This is the distinguished name used to bind to the LDAP server.
• This is typically the administrator or manager user. This user needs to have access to all LDAP user and group entries you want to retrieve.
• Leave blank if anonymous bind is sufficient.

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

13. Specify the User base DN. You can specify multiple user base DN entries by separating them with semicolons.

• Splunk uses this attribute to locate user information.

• Note: You must set this attribute for authentication to work.

14. Enter the User base filter for the object class you want to filter your users on.

• Note: This is recommended to return only applicable users. For example, (department=IT).
• Default value is empty, meaning no user entry filtering.

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

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

16. Enter the Real name attribute (common name) of the user.

• Typical values are displayName or cn (common name).

17. Enter the Group mapping attribute.

• This is the user entry attribute whose value is used by group entries to declare membership.
• The default is dn for active directory; set this attribute only if groups are mapped using some other attribute besides user DN.
• For example, a typical attribute used to map users to groups is uid.

18. Enter the Group base DN. You can specify multiple group base DN entries by separating them with semicolons.

• Ths is the location of the user groups in LDAP.
• If your LDAP environment does not have group entries, you can treat each user as its own group:
  • Set groupBaseDN to the same value as userBaseDN. This means you will search for groups in the same place as users.
  • Next, set the groupMemberAttribute and groupMappingAttribute to the same attribute as userNameAttribute. This means the entry, when treated as a group, will use the username value as its only member.
  • For clarity, you should probably also set groupNameAttribute to the same value as userNameAttribute.

19. Enter the Group base filter for the object class you want to filter your groups on.

• Note: This is recommended to return only applicable groups. For example, (department=IT).
• Default value is empty, meaning no group entry filtering.

20. Enter the Group name attribute.

• This is the group entry attribute whose value stores the group name.
• This is usually cn.

21. Enter the Group member attribute.

• This is the group attribute whose values are the group's members.
• This is typically member or memberUid.

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 map either users or groups, but not both. If you are using groups, all users you want to access Splunk must be members of an appropriate group. Groups inherit capabilities from the highest level role they're a member of.

All users that can login are visible in the Users page in Splunk Manager. Assign roles to groups in the group mapping page under Access controls in Splunk Manager.

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. Check $SPLUNK_HOME/var/log/splunk/splunkd.log for any authentication errors.

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

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

This example steps you through the process of obtaining LDIFs and setting up authentication.conf. You can also enter these settings through 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 need 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. Then, open the file in a text editor and find the appropriate entries.

On non-Windows systems, 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 configure authentication.conf. Edit the file in $SPLUNK_HOME/etc/system/local/. For more information on configuration files in general, see "About configuration files".

Set authentication type

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

[authentication]
authType = LDAP
authSettings = ldaphost

Note the following:

• 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
port = 389
SSLEnabled = 0
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 you need to map users directly to a Splunk role, you can do so by setting the groupBaseDN to the value of userBaseDN. Also, set the attributes for groupMappingAttribute, groupMemberAttribute, and groupNameAttribute to the same attribute as userNameAttribute. For example:

[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]
admin = Gina Lee

Converting from Splunk built-in authentication to LDAP

Usernames in Splunk's built-in authentication system always take precedence over the same usernames in LDAP. So, if you have converted from Splunk's built-in authentication system to LDAP, you might need to delete users from Splunk's built-in system to ensure that you're using LDAP credentials. This is only necessary if usernames are the same in both systems.

If your LDAP usernames are the same as the names you previously used in the built-in system, saved searches should work without any conversion.

If you have existing saved searches created when your system was using Splunk's built-in authentication and you'd like to transfer them to an LDAP user of a different name, edit the metadata:

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

2. 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 only works with one LDAP server at a time.
• Any user explicitly created locally using Splunk native authentication will have precedence over an LDAP user of the same name. For example, if the LDAP server has a user with a cname of 'admin' and the default Splunk user of the same name is present, the Splunk user will win. Only the local password will be accepted, and upon login the roles mapped to the local user will be in effect.
• The number of LDAP groups Splunk Web can display for mapping to roles is limited to the number your LDAP server can return in a query.
  • 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 the maximum number of groups, you can edit authentication.conf directly:

            [roleMap]
            admin = SplunkAdmins
            power = SplunkPowerUsers
            user = Help Desk

Security issues

If you have configured Splunk to use LDAP authentication, it's important to be aware that all local accounts using Splunk built-in authentication are still present and active. This includes the "admin" account. You need to consider the security implications of this.

To remove all the current local accounts when enabling LDAP authentication:

• Move the $SPLUNK_HOME/etc/passwd file to passwd.bak.
• Create a blank $SPLUNK_HOME/etc/passwd file.
• Restart Splunk.

Keep in mind that local Splunk accounts can still be created when Splunk is in LDAP authentication mode. Also, any local Splunk accounts that must remain for backup or disaster-recovery purposes should use a very strong password.

When using LDAP, make sure that your LDAP implementation enforces:

• Strong password requirements for length and complexity.
• A low incorrect attempt threshold for password lockout.

Answers

Have questions? Visit Splunk Answers and see what questions and answers the Splunk community has around LDAP authentication with Splunk.

• Was this topic useful?
• Post a comment