Configure the Splunk Supporting Add-on for Active Directory

The Splunk Supporting Add-on for Active Directory is a bundle of commands written in Python. New for version 2.0, the add-on no longer requires an installation of Java on the machines that run it.

Configure the Splunk Supporting Add-on for Active Directory

There are two ways to configure the Splunk Supporting Add-on for Active Directory:

Configure the add-on with Splunk Web

The Splunk Supporting Add-on for Active Directory has a configuration screen that you can access from Splunk Web.

To use the configuration page, activate the add-on by selecting it from the "App" menu in the upper left corner of the screen. Then, after the add-on loads, select "Configuration" from the menu.

Add a domain

To add a domain using the Configuration page:

1. In the lower left corner of the domain list pane, click the "+" sign.

2. In the Domain Name field, type in the name of the domain that you want the add-on to get data for.

3. Optionally, in the Alternate domain name field, type in an alternate representation of the domain in NetBIOS format.

4. In the Base DN field, type in the same domain in LDAP notation.

    Example: DC=spl,DC=com

5. In the LDAP Server: Hostname field, type in the name or IP address of the host that the add-on should connect to for this domain.

6. In the '"LDAP Server: Port field, type in the port that the add-on should connect to on the LDAP server.

Note: When configuring the 'default' connection, we strongly recommend that you use port 3268 (for plain text) or 3269 (for SSL) connections. For other domain connections use port 389 (for plain text) or 636 (for SSL)

7. If you want the server to use SSL to connect, click the SSL checkbox.

8. In the Credentials: Bind DN field, enter the username that the add-on should use to connect to the LDAP server you specified previously, in LDAP notation.

    Example: CN=Splunk Searcher,CN=Users,DC=spl,DC=com

9. In the Credentials: Password field, enter the password for that user.

10. Optionally, you can test whether or not the add-on can make a valid connection. To do so, click the Test connection button.

A window appears while the add-on attempts to connect to the LDAP server and retrieve information. If the test succeeds, the window displays results. If no results display, then the test has failed and you must correct your settings before attempting to test the connection again.

11. Click Save to save your changes.

Remove a domain

To remove a domain:

1. In the domain list pane, click the domain that you want to remove.

2. Click the "-" button at the bottom of the pane.

3. Click the Save button to save the changes.

Configure the add-on with a configuration file

The Splunk Supporting Add-on for Active Directory relies on a single configuration file, called ldap.conf. This file should be placed in the SA-ldapsearch/local directory. You might need to create this directory.

Within the file are a series of stanzas - one for each domain that you need to monitor. When configuring ldap.conf, remember to configure both the "DNS-style" and the "NetBIOS-style" names for each Active Directory domain.

There are two forms of stanza in ldap.conf.

Informational stanza

The informational stanza specifies all the information necessary to connect to the domain. Here is an example:

[spl.com]
server = 192.168.50.1;192.168.50.2
port = 636
ssl = true
basedn = dc=spl,dc=com
binddn = cn=Splunk Searcher,cn=Users,dc=spl,dc=com
password = {64}u9435tr8ujtgfnkjscc
alternatedomain = SPL

The valid attributes for the informational stanza are:

Attribute	Description	Default
server=<server1>;<server2>;…	Specifies the server or servers you want to connect to. Separate multiple servers with semicolons.	n/a
port	Specifies the LDAP port on the servers that you want to connect.	636 (when ssl is true) 389 (when ssl is false)
ssl=true/false	Specifies whether or not to use Secure Sockets Layer for communications.	false
basedn	Specifies the LDAP base Distinguished Name to use when connecting.	n/a
binddn	Specifies the LDAP binding Distinguished Name (the user account) to use when connecting.	n/a
password	Specifies the password for the user that you specified in binddn. You can either user a cleartext password, or preface a Base-64-encoded password with the string {64}. Use {64} with passwords that contain special characters (such as #) to ensure proper configuration. To create a Base-64-encoded password, use a Base-64 encoder, such as this one.	n/a
alternatedomain	Specifies the NetBIOS domain that this domain represents.	n/a

Specify multiple servers

You can specify multiple servers by including a list of hosts separated by semicolons. In this case, SA-ldapsearch uses the fastest available connection. In this case, the server that SA-ldapsearch uses might vary from command to command. You can turn on debug mode to find out which server a particular command uses. Once a command has started on a server, it uses that server until it completes.

The port and ssl parameters are optional. If you do not specify them, SA-ldapsearch uses port 389 and no SSL by default. SA-ldapsearch uses SSL only for encryption and not for authentication. SA-ldapsearch trusts all server side SSL certificates.

The bind Distinguished Name (binddn attribute) is a user within the domain you want to monitor. It must be a user that has at least read access to all attributes and entries that you want to read with any application that uses it.

Base64-encode attributes for added security

The password attribute should be set to the password for the user specified in the binddn attribute. You can use a plain text password, or a base64-encoded one by specifying {64} before the password.

Any attribute can be encoded as Base-64, including the binddn attribute. If your binddn has a special character in it, then use Base-64 encoding to store it.

Note: If you want to base64-encode an attribute, you must use a base-64 encoder to encode the entry for that attribute, and then assign the attribute with the results, preceded by {64}. Simply placing the {64} qualifier before the plain text value will not work.

'Default' stanza

To support context lookups in the "ldapfetch" command, you will also need a "default" stanza that lists a forest-level Global Catalog server by its IP address. In this case, you must specify the port to the Global Catalog. Following is an example:

[default]
server = 172.20.1.2
port = 3268

The Splunk Supporting Add-on for Active Directory has been tested to work with up to 100 domains. However, there is no built-in limit on the number of domains that the add-on can support.