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
- Configure security and identity provider (IdP) certificates, with
- 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|
||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|
||string||The authentication scheme that Splunk Enterprise should use when performing authentication. To log into a SAML IdP, you must set this to
|[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 |
|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 |
|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 |
|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 |
|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 |
|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|
|<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.
- Using a text editor, open the $SPLUNK_HOME/etc/system/local/authentication.conf.
- In the file, add the
authenticationstanza to configure the instance to use SAML as an authentication scheme:
[authentication] authSettings = saml_settings authType = SAML
- 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>
- 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>…]]
- Save the file and close it
- 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.
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:
<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>
<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>
<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
[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.
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:
- Export the IdP certificate onto a file in your Splunk software instance.
- Make sure that
authentication.confpoints to this certificate in the SAML configuration stanzas.
- 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
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
sslKeysFilePassword attributes will work for any IdPs.
For more information about TLS encryption, see Configure SSO with TLS certificates
Modify or remove role mappings
SAML SSO best practices
This documentation applies to the following versions of Splunk® Enterprise: 8.0.6, 8.1.0