Configure LDAP with Splunk Web
In both Splunk Cloud Platform and Splunk Enterprise, you can use Splunk Web to configure the Lightweight Directory Access Protocol (LDAP) authentication scheme.
There are three main steps to configure the LDAP authentication scheme with Splunk Web:
- Create an LDAP strategy.
- Map LDAP groups to Splunk roles.
- If you have multiple LDAP servers, specify their connection order.
If you run Splunk Enterprise and want to configure LDAP using the authentication.conf
configuration file, see Configure LDAP with configuration files.
Create an LDAP strategy
When you create an LDAP strategy, you let the Splunk platform connect to an LDAP server for the purposes of authentication using the settings that you specify for the strategy.
- Click Settings > Users and authentication > Authentication Methods.
- Check LDAP.
- Click Configure Splunk to use LDAP. The LDAP strategies page opens.
- Click New. This takes you to the Add new page.
- Enter an LDAP strategy name for your configuration.
- Enter the Host name of your LDAP server.
If you run Splunk Enterprise, confirm that the DNS subsystem on the machine can resolve the host name of your LDAP server. At this time, there is no support for IPv6 address formats on Windows.
- Enter the network Port that the Splunk platform is to use to connect to your LDAP server.
- By default LDAP servers listen on TCP port 389.
- LDAPS, or Secure LDAP, listens on TCP port 636.
- To turn on SSL, check SSL enabled.
- This setting is recommended for security.
- You must also have SSL enabled on your LDAP server.
- Enter the Bind DN.
- This is the distinguished name that the Splunk platform uses to bind to the LDAP server. It is typically, but not necessarily, the administrator. This user needs to have read access to all LDAP user and group entries that you want to retrieve.
- Leave blank if an anonymous bind is acceptable.
- Enter and confirm the Bind DN password for the binding user.
- Specify the User base DN. You can specify multiple user base DN entries by separating them with semicolons.
- The Splunk platform uses this attribute to locate user information.
- You must set this attribute for authentication to work.
- 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.
- 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, likecn
. - The value
uid
works for most other configurations.
- Enter the Real name attribute, or the common name, of the user.
- Typical values are
displayName
orcn
(common name).
- Typical values are
- Enter an Email attribute
- 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
.
- 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, also set groupNameAttribute to the same value as userNameAttribute.
- For best results when integrating Active Directory, place your Group Base DN in a separate hierarchy than the User Base DN.
- 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.
- This is recommended to return only applicable groups. For example:
- Enter the Group name attribute.
- This is the group entry attribute whose value stores the group name.
- This is usually
cn
.
- Enter the Static member attribute.
- This is the group attribute whose values are the group's members.
- This is typically
member
,uniqueMember
, ormemberUid
.
- To expand nested groups, check Nested groups.
- This controls whether the Splunk platform 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.
- 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 the Splunk platform will not look for dynamic group entries during authentication and authorization.
- This must match the object class of your dynamic groups definition to ensure that those groups get returned to Splunk. For example:
- 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
.
- This is the group attribute that uses the form of an LDAP search URL (such as
- 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. The Splunk platform 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 asize 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. - To set the request size limit higher than 1000, you must also edit
max_users_to_precache
inlimits.conf
to accomodate the number of users you set for your request size limit.
- To avoid performance-related issues, you can set the search request size limit. The Splunk platform 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,
- Search request time limit
- To avoid performance-related issues, you can set the search request time limit. The Splunk platform 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 time out. If this limit is reached on Splunk Enterprise, the
splunkd.log
log file will contain atime 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.
- To avoid performance-related issues, you can set the search request time limit. The Splunk platform 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 time out. If this limit is reached on Splunk Enterprise, the
- 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, the Splunk platform 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.
- Enable referrals with anonymous bind only.
- Click Save.
Map LDAP groups to Splunk roles
After you have configured the Splunk platform to authenticate using your LDAP server, map LDAP groups in your environment to Splunk roles. If you do not use groups, you can map users individually.
See Map LDAP groups to Splunk roles in Splunk Web for the procedure.
Specify the server connection order
If you have enabled multiple LDAP strategies, you can specify the order in which the Splunk platform searches their servers to find a user, as described in How Splunk works with multiple LDAP servers.
By default, the Splunk platform 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:
- From the main menu, select System > Users and Authentication > Access Controls.
- Click Authentication method.
- Select the LDAP radio button.
- Click Configure Splunk to use LDAP and map groups. This takes you to the LDAP strategies page.
- Click on the strategy whose connection order you want to specify. This takes you to the properties page for that strategy.
- Edit the Connection order field. This field appears only if you have enabled multiple strategies.
The '''Connection order''' field does not appear when you initially create the strategy. It only appears when you later edit its properties. Also, if you have disabled the strategy, the field appears grayed out.
- Click Save.
- Repeat the process for any other enabled strategy whose connection order you want to change.
How the Splunk platform works with multiple LDAP servers for authentication | Map LDAP groups to Splunk roles in Splunk Web |
This documentation applies to the following versions of Splunk® Enterprise: 7.0.0, 7.0.1, 7.0.2, 7.0.3, 7.0.4, 7.0.5, 7.0.6, 7.0.7, 7.0.8, 7.0.9, 7.0.10, 7.0.11, 7.0.13, 7.1.0, 7.1.1, 7.1.2, 7.1.3, 7.1.4, 7.1.5, 7.1.6, 7.1.7, 7.1.8, 7.1.9, 7.1.10, 7.2.0, 7.2.1, 7.2.2, 7.2.3, 7.2.4, 7.2.5, 7.2.6, 7.2.7, 7.2.8, 7.2.9, 7.2.10, 7.3.0, 7.3.1, 7.3.2, 7.3.3, 7.3.4, 7.3.5, 7.3.6, 7.3.7, 7.3.8, 7.3.9, 8.0.0, 8.0.1, 8.0.2, 8.0.3, 8.0.4, 8.0.5, 8.0.6, 8.0.7, 8.0.8, 8.0.9, 8.0.10, 8.1.1, 8.1.2, 8.1.3, 8.1.4, 8.1.5, 8.1.6, 8.1.7, 8.1.8, 8.1.9, 8.1.13, 8.1.14, 8.2.0, 8.2.1, 8.2.2, 8.2.3, 8.2.4, 8.2.5, 8.2.6, 8.2.7, 8.2.8, 8.2.9, 8.2.10, 8.2.11, 8.2.12, 9.0.0, 9.0.1, 9.0.2, 9.0.3, 9.0.4, 9.0.5, 9.0.6, 9.0.7, 9.0.8, 9.0.9, 9.0.10, 9.1.0, 9.1.1, 9.1.2, 9.1.3, 9.1.4, 9.1.5, 9.1.6, 9.2.0, 9.2.1, 9.2.2, 9.2.3, 9.3.0, 9.3.1, 8.1.0, 8.1.10, 8.1.11, 8.1.12
Feedback submitted, thanks!