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.
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.
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.
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
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:
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.
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:
The following is a sample authentication.conf file that you can use as a template:
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.