Splunk® Enterprise

Admin Manual

Download manual as PDF

Splunk version 4.x reached its End of Life on October 1, 2013. Please see the migration information.
This documentation does not apply to the most recent version of Splunk. Click here for the latest version.
Download topic as PDF

Set up user authentication with external systems

Splunk ships with support for three types of authentication systems:

Important: Splunk's built-in system always takes precedence over any external systems. This is the order in which Splunk authenticates a user:

1. Splunk built-in authentication

2. LDAP authentication (if enabled)

3. Scripted authentication (if enabled)

How scripted authentication works

In scripted authentication, a user-generated Python script serves as the middleman between the Splunk server and an external authentication system such as PAM or RADIUS.

The API consists of a few functions that handle communications between Splunk and the authentication system. You need to create a script with handlers that implement those functions.

To use your authentication system with Splunk, make sure the authentication system is running and then do the following:

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.

Examples

Splunk provides several example authentication scripts and associated configuration files, including one set for RADIUS and another for PAM. There is also a simple script called dumbScripted.py, which focuses on the interaction between the script and Splunk.

You can use an example script and configuration file as the starting point for creating your own script. You must modify them for your environment.

You can find these examples in $SPLUNK_HOME/share/splunk/authScriptSamples/. That directory also contains a README file with information on the examples, as well as additional information on setting up the connection between Splunk and external systems.

Important: Splunk does not provide support for these scripts, nor does it guarantee that they will fully meet your authentication and security needs. They are meant to serve as examples that you can modify or extend as needed.

Create the authentication script

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

  • userLogin
  • getUserInfo
  • getUsers

The Splunk server will call these functions as necessary, either to authenticate user login or to obtain information on a user's roles.

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

  • getSearchFilter

This table summarizes the authentication functions, their arguments, and their return values:

Function Description Argument string Return value string
userLogin Login with user credentials. --username=<username>

--password=<password>

(values passed one per line over stdin)

fail

(safely passed over stdout)

getUserInfo Return a user's information, including name and role(s). --username=<username>
--status=success|fail 
--userInfo=<userId>;<username>;<realname>;<roles> 

Note the following:

  • userInfo must specify a semicolon-delimited list.
  • <userId> is deprecated; you should return just the associated semicolon.
  • <username> is required.
  • <realname> is optional, but its semicolon is required.
  • <roles> is required. To return multiple roles, use colons to separate the roles.
    For example: admin:power
  • This example returns just the roles for a user named "docsplunk":
        --status=success --userInfo=;docsplunk;;admin:power
getUsers Return information for all Splunk users. none
--status=success|fail 
--userInfo=<userId>;<username>;<realname>;<roles> 
--userInfo=<userId>;<username>;<realname>;<roles> 
--userInfo=<userId>;<username>;<realname>;<roles> ... 

Note the following:

  • See getUserInfo for information on the syntax to use to return each user's information.
  • Separate each user's information with a space.
  • <roles> is required. To return multiple roles, use colons to separate the roles.
    For example: admin:power
getSearchFilter Optional. Returns the filters applied specifically to this user, along with those applied to the user's roles. The filters are OR'd together.

Note: User-based search filters are optional and not recommended. A better approach is to assign search filters to roles and then assign users to the appropriate roles.

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

--username=<username>
--status=success|fail --search_filter=<filter> 
--search_filter=<filter> ... 

See the example scripts for detailed information on how to implement these functions.

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]
>

The following example shows a debugging session that does some simple testing of a fictional script called "example.py", with two users "alice" and "bob". "alice" is a member of the "admin" and "super" roles, and "bob" is a member of the "user" role.

> python example.py userLogin
--username=alice
--password=correctpassword
<send an EOF>
--status=success
> python example.py userLogin
--username=bob
--password=wrongpassword
<send an EOF>
--status=fail
> python example.py getUsers
<no arguments for this function, send an EOF> 
--status=success --userInfo=bob;bob;bob;user --userInfo=alice;alice;alice;admin:super
> python example.py getUserInfo
--username=bob
<send an EOF>
--status=success --userInfo=bob;bob;bob;user
> python example.py getUserInfo
--username=userdoesnotexist
<send an EOF>
--status=fail
>

Important: This is just an example of how to go about testing a script. It does not attempt to perform exhaustive debugging of any real script.

Edit authentication.conf

Add the following settings to authentication.conf in $SPLUNK_HOME/etc/system/local/ to enable your script. You can also copy and edit a sample authentication.conf from $SPLUNK_HOME/share/splunk/authScriptSamples/.

Specify Scripted as your authentication type under the [authentication] stanza heading:

[authentication]
authType = Scripted
authSettings = script

Set script variables under the [script] stanza heading. For example:

[script]
scriptPath = $SPLUNK_HOME/bin/python $SPLUNK_HOME/bin/<scriptname.py>

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.

The cacheTiming settings specify the frequency at which Splunk calls your script to communicate with the external authentication system. You can specify time in seconds (s), minutes (m), hours (h), days (d), etc. Typically, you'll limit the cache frequency to seconds or minutes. If a unit is not specified, the value defaults to seconds. So, a value of "5" is equivalent to "5s".

This example shows typical values for the caches:

[cacheTiming]
userLoginTTL    = 10s
getUserInfoTTL  = 1m
getUsersTTL     = 2m

You'll want to set userLoginTTL to a low value, since this determines how long user login/password validity is cached.

To refresh all caches immediately, use the CLI command reload auth:

./splunk reload auth

Note: This command does not boot current users off the system.

You can also refresh caches in Splunk Web:

1. Click Manager in the upper right-hand corner of Splunk Web.

2. Under System configurations, click Access controls.

3. Click Authentication method.

4. Click Reload authentication configuration to refresh the caches.

Each specified function, except getUsers, has a separate cache for each user. So, if you have 10 users logged on and you've specified the getUserInfoTTL attribute, the getUserInfo function will have 10 user-based caches. The getUsers function encompasses all users, so it has a single, global cache.

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.

Note: User-based search filters are optional and not recommended. A better approach is to assign search filters to roles and then assign users to the appropriate roles.

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

[script]
scriptPath = $SPLUNK_HOME/bin/python $SPLUNK_HOME/bin/<scriptname.py>
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.

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

This documentation applies to the following versions of Splunk® Enterprise: 4.3, 4.3.1, 4.3.2, 4.3.3, 4.3.4, 4.3.5, 4.3.6, 4.3.7


Was this documentation topic helpful?

Enter your email address, and someone from the documentation team will respond to you:

Please provide your comments here. Ask a question or make a suggestion.

You must be logged into splunk.com in order to post comments. Log in now.

Please try to keep this discussion focused on the content covered in this documentation topic. If you have a more general question about Splunk functionality or are experiencing a difficulty with Splunk, consider posting a question to Splunkbase Answers.

0 out of 1000 Characters