Splunk® Enterprise

Admin Manual

Download manual as PDF

Download topic as PDF

Set up user authentication with external systems

Splunk ships with support for three types of authentication systems:


1. Splunk built-in authentication

2. LDAP authentication (if enabled)

3. Scripted authentication (if enabled)

How scripted authentication works




1. Create the Python authentication script.

2. Test the script with the command shell.

3. Edit authentication.conf to specify scripted authentication and associated settings.






Create the authentication script

You must create a Python script that implements these authentication functions:

  • userLogin
  • getUserInfo
  • getUsers


The script can optionally also include a handler for this function:

  • getSearchFilter


Function Description Argument string Return value string


(values passed one per line over stdin)


(safely passed over stdout)


Note the following:

  • userInfo must specify a semicolon-delimited list.
  • <username> is required.
    For example: admin:power
getUsers Return information for all Splunk users. none

Note the following:

  • Separate each user's information with a space.
    For example: admin:power


For more information, see "Using the getSearchFilter function" later in this topic.

--search_filter=<filter> ... 


Test the script

Since the communication between Splunk and the script occurs via stdin and stdout, you can test the script interactively in your command shell, without needing to call it from Splunk. Be sure to send one argument per line and end each function call with an EOF (Ctrl-D).

Test each function individually, using this pattern:

> python [script] [function name]
[pass arguments here, one per line]
[send eof, with Ctrl-D]
[output appears here, check that it's correct]


> python example.py userLogin
<send an EOF>
> python example.py userLogin
<send an EOF>
> python example.py getUsers
<no arguments for this function, send an EOF> 
> python example.py getUserInfo
<send an EOF>
> python example.py getUserInfo
<send an EOF>


Edit authentication.conf



authType = Scripted
authSettings = script



Set cache durations

To significantly speed authentication performance when using scripted authentication, make use of Splunk's authentication caching capability. You do so by adding the optional [cacheTiming] stanza. Each script function (except getSearchFilter) has a settable cacheTiming attribute, which turns on caching for that function and specifies its cache duration. For example, to specify the cache timing for the getUserInfo function, use the getUserInfoTTL attribute. Caching for a function occurs only if its associated attribute is specified.


This example shows typical values for the caches:

userLoginTTL    = 10s
getUserInfoTTL  = 1m
getUsersTTL     = 2m



./splunk reload auth


You can also refresh caches in Splunk Web:


2. Under System configurations, click Access controls.

3. Click Authentication method.

4. Click Reload authentication configuration to refresh the caches.


Edit pamauth for PAM authentication

If you're using PAM and you're unable to authenticate after following the steps in the example directory's README, edit /etc/pam.d/pamauth and add this line:

auth sufficient pam_unix.so

Using the getSearchFilter function

This function is optional and can be used to implement a user-based filter at search time. When getSearchFilter is enabled, Splunk will call it every time a search is run. A user-based search filter supplements any filters specified for that user's role(s). The returned filter(s) will be applied to each search, along with any configured at the role level. Caching of the filter does not occur with this function.


To enable getSearchFilter function, set the scriptSearchFilters parameter in authentication.conf:

scriptSearchFilters = 1

Note: In previous releases, getSearchFilter could also be used to implement search filters for users who had been authenticated by Splunk's built-in system. This is no longer the case. Starting with 4.2, Splunk calls getSearchFilter only for users who have been authenticated by scripted auth.

In addition, if a call to getSearchFilter fails, Splunk will cancel the user's search and return an error message. This ensures that users cannot view results from unauthorized searches.

Set up user authentication with LDAP
Use single sign-on (SSO) with Splunk


Was this documentation topic helpful?





0 out of 1000 Characters