Deploy:Integration with SSO
From Splunk Wiki
There are plenty of Single Sign-on (SSO) solutions for web access management. This document details the steps for integrating Splunk through Scripted Authentication using HTTP headers. The header values populate the uid, full name, and the roles for Splunk. The HTTP headers are set by the agent for the Web Access Management solution. This example uses Sun's Access Manager and should work for OpenSSO.
The modified login.html file expects the agent to set the following headers in the HTTP request:
- SPLUNK-UID: The authenticated user for the session. The agent sets the REMOTE_USER when this is derived from the session, but the REMOTE_USER value is not passed to the reverse proxy. The SPLUNK-UID is forwarded in the http request by the proxy server.
- SPLUNK-NAME: The full name, like the displayname attribute from LDAP
- SPLUNK-ROLES: The pipe delimited list of roles. The supplied script expects that these roles begin with splunk- or splunk_. So an account with administrator role and a user role are expected to be presented by the agent in the header as:
- This allows other roles to exist in the header value that other applications use.
The username and password fields are submitted in the modified login.html form (supplied). The username has the SPLUNK-UID header for its content, and the password field has the SPLUNK-NAME and SPLUNK-ROLES headers in pipe delimited format. The ssoScripted.pl will use these values to build files in a defined directory for userLogin(), then parses the files and returns data for the other functions in scripted authentication that include: getUserInfo(), getUsers(), and getUserType().
It's a pretty easy install.
Make sure the web server port is configured on the localhost or there are IP filters in place that prevent access from external clients. The agent is expected to make sure arbitrary headers are not sent in the request that collide with the header names defined above, but there's no agent installed in the application server distributed with Splunk.
Install a web server
The agent installs in the Apache Web server, and the web server will reverse proxy the connection to the Splunk application server.
- Download and configure Apache 2.2:
./configure --prefix=/u01/app/apache22 --enable-proxy --enable-ssl --enable-shared=all make install
- Make the appropriate configuration modifications to the httpd.conf file and optionally enable SSL
- Add the reverse proxy configuration, presuming the Splunk daemon is listening on port 8000 for web requests:
ProxyPreserveHost On ProxyPass / http://localhost:8000/ ProxyPassReverse / http://localhost:8000/
- Add a policy for the site
- Be sure the data store for Access Manager has the user attributes with the userid, displayname, and role list (in this case nsroles).
Install the Agent
The agent integrates with the Apache Web server using a shared library.
- Follow the documentation for the agent installation
- Configure the agent so it will set the appropriate header:
Edit the directory where the user information is maintained (the $USERDIR value in the supplied script). The account running the splunkd process must have write access to this directory.
Edit the location of the $USERDIR and adjust the $ROLEPREFIX. This is a regular expression that is used to match roles that are setup in Splunk.
- Backup the login.html and replace with the modified version.
cp $SPLUNK_HOME/share/splunk/search_mrsparkle/templates/account/login.html \ $SPLUNK_HOME/share/splunk/search_mrsparkle/templates/account/login.html.bak
- Setup the local authentication.conf file by copying the default
cp $SPLUNK_HOME/etc/system/default/authentication.conf \ $SPLUNK_HOME/etc/system/local/authentication.conf
- Edit the authentication.conf file:
- Add the changes to indicate scripted authentication will be used
[authentication] authType = Scripted authSettings = script
- In the script stanza give the script location
[script] scriptPath = /u01/app/splunk/scripts/ssoScripted.pl
- Ad the cacheTiming stanza to the appropriate settings. These are really important, getUserInfo() will be called many, many times for a single page in Splunk.
[cacheTiming] userLoginTTL = 0 searchFilterTTL = 300 getUserInfoTTL = 120 getUserTypeTTL = 120 getUsersTTL = 5
- Restart Splunk
The roles must be created in Splunk before they may be used. If a role can exist in the http header, the role needs to be created in Splunk and assigned the appropriate privileges. These roles must already exist before the account may use them. The scripted authentication provided will automatically setup users, but it doesn't automatically setup the role.
An unauthorized error displays in the web browser if an account authenticates with a role that does not exist. A message displaying the user must request roles displays if the user has no defined roles that match $ROLEPREFIX.
This is pretty cheap, but it works. You can still run splunk from the command line with the search argument. For username enter your SPLUNK-UID and for password enter the SPLUNK-ROLES in pipe delimited format.
TO DO: Modify the form so it checks something distinct to signify a command line query. That may be passed in the username or password field using and the ssoScripted.pl will check a username/password database .