Set up user authentication with LDAP
This documentation does not apply to the most recent version of Splunk. Click here for the latest version.
- Determine your User and Group Base DN
- Set up LDAP via Splunk Web
- Map existing LDAP groups to Splunk roles
- Test your LDAP configuration
- Get LDIFs
- Group LDIF
- Configure authentication.conf
- Map roles
- Map users directly
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:
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.
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.
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
- The value
uidshould work for most other configurations.
16. Enter the Real name attribute (common name) of the user.
- Typical values are
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
dnfor 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
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
21. Enter the Group member attribute.
- This is the group attribute whose values are the group's members.
- This is typically
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:
$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".
You need the user and group LDIFs to set up
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
# ldapsearch -h ldaphost -p 389 -x -b "ou=People,dc=splunk,dc=com" -D "cn=bind_user" -W
# ldapsearch -h ldaphost -p 389 -x -b "ou=People,dc=splunk,dc=com" -D "cn=bind_user" "(objectclass=*)" -W
# 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
Get the group LDIF by running the following command (use your own
# ldapsearch -h ldaphost -p 389 -x -b "ou=groups,dc=splunk,dc=com" -D "cn=bind_user" -W
# 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
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] authType = LDAP authSettings = ldaphost
Note the following:
- Turn on LDAP by setting
authType = LDAP.
authSettingsto your LDAP configuration stanza (below).
Map to LDAP server entries
Now, map your LDIFs to the attribute/values in
[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
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
[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
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:
$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.confare 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 = (|(cn=SplunkAdmins)(cn=SplunkPowerUsers)(cn=Help Desk))
- If you must role map more than the maximum number of groups, you can edit
- To prevent Splunk from listing unnecessary groups, use the
[roleMap] admin = SplunkAdmins power = SplunkPowerUsers user = Help Desk
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
- Create a blank
- 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.
Have questions? Visit Splunk Answers and see what questions and answers the Splunk community has around LDAP authentication with Splunk.