Configure SAML SSO in the configuration files
This topic explains how to set up SSO for SAML v2 using configuration files:
- Configure
authentication.conf
andweb.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
Modify or remove role mappings | Troubleshoot SAML SSO |
This documentation applies to the following versions of Splunk® Enterprise: 7.0.0, 7.0.1, 7.0.2, 7.0.3, 7.0.4, 7.0.5, 7.0.6, 7.0.7, 7.0.8, 7.0.9, 7.0.10, 7.0.11, 7.0.13, 7.1.0, 7.1.1, 7.1.2, 7.1.3, 7.1.4, 7.1.5, 7.1.6, 7.1.7, 7.1.8, 7.1.9, 7.1.10, 7.2.0, 7.2.1, 7.2.2, 7.2.3, 7.2.4, 7.2.5, 7.2.6, 7.2.7, 7.2.8, 7.2.9, 7.2.10, 7.3.0, 7.3.1, 7.3.2, 7.3.3, 7.3.4, 7.3.5, 7.3.6, 7.3.7, 7.3.8, 7.3.9, 8.0.0, 8.0.1, 8.0.2, 8.0.3, 8.0.4, 8.0.5
Feedback submitted, thanks!