The Practical User’s Guide for Setting up LDAP in Splunk

After setting up your Splunk environment, it’s often a good idea to configure a central authentication mechanism, particularly if you’re wanting to grow your Splunk user base.

Splunk offers a variety of authentication options, but the one we’ll focus on here is LDAP.

LDAP is one of the most popular forms of authentication for a variety of reasons–it integrates with a number of providers (e.g. Microsoft Active Directory) and is flexible in that it supports multiple sources.

If you’re trying to get LDAP configured in your Splunk instance, there are a few things you should be aware of before you begin and as you go through the deployment process. This article walks you through the initial information gathering, discusses how to implement the configuration, and reviews the necessary best practices for deployment.

A Quick Note on Using a Central Authentication Mechanism

Local accounts are easy to set up, but difficult to manage. To address the challenge they present, use a central authentication mechanism to allow the same credentials to log into Splunk and other corporate resources.

In terms of the account lifecycle, central management can be designed to automatically add and remove access to Splunk as employees join and leave your organization. This ensures a streamlined process for keeping accounts and credentials in sync when they’re updated.

Information Gathering

There are several pieces of information necessary to get LDAP configured, including:

• The host that is running LDAP
• The port where LDAP is running on this host (TCP/636 (SSL – Recommended) or TCP/389 (insecure/plaintext) are typical values)
• A service account that has permission to bind to the LDAP server (referred to the Bind DN)
• A password associated with the Bind DN user
• The location of user data in your LDAP structure (referred to the User Base DN)
• The location of groups which will require Splunk access (referred to the Group Base DN)
• If possible, a standardized naming convention for groups requiring Splunk access which can be used to filter and identify relevant groups from LDAP

The information may seem complicated at first glance, and yes, there’s a lot to obtain. Let’s dig into each of these a bit further to better understand what we need.

LDAP Host

The host running LDAP will vary based on your environment, and whether or not it is an Active Directory LDAP source or another provider. It is generally considered a best practice to use a DNS name for the host and not rely on one host, which would be a single point of failure.

In an Active Directory environment, you may point to a domain controller. However, a better practice would be to point to the top-level DNS name for your domain. This typically returns a multivalue DNS record, resolving to multiple domain controllers. It also adds a degree of built-in redundancy since you’re not tied to the status of a single domain controller.

In order for this to work, the Splunk instances must be able to make successful LDAP queries to any domain controllers that would be returned by DNS, so be aware of any possible firewall or network changes that may be required to allow this communication.

LDAP Port

Whenever possible, you should be running an SSL encrypted LDAP connection, which will typically run on TCP/636. Using unencrypted LDAP on TCP/389 is insecure, as credentials are transmitted in cleartext over the network.

You may also have to configure LDAP to access the Active Directory Global Catalog port, TCP/3268 (insecure) or TCP/3269 (SSL). Your Active Directory Admin/Architect will be able to let you know if configuring GC may be needed in your particular environment.

Bind DN + Password

To make LDAP queries, there must be an associated service account, or Bind DN, with permissions to access LDAP that exists. This will be the case for most LDAP environments, unless anonymous binds are permitted–which is generally not recommended as a security best practice. The user will need to have the ability to read LDAP information on all users and groups that need to log into Splunk.

The specific format for the username is known as a distinguished name format. It typically begins with CN (common name), and will look something like this:

In this example, the username is splunk-ldap, and it is in a group/organizational unit called service-accounts. DC stands for domain component; in this example, the DC is your-domain.com.

The user will also have an associated password, which will need to be added to the Splunk configuration. Please consider any password expiration policies that may be in place for this account, as an expiration of these credentials will prevent any LDAP users from being able to log into Splunk. Additionally, you’ll most likely want to maintain a local account with administrative permissions that can be used for backup access and troubleshooting authentication in the event of an LDAP failure.

User Base DN + Filter

A typical Active Directory LDAP environment will contain objects for more than just users: you’ll also have other non-person accounts, such as machines or services. The User Base DN, along with the User Base Filter–which is typically set to (objectClass=person)–will tell Splunk where to look in LDAP to find user information.

Depending on your Active Directory structure, you may find that user information is located in one or more branches of your LDAP tree. Splunk supports multiple User Base DNs, in the event your organization is set up in a way where this type of configuration would make sense. If multiple User Base DNs are specified, they should be separated by semicolons–not spaces.

A simple example may look something like this:

A slightly more complicated example with multiple DNs specified would look like this:

In the latter example, the LDAP tree is branched into both US and EU groups, each of which have a Splunk-Users group. Both of these groups are part of the User Base DN, which means these branches of the LDAP trees will be searched for user information. In this example, you could simply specify a User Base DN as DC=your-domain,DC=com, but it would be significantly less efficient as Splunk would need to search ALL groups for user information as opposed to just the ones containing Splunk users specifically.

Group Base DN + Filter

The Group Base DN is to LDAP groups as the User Base DN was to LDAP users–it tells Splunk where to locate groups in the LDAP environment. Just like the User Base DN, if there are multiple locations where groups are located, they all can be specified.

In addition to the Group Base DN, Splunk allows for a group search filter to be applied. Filtering is particularly helpful if all of your Splunk-related user groups have a consistent naming convention–such as beginning with the word Splunk–but may be within a base location where there are a bunch of non-Splunk groups that might also be returned.

A simple example for a Group Base DN may look something like this:

Just like the User Base DN, multiple Group Base DNs can be specified, separated by semicolons.

In this LDAP environment, you also decided to name all of your Splunk related groups as beginning with Splunk (e.g., Splunk-Admins and Splunk-Users). You can apply a Group Base Filter to limit the results returned to only these groups:

If you would like to filter on more than one group name, this can also be specified. For example, if you also want to add any members of groups that begin with “Security,” your Group Base Filter would look something like this:

Nested Groups

Depending on your LDAP configuration, you may end up with user objects directly in groups, or you may find groups added into groups. If there are groups inside of groups (e.g., an IT or Security admin group inside of a Splunk related group), Splunk will need to be configured to use Nested groups in order for it to follow the memberOf extensions and expand the groups as needed.

Splunk Configuration

At this point, you should have all the information you need to begin configuring LDAP within Splunk. There are two ways to configure this–using the WebUI or conf files.

Using conf files

LDAP configuration is stored in two separate files: authentication.conf and authorize.conf. The authentication.conf file stores the LDAP configuration itself, while the authorize.conf defines roles that are mapped to users, including LDAP users. Both files work together to ensure that users are able to log in and use Splunk.

My preference is to use an app and configuration files whenever possible. However, the WebUI can be very helpful for testing your LDAP configuration and validating that everything is working as expected.

Considerations in a distributed environment

When configuring LDAP in a Splunk environment, you will typically want to make one LDAP configuration that is identical across all of the nodes in the Splunk environment. This is typically accomplished by creating an authentication app and distributing the configuration via the Splunk Deployment Server.

Additionally, it is considered best practice to not have plaintext passwords–in this case, the Bind DN password–in configuration files. Splunk allows for an encoded password to be distributed via the authentication app if the splunk.secret is consistent across all of the nodes where LDAP is configured. If this is not something that is consistent in your environment and you are looking to centrally manage LDAP, now is a great time to standardize your Splunk secret. See our tutorial for steps on how to accomplish this.

Alternatively, you can configure LDAP locally on each individual host, but we definitely wouldn’t recommend this, as it makes it a lot more annoying to update configurations consistently in the future. Going into the WebUI and configuring LDAP on each host creates a configuration that is unique on each host and not centrally managed.

Creating an authentication app

Begin by creating an app that will contain your authentication configuration. In a distributed environment, I’ll start by creating this in $SPLUNK_HOME/etc/apps/ on the deployment server, and ultimately copy this app over to $SPLUNK_HOME/etc/deployment_apps once I’ve tested it on the deployment server successfully.

For this example, I will call my authentication app infra_auth_base. The authentication.conf and authorize.conf files will live in the local directory, since I want this configuration to take precedence over any config in a default directory that may exist in another app. Note that any configs in a default directory should not exist in an environment where LDAP is being set up for the first time.

NB: If you have previously attempted to configure LDAP via the Splunk web interface, check for existing configuration via btool. You will typically find LDAP configuration created in the WebUI in one of the following locations:

• $SPLUNK_HOME/etc/system/local
• $SPLUNK_HOME/etc/apps/search/local
• $SPLUNK_HOME/etc/apps/launcher/local

Authentication.conf

The following is a sample authentication.conf file that you can use as a template:

Authorize.conf

The following is a sample authentication.conf file that you can use as a template:

This example creates a new user role that inherits the permissions of the built-in user role in Splunk and also grants the user permissions to search all non-internal indexes.

Using the Splunk WebUI

If you would like to configure LDAP using the Splunk WebUI, this can be done in Settings -> Access Controls -> Authentication Method -> Choose External/LDAP -> LDAP Settings. From the Authentication method screen, you can also reload the authentication configuration, which is a quick and easy way to test the authentication configuration without restarting Splunk.

This is what the [Your_LDAP] stanza in the above ldap.conf file looks like in the Splunk WebUI:

Verifying LDAP is Functioning Correctly

Once you have LDAP configured, you’ll want to confirm that LDAP is functioning properly. First – you’ll want to reload the Splunk authentication configuration, to ensure that your changes are actively being used. You can do this via the WebUI in the Authentication method screen (described above) or on the CLI as follows:

Next, verify that Splunk can communicate with LDAP and obtain group information. I generally find the easiest way to do this is to navigate to the “Map Groups” section of your LDAP configuration. You can find this at Settings -> Access Controls -> Authentication Method -> Choose External/LDAP -> LDAP Settings.

From this screen, you’ll be able to see all of the groups that are within the Group Base DN that match the group base filter. Hopefully you will see some LDAP groups that match configured roles, and have roles shown.

If you click on one of these group names, you will see the following list of available roles and LDAP users. If you see the expected users in this list and have an appropriate role mapped, they should be able to log in successfully.

At this point, assuming you are not seeing any errors, you should be able to proceed with testing logging in.

Troubleshooting

Hopefully, you don’t have to read this section, but inevitably you will run into some difficulties at some point that require additional troubleshooting. Based on my experience, these are the most common issues you will encounter.

Where to look

Splunk logs information on LDAP activity to the splunkd.log file. If you have the ability to search your internal logs in Splunk (hopefully), you can set your search source to include this file. Otherwise, you can use grep to look for lines relating to LDAP, your strategy name, or a user experiencing issues.

Another search that can be helpful is:

Unable to communicate with LDAP server

Failing to communicate with the LDAP server is a simple but very common issue. The Splunk server needs to be able to reach the LDAP server(s) on the ports configured. Ensure that any firewalls (host or network) allow this communication. Additionally, if you’re using a DNS name for your LDAP server (which you should be), ensure that DNS is functioning properly and resolving to the correct IP address(es) on the Splunk system.

Invalid Bind DN or password/permissions issues

The Splunk service account needs to be able to query LDAP and retrieve user information. If these credentials are invalid, Splunk will be unable to bind to LDAP. Additionally, if you are pushing out an encoded password via the deployment server and the splunk.secret is different, authentication will also fail.

No groups found

Check the Group Base DN to confirm that it is correct for your environment. For testing purposes, you can make the Base DN less restrictive to see if it returns more (or any) groups.

No users found

Check the User Base DN to confirm that it is correct for your environment. For testing purposes, you can make the Base DN less restrictive to see if it returns more (or any) users.

In Conclusion

While you have a couple choices for central authentication, I hope our guide was helpful for helping you get LDAP configured in your Splunk environment. Happy Splunking!