Documentation: 3.3
|  Print Version Contents
This page last updated: 09/23/08 10:09am

Scripted authentication

Splunk ships with support for three authentication systems: Splunk's built-in system, LDAP and a new scripted authentication API. The scripted authentication system allows you to set up Splunk to interface with an authentication system you already have in place. Set up authentication using authentication.conf.

For the most up-to-date information on scripted authentication, see the README file in $SPLUNK_HOME/share/splunk/authScriptSamples/. There are sample scripts in this directory for PAM and RADIUS, as well as a sample authentication.conf for each auth system.
Note: These scripts are samples, and must be edited to work in your specific environment.

Known issues with scripted authentication

  • Scripted authentication does not currently work with distributed search.
  • Everybody gets User-level privileges. Use the admin section of Splunk Web to map your users to the correct Splunk role.
    • There is also a sample user-mapping script in $SPLUNK_HOME/share/splunk/authScriptSamples/. To use it, you must adapt the script to suit your environment; it is not designed to work without customization.

Configuration

Add the following settings to authentication.conf in $SPLUNK_HOME/etc/system/local/ (or your custom app directory) to enable your specific script. You can also copy the 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:

[script]
scriptPath = $SPLUNK_HOME/bin/python $SPLUNK_HOME/share/splunk/authScriptSamples/<scriptname>
scriptSearchFilters = 1

Set scriptSearchFilters to 1 if you want to enable search filters for roles mapped to users. Set to 0 to disable.

Optionally, add a [cacheTiming] stanza if needed for your script. Use these settings to adjust the frequency at which Splunk calls your application. Each call has its own timeout specified in seconds. Caching does not occur if not specified.

[cacheTiming]
userLoginTTL    = 1
searchFilterTTL = 1
getUserInfoTTL  = 1
getUserTypeTTL  = 1
getUsersTTL     = 1

Script commands

Scripted authentication includes the following commands to use in your script. Here is a descriptive list of these commands, including their inputs and outputs.

  • userlogin: login with username/password pair
    • in: --username=<username> --password=<password> (passed over stdin)
    • out: --status=<status_bit> --search_filter=<search_filter>(optional) --authToken=<tok> (optional)success (or fail)
  • getUserType: this command corresponds to the role within Splunk (for example Admin, Power or User)
    • in: --username=<username> --authToken=<tok> (optional)
    • out: --status=<status_bit> --role=<role> (eg Admin)
  • getUserInfo: get user information
    • in: --username=<username> --authToken=<tok> (optional)
    • out: --status=<status_bit> --userInfo=<userId>;<username>;<realname>;<role>

Supplemental calls:

  • getUsers
    • in: --authToken=<tok> (optional)
    • out: --status=<status_bit> --userInfo=<userId>;<username>;<realname>;<role> --userInfo=<userId>;<username>;<realname>;<role>....

Advanced calls:

  • checkSession
    • in: --authToken=<tok> (optional)
    • out: --status=<status_bit>
  • getSearchFilter = <role>
    • This command corresponds to the role within Splunk (for example Admin, Power or User).
    • in: --username=<username> --authToken=<tok> (optional)
    • out: --status=<status_bit> --search_filter=<filter> (you can have one or more --search_filter)

Every out starts with a <status_bit> which is one of the following:

  • success
    • The command succeeded correctly.
  • tmp_fail
    • Temporary failure of auth plugin. Attempt to just go on.
  • auth_fail
    • Failure to authenticate. Terminate the user's session.
Previous: Set up LDAP    |    Next: File system change monitor

Comments

  1. @michael.crispino: thanks for the clarification!
    Posted by rachel on Sep 23 2008, 9:44am

  2. The example for getUsers above is misleading. I took it to literally mean that the output had to be a string of --userInfo1 --userInfo2 --userInfo3 etc., which does not work.

    A string of --userInfo --userInfo --userInfo works however
    Posted by michael.crispino on Sep 22 2008, 7:02pm

Log in to comment.