Configure SAML SSO using configuration files

On Splunk Enterprise, you can use configuration files to set up 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 the authentication.conf file
• Configure security and identity provider (IdP) certificates, with the web.conf file
• 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 the authentication.conf file

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 that you need to configure. You might need to configure additional settings based on the available features of the IdP you use.

Configure basic SSO using SAML with the authentication.conf file

When you configure SAML SSO using the authentication.conf configuration file, 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 is to 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 is to 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 settings and values to the authentication.conf file:

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 setting 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 the authentication.conf file.

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

Splunk Enterprise does not support group information in the strings format when your IdP uses AQRs.

<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

Splunk Enterprise does not support group information in the semicolon-separated list format when your IdP uses AQRs.

<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