Configure authentication extensions for SAML tokens

When you configure a Splunk platform instance to use a single sign-on scheme that relies on the Security Assertion Markup Language (SAML), depending on the identity provider (IdP) that the scheme connects to, you might have to create or configure authentication extensions, or scripts, that interface with the IdP to process user logins and fetch user information.

In the context of SAML, an Attribute Query request (AQR) is a request by an entity against an IdP, either by or on behalf of a user, for the purposes of getting more attributes about that user. In general, if the IdP that you use for authentication with SAML does not support AQRs, then you can configure authentication extensions to ensure that login and user information retrieval works successfully. When you configure authentication extensions, you must provide details about how your IdP performs these actions in the scripts, then configure the authentication system to use the scripts in the authentication.conf configuration file.

If the SAML IdP that you use supports AQRs, this content does not apply to you. You can configure tokens as you would with any other type of authentication scheme. Proceed to Create authentication tokens for instructions.
If you are using Splunk Cloud, this content does not apply to you either. While you can use authentication extensions with Splunk Cloud instances, you cannot customize the extensions on those instances in any way. Authentication extension customization can only happen on a Splunk Enterprise instance to which you have direct access.
To learn how to configure authentication extensions, see "Configure authentication extensions" later in this topic.
To learn more about how authentication extensions work, continue reading.

How authentication extensions work with SAML IdPs

When you connect to a SAML IdP that does not support AQRs, there is no way for the auth system to know how to process login and get information about a user natively, as could be done with AQRs.

Splunk has implemented a system where you can configure an authentication extension to perform the login processing and user retrieval functions as a way to interface with an IdP that cannot provide that information natively. In this case, you provide the extension, which is a Python script, configure the Splunk platform to use the extension, supply the required arguments to the extension, and potentially make changes to the extension so that it works with your IdP.

The authentication extensions support two separate script functions:

Setting	Description
`getUsers`	This function lets The Splunk platform retrieve users to populate the SAML user cache with information when The Splunk platform initially starts up.
`getUserInfo`	This function lets the Splunk platform retrieve user information from the IdP as needed, and is a drop-in replacement for AQRs. You can configure an authentication extension to use this script function to gather user information after a successful login as if it did support AQRs.
`login`	This function lets the Splunk platform perform post-processing on information that the IdP returns after a successful SAML login. You can configure this script function in cases where IdPs return information that needs post-processing. An example of such a case is Microsoft Azure, which returns a link to a list of groups when a user that is a member of more than 150 groups logs in. Without this extension, the SAML response to the login request appears to be empty.

As part of configuring the scripts, you can supply the following arguments and process the following returned objects:

Setting Arguments Returns

getUserInfo

--username=<username>

--status=success|fail

--userInfo=<username>;<realname>;<roles>

Notes:

userInfo must specify a semicolon-delimited list.
<username> is required.
<realname> is optional, but its semicolon is required.
<roles> is required. To return multiple roles, use colons to separate the roles.

For example: admin:power
This example returns just the roles for a user named "testUser":

--status=success --userInfo=testUser;Test;admin:power

login

--userInfo=<username>;<realname>;

<roles>

Note: userInfo contains role information that the IdP returns as a SAML assertion.

--status=success|fail

--userInfo=<username>;<realname>;<roles>

Splunk includes sample authentication extensions that work with various well known IdPs that do not support AQRs, such as Azure and Okta. You can make changes to these extensions so that they work with your specific IdP.

You do not need to implement both extensions in your environment for successful SAML logins. You can configure the extensions that best address your specific authentication use case.

Technical information on the authentication extensions

There are two scripts that comprise authentication extensions, both of which exist in the $SPLUNK_HOME/share/splunk/authScriptSamples directory:

commonAuth.py: This script is the base script that retrieves specific arguments from the auth system, as provided by the second, IdP-specific script. It comes with the Splunk Enterprise installation package.
IdP-specific script: This script takes IdP-specific arguments, such as API key, base URL for accessing the IdP, and so on, and initiates contact with the IdP for the purposes of establishing a login session or retrieving user information. The Splunk Enterprise installation package includes several example scripts with support for the Azure and Okta IdPs. You can modify and use these scripts or write a custom script that works with your specific IdP. In any case, you must always include the commonAuth.py script for authentication to work.

These scripts exist in the $SPLUNK_HOME/etc/auth/scripts directory, and changes to authentication.conf activate the scripts when the Splunk platform authentication system initiates contact with the SAML IdP to log in or retrieve user information.

Several settings in authentication.conf control how this process works:

Setting	What it does
`scriptPath`	Performs the connection to the IdP during the login or user retrieval process.
`scriptFunctions`	Provides the functions that the extension should use when connecting to the IdP to log in and retrieve user information.
`getUserInfoTTL`	Determines how long the Splunk platform retains user information that it has retrieved from the IdP.
`getUsersPrecacheLimit`	Determines how many users the Splunk platform instance must put in its SAML user cache when the instance starts up.
`scriptTimeout`	Determines how long the Splunk platform lets the extension run while logging in or retrieving user information from the IdP.
`scriptSecureArguments`	Provides the credentials, tokens, or other items that the extension needs to initiate a connection to the IdP for login or user information retrieval.

For more information on these settings, see authentication.conf in the Admin Manual.

Upon a login attempt on a Splunk platform instance that is configured for SAML, the auth system attempts to log in to the IdP with the authentication extension, using the script functions that you provide. Upon a successful connection to the IdP, it then retrieves user information from the IdP to verify that the user is valid and complete the login process.