Splunk® Enterprise

Securing the Splunk Platform

Acrobat logo Download manual as PDF

Acrobat logo Download topic as PDF

Configure SAML SSO using configuration files

With Splunk Enterprise, you can use configuration files to configure it for single sign-on (SSL) authentication using the Security Assertion Markup Language (SAML) authentication scheme. By using configuration files, you can:

  • Configure how the instance performs authentication, with authentication.conf
  • Configure security and identity provider (IdP) certificates, with web.conf
  • Configure your identity provider
  • Secure your SAML configuration

Prerequisites to configuring SAML SSO with configuration files

Before you can configure SAML SSO using configuration files, you must have the following:

  • Access to the Spunk Enterprise instance, including where the configuration files reside, as an administrator
  • An understanding of what the configuration files do
  • A text editor

Configure SSO using SAML with authentication.conf

Splunk Enterprise always has native authentication available. If you configure the instance to use SAML as an authentication scheme, and the IdP you provide is not available, you can always log in as a local Splunk user.

The following procedures provide the minimum amount of settings you need to configure. You might need to configure additional settings based on the available features of your IdP.

Configure basic SSO using SAML with authentication.conf

When you configure SAML SSO using authentication.conf, you must supply values for authenticating into your SAML identity provider, SAML to Splunk role mappings, and optionally, any IdP certificates and Attribute Query Request (AQR) URLs.

Following is a table of the most common settings; you can view all of the settings and their default values in the authentication.conf specification file. See Authentication.conf.spec in the Admin Manual.

Setting name Setting type Description Necessity
[authentication] stanza
authSettings string Refers to a separate stanza that contains information on how to interact with the SAML IdP for SSO. The value can be anything, but must reference a stanza with the same name in the configuration file. The Splunk Enterprise instance cannot log into the SAML IdP if you do not set this value. Required
authType string The authentication scheme that Splunk Enterprise should use when performing authentication. To log into a SAML IdP, you must set this to SAML. Required
[authSettings reference stanza]
entityId string The identifier for this Splunk Enterprise instance that is unique across all entities on the IdP. The IdP provides this information, and the Splunk Enterprise instance cannot authenticate into the IdP without it. Required
idPSSOUrl string The protocol endpoint on the IdP where Splunk Enterprise should send authentication requests. The instance cannot authenticate into the IdP without this information. Example: https://your path/idp/SSO.saml2. Required
redirectPort positive integer The network port where the Splunk Enterprise instance is to send SAML responses. Required
idPSLOUrl string The protocol endpoint on the IdP that Splunk Enterprise uses to log the user out. While this setting is not required, if you don't supply it, the user that Splunk Enterprise uses to log into the IdP will not be logged out. Example: https://your path/idp/SLO.saml2 Optional
IdPCertPath string The location on the Splunk Enterprise instance where you store the certificates that the instance uses to connect to the IdP over SSL. This can be either a file or a directory name depending on how you configure the certificates, and Splunk Enterprise starts from the $SPLUNK_HOME/etc/auth/idpCerts directory on the instance when it looks for the certificates. See the setting entry in the Authentication.conf specification file in the Admin Manual for more detailed information. Example: /opt/splunk/saml-install/etc/auth/ping_idp.crt Depends [1]
idPAttributeQueryUrl string The URL of the endpoint on the IdP where Splunk Enterprise is to send attribute query requests. This lets the instance get the latest SAML role information. Use this setting only if your IdP supports AQR. Example: https://your path/idp/attrsvc.ssaml2 Depends [2]
attributeQueryRequestSigned Boolean Whether or not the Splunk Enterprise instance signs attribute query requests. Optional
attributeQueryResponseSigned Boolean Whether or not The Splunk Enterprise instance verifies the signature in the response using the certificate of the IdP. Optional
attributeQuerySoapUsername string The username that the Splunk Enterprise instance is to use when it makes an attribute query request. Depends [2]
attributeQuerySoapPassword string The password that the Splunk Enterprise instance is to use when it makes an attribute query request. The password must be valid for the user you supply in the 'attributeQuerySoapUsername' setting. Depends [2]
attributeQueryTTL positive integer The amount of time, in seconds, that the Splunk Instance caches the user and role information that it retrieves from the IdP. If this time has not elapsed since the last query of the IdP, Splunk Enterprise does not query the IdP for user information. Depends [2]
signAuthnRequest Boolean Whether or not The Splunk Enterprise instance is to sign authentication requests. Optional
signedAssertion Boolean Whether or not the Splunk Enterprise instance verifies the assertion that it receives from the IdP using the IdP certificate. The instance accepts both signed and encrypted assertions from an IdP, and configuring this setting to "false" does not affect assertions that have been encrypted. Optional
[roleMap_SAML] stanza
<splunk role name> semicolon-separated list An explicit mapping of LDAP groups from the IdP to Splunk roles on the Splunk Enterprise instance. Do not use spaces when supplying multiple SAML roles. Use a separate line for each Splunk role. Optional

1: This setting is required only if you use SSL to connect securely to the IdP. 2: If you configure the 'IdPAttributeQueryUrl' setting, you must also configure this setting.

  1. Using a text editor, open the $SPLUNK_HOME/etc/system/local/authentication.conf.
  2. In the file, add the authentication stanza to configure the instance to use SAML as an authentication scheme:
    [authentication]
    authSettings = saml_settings
    authType = SAML
    
  3. Add the [saml_settings] stanza to specify settings that are specific to your IdP:
    [saml_settings]
    entityId = <string>
    idpAttributeQueryUrl = <string>
    idpCertPath = <string>
    idpSSOUrl = <string> 
    idpSLOUrl = <string>
    redirectPort = <positive integer>
    attributeQueryTTL = <positive integer>
    signAuthnRequest = <boolean>
    signedAssertion = <boolean>
    attributeQueryRequestSigned = <boolean>
    attributeQueryResponseSigned = <boolean>
    attributeQuerySoapPassword = <string>
    attributeQuerySoapUsername = <string> 
    
  4. Add the [roleMap_SAML] stanza to specify the Splunk roles that map to the SAML roles of the IdP:
    [roleMap_SAML]
    <splunk role 1> = <LDAP group 1>;[<LDAP group N>…]
    [<splunk role 2> = <LDAP group 1>;[<LDAP group N>…]]
    
  5. Save the file and close it
  6. Restart The Splunk Enterprise instance to apply the changes.

Configure SAML SSO for Microsoft Azure IdP or Active Directory Federation Services (ADFS)

To configure single sign-on with Azure AD or ADFS, add the following additional attributes:

nameIDFormat = (optional) Specify the format of the subject that is returned in the SAML response. 
AzureAD returns a string to identify the subject and this attribute lets you optionally specify a 
different format (we recommend email address). This can be useful for auditing and saved 
searches. To specify email address as the format, use: 
<code>urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress</code>

role = Populate this field if you use Azure AD for SSO or ADFS. This value tells Splunk Enterprise 
the attribute that supplies role information in the SAML response returned. For Azure AD, use: 
<code>http://schemas.microsoft.com/ws/2008/06/identity/claims/groups</code>

mail = This value maps the alias to the user email addresses in the SAML response returned. 
For Azure AD, use: <code>http://schemas.microsoft.com/identity/claims/displayname</code>

realName = This tells Splunk Enterprise where to map the real name in the SAML response 
returned. For Azure AD use: 
<code>http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress</code>.

Use exclusion lists to improve security

Splunk Enterprise supports auto-mapped roles by default. This means that if the IdP returns Splunk roles in an assertion, Splunk Enterprise uses those roles to process the login. If you don't want this to happen, you can turn off auto-mapping for roles by using authentication.conf.

Use the excludedAutoMappedRoles setting to add the list of roles that you don't want Splunk Enterprise to use if it receives them from the IdP. Supply a comma-separated list of all the roles to which this restriction is to apply.

excludedAutoMappedRoles = <comma-separated list>

You can secure your Splunk Enterprise instance further by preventing users on the excluded list from logging in. Use the excludedUsers setting to accomplish this task. When the IdP returns an assertion, Splunk Enterprise ignores the users that are in that assertion.

If your Splunk Enterprise instance uses the defaultRolesIfMissing setting, and the IdP does not send role information in its assertion, Splunk Enterprise uses the defaultRolesIfMissing setting to complete this information.

excludedUsers = <comma-separated list>

Do not configure defaultRolesIfMissing with the "Admin" role. The Admin role is temporarily used to send group information in the SAML assertion until the IdP is configured.

Supported exclude list role and group formats

User and group names are not case-sensitive. Splunk Enterprise converts usernames to lower case and stores them. If the IdP expects the username in the NameId in the exact case that it was sent to Splunk, this might result in an error.

Splunk supports group information in the following formats:

DN format

<saml:AttributeStatement>
<saml:Attribute Name="role"
                            NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic"
                            >
                <saml:AttributeValue xsi:type="xs:string"
                                     xmlns:xs="http://www.w3.org/2001/XMLSchema"
                                     xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
                                     >CN=Employee,OU=SAML Test,DC=qa,DC=ad2r2,DC=com</saml:AttributeValue>
                <saml:AttributeValue xsi:type="xs:string"
                                     xmlns:xs="http://www.w3.org/2001/XMLSchema"
                                     xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
                                     >CN=User Admin,OU=SAML Test,DC=qa,DC=adr2,DC=com</saml:AttributeValue>
            </saml:Attribute>
</saml:AttributeStatement>

Strings format

<saml2:AttributeStatement>
<saml2:Attribute Name="role" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic">
<saml2:AttributeValue xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="xs:string">Super Admin</saml2:AttributeValue>
<saml2:AttributeValue xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="xs:string">Everyone</saml2:AttributeValue>
</saml2:Attribute>
…
</saml2:AttributeStatement>

Semicolon separated lists

<saml:Attribute NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic"
                            Name="role"
                            >
                <saml:AttributeValue xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
                                     xsi:type="xs:string"
                                     >role_splunktest;role_admin</saml:AttributeValue>
</saml:Attribute>

Splunk Roles

<saml:Attribute NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic"
                            Name="role"
                            >
                <saml:AttributeValue xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
                                     xsi:type="xs:string"
                                     >admin</saml:AttributeValue>
</saml:Attribute>

Configure web.conf and optionally add a failure redirect address

Add the following values to your settings stanza in web.conf

[settings]
appServerPorts = 7065 <make sure this attribute is enabled>

ssoAuthFailureRedirect = http://10.140.31.19:7000/ui/en-us/account/sso_error 
<this is your custom user redirect for failed logins>

Configure certificate replication for search head clusters

Splunk Enterprise uses certificate replication to allow SAML single sign-on in a search head cluster environment. If a search head cluster is set up and certificate replication is turned on, then IdP certificate files are replicated across that search head cluster.

The is enabled by default and if there is not a configured search head cluster, the system ignores the attribute.

In authentication.conf turn on certificate replication:

replicateCertificates = true / false

Configure your identity provider

Now you must configure your IdP to import Splunk software metadata. To import Splunk software metadata on your IdP, make sure that the AuthnRequest signing and AttributeQuery request signing setting is compatible on Splunk software and the IdP:

  1. Export the IdP certificate onto a file in your Splunk software instance.
  2. Make sure that authentication.conf points to this certificate in the SAML configuration stanzas.
  3. Import the Splunk software server certificate (server.pem) into the IdP for signature verification.

Note that you can export Splunk software metadata using the /saml/spmetadata endpoint on Splunk Web. You can also access the SAML-sp-metadata endpoint on splunkd.

Secure your SAML configuration

SAML attribute query service supports all of the standard SSL settings for Splunk Enterprise to perform TLS verification between Splunk Instance and SOAP instance providing AttributeQuery service.

In general, TLS encryption only works with an IdP that supports attribute queries. However, the sslKeysFile and sslKeysFilePassword attributes will work for any IdPs.

For more information about TLS encryption, see Configure SSO with TLS certificates

Last modified on 01 September, 2020
PREVIOUS
Modify or remove role mappings
  NEXT
SAML SSO best practices

This documentation applies to the following versions of Splunk® Enterprise: 8.0.6, 8.0.7, 8.1.0


Was this documentation topic helpful?

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

Please try to keep this discussion focused on the content covered in this documentation topic. If you have a more general question about Splunk functionality or are experiencing a difficulty with Splunk, consider posting a question to Splunkbase Answers.

0 out of 1000 Characters