Use single sign-on (SSO) with Splunk
This documentation does not apply to the most recent version of Splunk. Click here for the latest version.
Use single sign-on (SSO) with Splunk
Use this topic to configure Splunk to work with your enterprise's SSO solution.
How Splunk works with SSO
Configuring Splunk to work with SSO requires that any Splunk instance to be accessed via SSO is secured behind an HTTP proxy. The HTTP proxy you configure is then responsible for handling authentication and is the sole entity capable of communicating with Splunk Web (and the underlying Splunk server process,
splunkd). Splunk's SSO implementation currently supports IIS and Apache HTTP proxies.
How Splunk handles authentication
Splunk's SSO implementation expects that your user authentication is handled outside of Splunk by a web proxy. The web proxy server must be configured to authenticate against your external authentication system. Once a user has been authenticated by the proxy, the proxy must insert the authenticated user's username as a
REMOTE_USER header in all HTTP requests forwarded to Splunk Web.
Splunk accepts incoming HTTP requests which include a
REMOTE_USER header from a trusted proxy. If the user in the
REMOTE_USER header is not currently authenticated by Splunk, an authentication request is made to Splunk via a trusted authentication endpoint the
splunkd process provides. If Splunk returns a valid session key, Splunk Web can begin making secure requests as the user set in the
REMOTE_USER header. All subsequent requests from the proxy to Splunk Web must include the
REMOTE_USER header. If
REMOTE_USER is not provided in every request, the
REMOTE_USER is assumed to not be authenticated and will receive a Splunk login screen.
Note: If your proxy uses some other remote user header name besides
REMOTE_USER, you can change the name of the header through the
remoteUser attribute in
web.conf, as described below.
Warning: Because the authentication component of is offloaded to the SSO proxy system, the proxy should not allow user-provided headers with the same name to be passed through to Splunk. In addition, HTTP headers are universally viewed as case-insensitive, so UserName would collide with USERNAME. As a Splunk special behavior, the - and _ characters are normalized to the same value, so a browser-provided USER-NAME could theoretically override a proxy-provided USER_NAME. For proxies we have tested, this is not a problem because the proxies add their headers at the end of the request, and the server will process the headers in header-presence order, thus ensure the proxy values will always take precedence.
Important: Splunk's SSO implementation supports logging in to Splunk Web only, not the command line interface or directly to
Configure Splunk to work with SSO
Setting up SSO on Splunk requires several steps:
1. Set up a proxy server.
2. Edit Splunk's
3. Edit Splunk's
4. Set up Splunk users.
Set up a proxy server
Splunk's SSO implementation supports most proxy servers, including Apache and IIS HTTP proxies. The proxy server must handle its own authentication and must insert the authorized username into a
REMOTE_USER (or equivalent) header for all HTTP requests it forwards to Splunk.
For more information on configuring an Apache or IIS proxy server, refer to this material:
- For Apache, see http://httpd.apache.org/docs/2.0/mod/mod_proxy.html
- For IIS, the Splunk SSO implementation has been tested with Helicon's ISAPI_Rewrite 3.0. Get it at: http://www.helicontech.com/download-isapi_rewrite3.htm
Note: The Helicon ISAPI must include the proxy module. Do not use the 'lite' version of Helicon ISAPI, as it does not have the required proxy module.
$SPLUNK_HOME/etc/system/local/server.conf to set the value of
trustedIP to the IP address that will make the secure requests to the
splunkd process. Typically, this is the address of your Splunk Web interface. If on the same machine, you can use the localhost IP (127.0.0.1). If you host Splunk Web on a different interface, use the IP for that interface.
Note: You can only configure
splunkd to trust one Splunk Web IP.
[general] serverName = myserver trustedIP = 127.0.0.1 [sslConfig] sslKeysfilePassword = $1&Jf96BQ0bdFG0
Note: You can also set the value of the SSO trusted IP in Splunk Web Manager. Go to Splunk Manager > System Settings > General Settings. Set the field SSO Trusted IP to the correct IP address.
[settings] stanza of
$SPLUNK_HOME/etc/system/local/web.conf, set one or more of the following attributes:
|trustedIP||yes||n/a||Set this to the IP address of the authenticating proxy or proxies. Specify a single address or a comma-separated list of addresses; IP ranges and netmask notation are not supported.|
|root_endpoint||no||the proxy's root|| If you host Splunk Web behind a proxy that does not place Splunk Web at the proxy's root, change this setting to reflect the offset from the root. For example, if your proxy hosts Splunk Web at "fflanda.com:9000/splunk", set the value to |
Note: The Splunk root endpoint for both the proxy and the reverse proxy, if any, must be identical.
|remoteUser||no||REMOTE_USER|| Sets the remote user header. Most proxies forward the authenticated username in an HTTP header called |
Caution: The proxy should be configured to rewrite
To prevent name space collisions and resulting security issues, configure the proxy to not pass
|tools.proxy.on||no||false|| For Apache 1.x proxies only. Set this attribute to "true". This configuration instructs CherryPy (the Splunk Web HTTP server) to look for an incoming |
|SSOMode||no||strict||Specifies the SSO mode for Splunk Web. The value is either "permissive" or "strict":
[default] [settings] mgmtHostPort = localhost:8089 httpport = 8000 enableSplunkWebSSL = 0 # SSO remoteUser = REMOTE-USER SSOMode = strict trustedIP = 10.1.6.199,10.1.7.161,10.1.7.38
Set up users in Splunk that match users in your authentication system
You must create or map users in Splunk that have the same username as the users authenticating via the proxy. For example, if you configure LDAP to use a name field that resolves as "omarlittle", Splunk assumes that the proxy will set
REMOTE_USER to "omarlittle". Alternatively, you can create a Splunk user with a username of "omarlittle" to allow this user to login via SSO using native Splunk authentication. For information about creating users in Splunk, refer to "Set up user authentication with Splunk's built-in system".
Splunk provides a URI for debugging any problems with SSO. This URI is located at:
This page provides diagnostic information about headers, usernames, and more.
Have questions? Visit Splunk Answers and see what questions and answers the Splunk community has around SSO with Splunk.