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.
Contents
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 authentication is handled
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 splunkd endpoints.
Configure Splunk to work with SSO
Setting up SSO on Splunk requires several steps:
1. Set up a proxy server.
2. Edit Splunk's server.conf file.
3. Edit Splunk's web.conf file.
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.
Edit server.conf
Edit $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.
Example:
[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.
Edit web.conf
In the [settings] stanza of $SPLUNK_HOME/etc/system/local/web.conf, set one or more of the following attributes:
| Attribute | Required? | Default | Value |
|---|---|---|---|
| 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 /splunk.
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 REMOTE_USER. However, some may use a different header, such as REMOTE-USER (with a hyphen instead of an underscore). If the proxy you are using does not use REMOTE_USER, specify the HTTP header that Splunk Web should look for.
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 X-Forwarded-Host header and to use the value of that header to construct canonical redirect URLs that include the proper host name. For more information, refer to the CherryPy documentation on running behind an Apache proxy. This setting is only necessary for Apache 1.1 proxies. For all other proxies, the setting must be "false", which is the default.
|
| SSOMode | no | permissive | Specifies the SSO mode for Splunk Web. The value is either "permissive" or "strict":
|
Example:
[default] [settings] mgmtHostPort = localhost:8089 httpport = 8000 enableSplunkWebSSL = 0 # SSO remoteUser = REMOTE-USER SSOMode = permissive 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".
Debug issues
Splunk provides a URI for debugging any problems with SSO. This URI is located at:
http://YourSplunkServer:8000/debug/sso
This page provides diagnostic information about headers, usernames, and more.
Answers
Have questions? Visit Splunk Answers and see what questions and answers the Splunk community has around SSO with Splunk.
This documentation applies to the following versions of Splunk: 4.1 , 4.1.1 , 4.1.2 , 4.1.3 , 4.1.4 , 4.1.5 , 4.1.6 , 4.1.7 , 4.1.8 , 4.2 , 4.2.1 , 4.2.2 , 4.2.3 , 4.2.4 , 4.2.5 View the Article History for its revisions.
> You must create or map users in Splunk that have the same username as the users authenticating via the proxy.
Creating a user for every users authenticating via the proxy defeats the convenience of using external authentication sources. Can I just assign users to a default role instead?