Admin Manual

 


Use single sign-on (SSO) with Splunk

NOTE - Splunk version 4.x reached its End of Life on October 1, 2013. Please see the migration information.

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 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:

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 REMOTE_USER with the correct value. However, if the proxy also passes a user-supplied REMOTE-USER after the rewritten REMOTE_USER, cherrypy will overwrite HTTP_REMOTE_USER with the user-supplied REMOTE-USER value.

To prevent name space collisions and resulting security issues, configure the proxy to not pass REMOTE-USER at all, or make sure that REMOTE_USER with the proxy-rewritten variable is passed after the user-supplied REMOTE-USER.

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 strict Specifies the SSO mode for Splunk Web. The value is either "permissive" or "strict":
  • Permissive mode honors incoming requests from IPs not specified in the trustedIP setting but refuses to use SSO authentication if it receives requests from these unsupported IPs.
  • Strict mode completely shuts down all requests unless they originate from an IP address specified in the trustedIP setting.


Example:

[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".

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.3 , 4.3.1 , 4.3.2 , 4.3.3 , 4.3.4 , 4.3.5 , 4.3.6 , 4.3.7 View the Article History for its revisions.


You must be logged into splunk.com in order to post comments. Log in now.

Was this documentation topic helpful?

If you'd like to hear back from us, please provide your email address:

We'd love to hear what you think about this topic or the documentation as a whole. Feedback you enter here will be delivered to the documentation team.

Feedback submitted, thanks!