Set up user authentication with LDAP

Set up user authentication with LDAP

Splunk supports 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)

Note: Splunk supports LDAP v3.

4.3 features

Starting with v4.3, Splunk supports several new LDAP-related features:

• Querying across multiple distinct LDAP servers. See "Use multiple LDAP strategies" below for details.
• Dynamic groups. The Manager settings for using dynamics groups are described later in this topic.
• Nested groups. The Manager setting for expanding nested groups is described later in this topic.
• Chasing LDAP referrals with anonymous bind is configurable on a per strategy basis. The Manager setting for disabling referrals with anonymous bind is described later in this topic.
• Settings for network timeout and search request time and size limits are configurable on a per strategy basis. The relevant settings in Manager are described later in this topic.

Manage Splunk users with LDAP

To configure Splunk to use LDAP authentication, first create a Splunk strategy for each LDAP server and then map Splunk roles to that server's groups, as described later in this topic. When a user attempts to log in, Splunk queries the server(s) to find the user. It grants the user permissions based on any roles associated with the LDAP groups the user is a member of.

When it comes to changing a user's permissions, you have several options:

• To change the permissions for a group of users, you can remap the LDAP group to a different Splunk role. You can also update the role itself to specify a different set of permissions for it. You do this on Splunk.
• To change the permissions for an individual user, you can move the user to an LDAP group mapped to a different Splunk role. You do this on the LDAP server.

Here are some other user management activities:

• To add a user to a Splunk role: First, On Splunk Web make sure that you've mapped the Splunk role to an LDAP group. Then, on your LDAP server, add the user to that LDAP group.
• To remove a user from a Splunk role: On your LDAP server, remove the user from the corresponding LDAP group.

A user can have membership in several roles. In that case, Splunk gives the user access to all the capabilities available for any of those roles. For example, if the user is a member of both the docs and eng groups, and docs is mapped to "user" and eng is mapped to "admin", the user obtains all permissions assigned to both the "user" or "admin" roles.

Note: Splunk automatically checks LDAP membership information when a user attempts to log into Splunk. You do not need to reload the authentication configuration when adding or removing users.

How to configure Splunk to use LDAP

These are the main steps to configure Splunk to work with LDAP:

1. Configure one or more LDAP strategies. (Typically, you configure one strategy per LDAP server.)

2. For each strategy, map its groups to one or more Splunk roles.

3. If you have multiple strategies, specify the connection order of their servers.

You can perform these steps in Splunk Web or by directly editing the authentication.conf file.

Use multiple LDAP strategies

Splunk can search against multiple LDAP servers when authenticating users. To do so, you must set up multiple strategies, one for each LDAP server. You can then specify the order in which you want Splunk to query the servers for LDAP users. (Splunk assigns a default order when the strategies are created.)

When it attempts to authenticate a user, Splunk searches the servers in the specified order. Once it locates the user on a server, it quits searching and takes the user's credentials from that server only. If the user also has credentials on a server that's later in the search order, Splunk will ignore them.

The order in which Splunk searches servers is called the "connection order". The default connection order is determined by the order in which a strategy was first enabled. For example, assume you configure and enable three strategies in this order: A, B, C. Splunk will search their servers in that same order: A, B, C. If it finds the user on A, it stops looking. It doesn't matter whether the user also exists on B and C; Splunk will only use A's credentials for that user. If it doesn't find the user on A, then it will continue to search the remaining servers: first B, then C.

If you later disable strategy A, Splunk will search the remaining strategies in the order: B, C.

You can change the connection order at any time by editing the strategies' properties in Splunk Web or by changing the order of the strategies in the authSettings attribute, as described in authentication.conf.

Important: Any user created locally through Splunk native authentication will have precedence over an LDAP user of the same name. See the section "Additional considerations", below, for details.

Things to consider when configuring LDAP

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. Users and groups will be searched recursively on all the subnodes under this DN. 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.

Additional considerations

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

• Entries in Splunk Web and authentication.conf are case sensitive.
• Any user created locally through 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 username attribute (for instance, cn or uid) 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. You can use the Search request size limit and Search request time limit settings to configure this, as described in the section "Create an LDAP strategy", below.
  • To prevent Splunk from listing unnecessary groups, use the groupBaseFilter. For 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. In this example, "roleMap_AD" specifies the name of the Splunk strategy. Each attribute/value pair maps a Splunk role to one or more LDAP groups:

       [roleMap_AD]
       admin = SplunkAdmins1;SplunkAdmins2
       power = SplunkPowerUsers
       user = SplunkUsers

Configure LDAP through Splunk Web

This section describes how to configure LDAP through Splunk Web. If you want to configure LDAP by directly editing authentication.conf instead, see "Configure LDAP by editing the configuration file" later in this topic.

There are three main steps to configuring LDAP with Splunk Web:

1. Create an LDAP strategy.

2. Map LDAP groups to Splunk roles.

3. Specify the connection order (for multiple LDAP servers only)

Create an LDAP strategy

To create an LDAP strategy:

1. Click Manager in Splunk Web.

2. In the Users and authentication section, click Access controls.

3. Click Authentication method.

4. Select the LDAP radio button.

5. Click Configure Splunk to use LDAP and map groups. This takes you to the LDAP strategies page.

6. Click New. This takes you to the Add new page.

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.

• This setting is recommended for security.
• You must also have SSL enabled on your LDAP server.
• You must also configure TLS_CACERT in ldap.conf (located under $SPLUNK_HOME/etc/openldap) to point to the root CA of the LDAP server certificate in the .pem format. For example:

     TLS_CACERT $SPLUNK_HOME/etc/openldap/certs/mycertificate.pem

11. Enter the Bind DN.

• This is the distinguished name used to bind to the LDAP server.
• This is typically, but not necessarily, the administrator or manager user. This user needs to have read 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.
• 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.

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

• The username attribute cannot contain white spaces.
• In Active Directory, this is typically sAMAccountName, but you can also authenticate on other attributes, like cn.
• 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 attribute that group entries use to define their members.
• 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 dn.

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

• This 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 Static group search filter for the object class you want to filter your static groups on.

• This is recommended to return only applicable groups. For example: (|(objectclass=groupofNames)(objectclass=groupofUniqueNames))
• Default value is empty, meaning no static 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 Static member attribute.

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

22. To expand nested groups, check Nested groups.

• This controls whether Splunk will expand nested groups using the 'memberof' attribute. Only check this if you have nested groups that leverage the 'memberof' attribute to resolve their members. On OpenLDAP, you need to explicitly enable the 'memberof' overlay.

23. Enter the Dynamic group search filter to retrieve dynamic groups, if any.

• This must match the object class of your dynamic groups definition to ensure that those groups get returned to Splunk. For example: (objectclass=groupOfURLs)
• Default value is empty, meaning Splunk will not look for dynamic group entries during authentication and authorization.

24. Enter the Dynamic member attribute.

• This is the group attribute that uses the form of an LDAP search URL (such as ldap:///o=Acme, c=US??sub?(objectclass=person) ) to define its members.
• This is typically memberURL.

25. If you check Advanced settings, there are several additional options you can set:

• Enable referrals with anonymous bind only.
  • This setting is on by default. Turn this off if you have no need for referrals.
  • Splunk can chase referrals with anonymous bind only. You must also have anonymous search enabled on your LDAP server.
  • If you are seeing long LDAP search timeouts (likely in Active Directory) and "Operations error" in splunkd.log for ScopedLDAPConnection, the issues might be related to referrals.
• Search request size limit
  • To avoid performance-related issues, you can set the search request size limit. Splunk will then request that the LDAP server return the specified maximum number of entries in response to a search request. In a large deployment with millions of users, setting this limit to a high value could result in a long response, depending on the search filter set in the LDAP strategy configuration. If this limit is reached, splunkd.log should contain a size limit exceeded message.
  • You should set the search request time limit and search request size limit values in conjunction with the splunkweb timeout property, described in "Configure user session timeouts". If you have a group that is not showing up in the Splunk console, it was likely excluded due to one of these limits. Tune these properties as needed.
• Search request time limit
  • To avoid performance-related issues, you can set the search request time limit. Splunk will then request that the LDAP server complete its search within the specified number of seconds. In a large deployment with millions of users, setting this limit to a high value could cause Splunk Web to timeout. If this limit is reached, splunkd.log should contain a time limit exceeded message.
  • You should set the search request time limit and search request size limit values in conjunction with the splunkweb timeout property, described in "Configure user session timeouts". If you have a group that is not showing up in the Splunk console, it was likely excluded due to one of these limits. Tune these properties as needed.
• Network socket timeout
  • This property is used to break the loop in the authentication chain when one of the LDAP servers in a multiple strategy configuration is unreachable due to network congestion or otherwise takes too long to respond. After waiting the specified number of seconds, the authentication process will continue with the next available strategy, if any.
  • When an LDAP strategy is first created, Splunk validates the LDAP server/port and other parameters. If the LDAP server is down or one of the parameters cannot be validated at that time, the LDAP strategy does not get created.

26. Click Save.

Map LDAP groups to Splunk roles

Once you have configured Splunk to authenticate via your LDAP server, map your LDAP groups to Splunk roles. 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 are visible in the Users page in Splunk Manager. To assign roles to groups in Splunk Web:

1. Click Manager in Splunk Web.

2. In the Users and authentication section, click Access controls.

3. Click Authentication method.

4. Select the LDAP radio button.

5. Click Configure Splunk to use LDAP and map groups. This takes you to the LDAP strategies page.

6. Click Map groups in the Actions column for a specific strategy. This takes you to the LDAP Groups page. You can use the search field in the upper right corner of the page to qualify the list of groups; for example, to search for groups containing specific users.

7. Click on a group name. This takes you the mapping page, which includes a list of available roles and a list of LDAP users for that group.

8. To map a role to a group, click the arrow to the left of a role in the "Available Roles" list. This moves the group into the "Selected Roles" list. You can map multiple roles to the group.

9. Click Save. This takes you back to the LDAP Groups page.

10. Repeat the process for each group that you want to assign Splunk roles to.

Specify the server connection order

If you have enabled multiple LDAP strategies, you can specify the order in which Splunk searches their servers to find a user, as described in "Use multiple LDAP strategies".

By default, Splunk searches the servers in the order in which they were enabled. To change the connection (search) order, you need to edit the properties for each strategy individually:

1. Click Manager in Splunk Web.

2. In the Users and authentication section, click Access controls.

3. Click Authentication method.

4. Select the LDAP radio button.

5. Click Configure Splunk to use LDAP and map groups. This takes you to the LDAP strategies page.

6. Click on the strategy whose connection order you want to specify. This takes you to the properties page for that strategy.

7. Edit the Connection order field near the top of the page. This field appears only if multiple strategies are enabled.

Note: The Connection order field does not appear when you initially create the strategy. It only appears when you later edit its properties. Also, the field will be grayed out if the strategy has been disabled.

8. Click Save.

9. Repeat the process for any other enabled strategy whose connection order you want to change.

Configure LDAP by editing the configuration file

As an alternative to using Splunk Web to configure LDAP, you can directly edit the authentication.conf file.

Note: If you decide later to return to using the default Splunk authentication, the simplest way is to move the existing authentication.conf file out of the way (for example, by renaming it to authentication.conf.disabled) and restart Splunk.

This example steps you through the process of setting up authentication.conf. You can also enter these settings through Splunk Web, as described above.

You can see some more examples at the end of the authentication.conf spec file.

Edit authentication.conf in $SPLUNK_HOME/etc/system/local/. For information on configuration files in general, see "About configuration files".

Set authentication type and strategy name(s)

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

[authentication]
authType = LDAP
authSettings = ldaphost1,ldaphost2

Note the following:

• Turn on LDAP by setting authType = LDAP.
• The authSettings attribute identifies one or more LDAP strategies. Each strategy has its own stanza, as described below.

Configure LDAP strategy stanzas

Each LDAP strategy needs its own stanza. Map the LDAP values to attribute/value pairs in the strategy's stanza.

Here's an example stanza for the "ldaphost1" strategy, specified earlier in the authSettings attribute:

[ldaphost1]
host = ldaphost1.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

Configure multiple LDAP strategies

Splunk can search across multiple LDAP servers, as described in "Use multiple LDAP strategies". To configure this, set the authSettings attribute to a comma-separated list of all strategies, in the order in which you want Splunk to query them. Then, specify separate stanzas for each strategy.

Map groups to roles

To map Splunk roles to a strategy's LDAP groups, you need to set up a roleMap stanza for that strategy. Each strategy requires its own roleMap stanza. This example maps roles for groups in the "ldaphost1" strategy:

[roleMap_ldaphost1]
admin = SplunkAdmins
itusers = ITAdmins

Map users directly to roles

If you need to map users directly to Splunk roles, 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_supportLDAP]
admin = rlee;bsmith

Test your LDAP configuration

If you find that Splunk is not able to 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. Use ldapsearch to confirm that the variables you are specifying will return the expected entries:

ldapsearch  -x –h <ldap_host> –p <ldap_port> –D "bind_dn" -w "bind_passwd" -b "user_basedn"  "userNameAttribute=*"

ldapsearch -x –h <ldap_host> –p <ldap_port> –D "bind_dn" -w "bind_passwd" –b "group_basedn"  "groupNameAttribute=*"

If these commands return matching entries, then your backend LDAP system is properly configured. Continue to troubleshoot the Splunk LDAP strategy configuration.

Converting from Splunk built-in authentication to LDAP

Username precedence

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.

Saved searches

If your LDAP usernames are the same as the names you previously used in the built-in system (but then deleted), 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.

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