Documentation: 3.2
|  Print Version Contents
This page last updated: 06/13/08 02:06pm

Set up LDAP

Splunk supports authentication via its internal authentication services or your existing LDAP server.

Note: You must add a CA when connecting to AD via secure LDAP. Read the section below entitled Import your CA for more information.

Configure LDAP

Configure LDAP through Splunk Web or via authentication.conf.

Determine your User and Group Base DN

Before you map your LDAP settings in Splunk, figure out your user and groupbase DN, or distinguished name. The DN is the location in the directory where authentication information is stored. If all information is contained in each user's entry, then these DNs must be the same. 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.

Set up LDAP via Splunk Web

First, set LDAP as your authentication strategy.

  • Click the Admin link in the upper right-hand corner.
  • Click the Server tab then select Authentication Configuration.
  • Select LDAP from the Set Authentication method drop-down.

Next, fill in your LDAP settings.

  • Define an LDAP strategy name for your configuration.
    • The name cannot be LDAP and it must not contain spaces.
    • The strategy name is added to the Set Authentication Strategy drop-down once you save your LDAP configurations.
  • Specify the Host name of your LDAP server.
    • Be sure that your Splunk Server can resolve the host name.
  • Specify 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.
  • Turn on SSL by checking SSL enabled.
    • Note: You must also have SSL enabled on your LDAP server.
  • Enter the Bind DN
    • This is the distinguished name to bind to the LDAP server with.
    • This is typically the administrator or manager user.
    • This user needs to have access to all LDAP users you wish to add to Splunk.
  • Enter and confirm the Bind DN password for the binding user.
  • Specify the User base DN.
    • Splunk uses this attribute to locate user information.
  • Specify the User base filter for the object class you want to filter your users on.
    • Default value is objectclass=*, which should work for most configurations.
  • Specify the Group base DN
    • Location of the user groups in LDAP.
  • Input the Group base filter.
    • This attribute defines the group name.
    • Default value is objectclass=*, which should work for most configurations.
    • Splunk can also accept a GID as a group base filter.
  • Enter the User name attribute that defines the user name.
    • Note: The username attribute cannot contain whitespace. The username is case sensitive.
    • In Active Directory, this is sAMAccountName.
    • The value uid should work for most configurations.
  • Specify the Real name attribute (also referred to as the common name) of the user.
    • The value cn should work for most configurations.
  • Input the Group name attribute.
    • Set this only if users and groups are defined in the same tree.
    • This is usually cn.
  • Specify the Group member attribute.
    • This is usually member or memberOf, depending on whether the memberships are listed in the group entry or the user entry.
  • Enter the Group mapping attribute.
    • Specify this value only if your member entries don't contain dn strings. In most cases, however, you can leave this field blank.
    • If you enter this field, the value is usually dn.
  • Enter a value for pageSize.
    • This determines how many records to return at one time.
    • Enter 0 to disable and revert to LDAPv2
  • Specify a Failsafe user name.
    • This allows you to authenticate into Splunk in the event that your LDAP server is unreachable.
    • Note: This user has admin privileges within Splunk.
  • Enter and confirm a Failsafe password for your failsafe user.

Import your CA

To configure Splunk's LDAP to work with your own CA, follow these steps:

  • Export your root CA cert in Base-64 encoded X.509 format.
  • Add these lines to $SPLUNK_HOME/etc/openldap/ldap.conf:
TLS_CACERT $SPLUNK_HOME/etc/openldap/certs/$YOUR_CERT_NAME
TLS_CACERTDIR $SPLUNK_HOME/etc/openldap/certs
  • Create the directory $SPLUNK_HOMEetc/openldap/certs.
  • Place the exported CA cert at $SPLUNK_HOME/etc/openldap/certs/cert1.cer.
  • Restart Splunk.
  • In Splunk Web, navigate to Admin > Server > Authentication Configuration.
    • Click Save at the bottom of the page.
  • You can now map the designated AD groups to the respective roles in Splunk.

Map existing LDAP groups to Splunk roles

Once you have configured Splunk to authenticate via your LDAP server, map your existing LDAP groups to any roles you have created. If you do not use groups, you can map users individually. NOTE: You can either map users or map groups but not both. If you are using groups, all the users you wish to have access to Splunk must be members of an appropriate group. Groups inherit capabilities from the highest level role they're a member of.

All users and groups are visible under the Users tab in the Splunk Web Admin section. Click the Edit link next to the appropriate user or group to define User Roles.

Test your LDAP configuration

If you find that your Splunk install is not able to successfully connect to your LDAP server, try these troubleshooting steps:

  • Remove any custom values you've added for userBaseFilter and groupBaseFilter.
  • Check $SPLUNK_HOME/var/log/splunk/splunkd.log for any authentication errors.
  • Perform an ldapsearch to test that the variables you are specifying work:
ldapsearch -h "<host>" -p "<port>" -b "<userBaseDN>" -x -D "<bindDN>" -w "<bindDNpassword>"
ldapsearch -h "<host>" -p "<port>" -b "<groupBaseDN>" -x -D "<bindDN>" -w "<bindDNpassword>"

Example

This example steps you through obtaining LDIFs and setting up authentication.conf. You can also enter these settings in Splunk Web, as described above.

Note: The particulars of your LDAP server may be different. Check your LDAP server settings and adapt authentication.conf attributes to your environment.

Get LDIFs

You should have both the user and group LDIFs to set up authentication.conf.

User LDIF

Get the user LDIF by running the following command (use your own ou and dc):

# ldapsearch -h ldaphost -p 389 -x -b "ou=People,dc=splunk,dc=com" -D "cn=Directory Manager" -w password

This returns:

# splunkadmin, People, splunk.com
dn: uid=splunkadmin,ou=People, dc=splunk,dc=com
uid: splunkadmin
givenName: Splunk
objectClass: top
objectClass: person
objectClass: organizationalPerson
objectClass: inetorgperson
sn: Admin
cn: Splunk Admin

Group LDIF

Get the group LDIF by running the following command (use your own ou and dc):

# ldapsearch -h ldaphost -p 389 -x -b "ou=groups,dc=splunk,dc=com" -D "cn=Directory Manager" -w password

This returns:

# SplunkAdmins, Groups, splunk.com
dn: cn=SplunkAdmins,ou=Groups, dc=splunk,dc=com
description: Splunk Admins
objectClass: top
objectClass: groupofuniquenames
cn: SplunkAdmins
uniqueMember: uid=splunkadmin,ou=People, dc=splunk,dc=com

configure authentication.conf

Use the following instructions to set up authentication.conf. To set up LDAP via Splunk Web, see the instructions above.

set authentication type

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

[authentication]
authType = LDAP
authSettings = ldaphost
  • Turn on LDAP by setting authType = LDAP.
  • Map authSettings to your LDAP configuration stanza (below).

map to LDAP server entries

Now, map your LDIFs to the attribute/values in authentication.conf.

[ldaphost]
host = ldaphost.domain.com
pageSize = 0
port = 389
SSLEnabled = 0

failsafeLogin = failsafe
failsafePassword = fail

bindDN = cn=Directory Manager
bindDNpassword = password

groupBaseDN = ou=Groups,dc=splunk,dc=com;
groupBaseFilter = (objectclass=*)
groupMappingAttribute = dn
groupMemberAttribute = uniqueMember
groupNameAttribute = cn

realNameAttribute = givenName
userBaseDN = ou=People,dc=splunk,dc=com;
userBaseFilter = (objectclass=*)
userNameAttribute = uid

map roles

You can also set a stanza to map roles you have created in authorize.conf to users you have enabled in authentication.conf.

[roleMap]
Admin = SplunkAdmins;

Known issues with LDAP

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

  • Entries in Splunk Web and authentication.conf are case sensitive.
  • Splunk currently supports LDAP v2 and v3; v3 allows for paging and is the default protocol used.
  • Splunk does not support scrolling. LDAP servers that use scrolling, such as SUN/iPlanet Directory Server (versions 5.x and 6.x), should disable paging by setting pageSize to 0.
  • Splunk only works with one LDAP server at a time.
  • Splunk Web can display a maximum of 499 LDAP groups.
    • To view and configure more than 499 groups manually configure them by editing authentication.conf.
    • If you want a group that did not make the cut for UI rendering, add the dn to the appropriate role in authentication.conf:
      • user = cn=splunk,ou=splunkgroups,ou=groups,o=company
  • Ldap referrals is currently not supported.
Previous: Configure roles    |    Next: Scripted authentication

Comments

  1. @szhuk:

    thanks for including the examples for AD and SSL. the above examples are meant to be more general guidelines for different auth systems, so it's useful to have more specific ones.
    Posted by emma on Sep 12 2008, 5:17pm

  2. Also, for SSL AD requires a client cert.
    It doesn't verify it, so you can generate a self-signed cert, but it should be present.
    define this in the startup file:
    LDAPTLS_CERT=$SPLUNK_HOME/etc/openldap/<your_client_crt>
    LDAPTLS_KEY=$SPLUNK_HOME/etc/openldap/<your_client.key>
    export LDAPTLS_CERT
    export LDAPTLS_KEY
    Posted by szhuk on Jun 12 2008, 4:14pm

  3. Example for AD is incorrect.
    This works though:
    groupNameAttribute = cn
    groupMappingAttribute = dn
    realNameAttribute = cn
    userNameAttribute = sAMAccountName
    groupBaseFilter = (objectclass=group)
    userBaseFilter = (objectclass=user)
    groupMemberAttribute = member
    Posted by szhuk on Jun 12 2008, 3:35pm

Log in to comment.