Configure SAML SSO in the configuration files

This topic explains how to set up SSO for SAML v2 using configuration files:

• Configure authentication.conf and web.conf in Splunk Enterprise
• Configure your identity provider
• Secure your SAML configuration

Configure authentication.conf

Configure the following stanza in authentication.conf

[authentication]

authSettings = saml_settings

authType = SAML

[roleMap_SAML]

admin = Super Admin;

power = Power Admin;

user = <list roles> Admin;Employee;  

[saml_settings]

entityId = <entityid>

idpAttributeQueryUrl = <optional path to the Attribute query> 
https://your path/idp/attrsvc.ssaml2

idpCertPath = <path to the idp cert in Splunk> 
/home/user/splunk/saml-install/etc/auth/ping_idp.crt.>

idpSSOUrl = <path to the sso url> 
https://your path/idp/SSO.saml2. 

idpSLOUrl = <Logout url> If not specified, this will be treated as 
a typical sso and the logout button is disabled.
https://your path/idp/SLO.saml2 # 

redirectPort=443

attributeQueryTTL = 3600

signAuthnRequest = true

signedAssertion = true

attributeQueryRequestSigned = 
<Set to true if using optional idpAttributeQuerySSL>

attributeQueryResponseSigned = <Set to true if using 
optional idpAttributeQuerySSL>

attributeQuerySoapPassword = <your password>

attributeQuerySoapUsername = <your username> 

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: urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress

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: http://schemas.microsoft.com/ws/2008/06/identity/claims/groups

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

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

Use blacklists to improve security

Splunk supports auto-mapped roles by default, so if Splunk roles are returned in an assertion, Splunk uses them. To turn off auto-mapping for roles, add the list of roles to the blacklistedAutoMappedRoles setting in authentication.conf.

blacklistedAutoMappedRoles = <Comma separated list of splunk roles that should be blacklisted from being auto-mapped by Splunk from the IDP Response>

To prevent blacklisted users from logging in, add the users to blacklistedUsers attribute in authentication.conf. If your Splunk instance is configured to use defaultRolesIfMissing, and role information is missing in the assertion, Splunk uses the defaultRolesIfMissing setting to complete that information.

blacklistedUsers = <comma separated list of user names from the IDP response to be
blacklisted by the Splunk Platform>

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 blacklist role and group formats

User and group names are not case-sensitive manner. Names are converted to lower case and stored. 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 groups 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 software 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 attributequery 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