Scripted authentication

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 -- such as PAM or RADIUS. 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

Configure scripted auth via authentication.conf. If you're using PAM, you may also need to edit your system's pamauth file in "etc/pam.d/pamauth".

Authentication.conf

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.

PAM auth

If you're using PAM and you're unable to auth after following the steps in the README, make sure you've added an entry to the system to support pamauth config. Edit /etc/pam.d/pamauth and put this line in:

auth sufficient pam_unix.so

• Was this topic useful?
• Post a comment