Configure authentication extensions to interface with your SAML identity provider

When you configure a Splunk platform instance to use a single sign-on scheme that uses the Security Assertion Markup Language (SAML), you might have to create or configure authentication extensions depending on the identity provider (IdP) that the instance connects to.

Authentication extensions are scripts that interface with an IdP in the following scenarios:

• When a user logs in to the Splunk platform instance initially for some IdPs, like Microsoft Azure
• When a logged-in user performs a task, and the Splunk platform instance needs to fetch information about that user to confirm that they can perform that task. This includes non-interactive tasks such as running saved searches

Authentication extensions bridge the gap between the Splunk platform and identity providers that do not support Attribute Query Requests

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. Identity providers (IdPs) can either support AQRs or not. In general, if the IdP does not support AQRs, then you must 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 activate the extensions using Splunk Web or configuration files.

• If the IdP that you use supports AQRs, this content does not apply to you. You can configure authentication tokens as you would with any other type of authentication scheme, and the authentication system will log users in or retrieve information as needed without further configuration. See Create authentication tokens for instructions.
• 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 your Splunk platform instance interacts with a SAML IdP that does not support AQRs, the instance cannot process logins and get information about a user natively, as it can with IdPs that do support AQRs. Splunk has implemented authentication extensions to address the problem of login processing and user information retrieval on IdPs that cannot provide that information natively.

Authentication extensions are Python scripts. You configure the Splunk authentication system to activate the extension by supplying the required arguments to the extension. In Splunk Cloud, you can use Splunk Web to activate the extension. In Splunk Enterprise, you can either use Splunk Web or configure with a file.

Description of the authentication extensions that Splunk ships

Splunk includes authentication extensions for the Microsoft Azure and Okta IdPs. To use the extensions, you must activate them. Activated extensions run when the authentication system initiates contact with the SAML IdP to log users in or periodically retrieve their information.

On both Splunk Cloud and Splunk Enterprise, you can activate the extensions using the SAML configuration page in Splunk Web.

On Splunk Enterprise only, you can also activate the scripts using the authentication.conf configuration file and, if necessary, modify the scripts so that they work with your specific IdP.

The following extensions ship with both Splunk Cloud and Splunk Enterprise:

Extension name	Description
SAML_script_azure.py	You can use this extension if you use Microsoft Azure as a SAML IdP. The script addresses the fact that Microsoft Azure does not support AQRs, and deals with situations where either Azure has been configured to have nested groups for its users, or when an Azure user is a member of more than 150 groups. It contains a getUserInfo script function that retrieves an Azure user name, friendly name, and a list of groups as a set. It also has a login script function that returns a list of groups using the same method when you supply a valid Azure username on login.
SAML_script_okta.py	You can use this extension if you use Okta as an IdP. The script addresses the fact that Okta does not support AQRs, and offers an alternative method for logging in when IdPs use a different entity type. It contains a getUserInfo script function which processes Okta logins, but does not contain a login script function.
commonAuth.py	The Okta and Azure extensions rely on this extension for necessary script support. Do not make changes to this extension.

On a Splunk Enterprise instance, authentication extensions must reside in the $SPLUNK_HOME/etc/auth/scripts directory.

Authentication extension script functions assist with login processing and SAML user information retrieval

The authentication extensions that come with the Splunk platform include script functions for processing SAML user logins and user information retrieval. These script functions are what specifically help the Splunk platform properly interact with the IdP. Not every extension includes all of these functions.

When you activate an extension for an IdP, you specify which script functions in the extension that the auth system is to use.

Setting	Description
getUsers	This script function lets the Splunk authentication system retrieve users to populate the SAML user cache with information when the Splunk platform initially starts up. This script function is not supported in Splunk Cloud. On a Splunk Enterprise deployment, you must create this function on your own.
getUserInfo	This script function lets the auth system 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, for example, on Microsoft Azure. The extensions that Splunk includes for both Microsoft Azure and Okta use this script function to ensure that the Splunk platform can connect successfully to those IdPs.
login	This script function lets the auth system perform post-processing on information that the IdP returns after a successful SAML login. This function is used, for example, on 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 script function, the SAML response to the login request appears to be empty because it contains no groups, and the auth system treats that response as an incomplete login. This script function was created specifically to process logins when Microsoft Azure is the IdP.

Authentication extensions use script secure arguments to make authorized calls to identity providers

When you activate authentication extensions, you must supply what are known as script secure arguments to the extensions. The authentication system provides script secure arguments to the extension, which then uses the arguments to make authorized calls to access resources on the IdP and retrieve the user information that the extensions need.

For example, if you configure the getUserInfo script function in the Microsoft Azure authentication extension, the extension supplies a set of script secure arguments to the IdP as part of the authentication process. The IdP returns an object that contains the authentication token, which the extension can then use to retrieve user attributes and group membership.

Details of the login and user information retrieval process using authentication extensions

The Splunk authentication system communicates with IdPs in two scenarios:

• When a user logs in
• When a user who is logged in performs a task on the Splunk platform instance, and the user information cache has expired. A task can be either interactive or not, such as a user running a saved search

In these scenarios, the following general sequence happens. The sequence might differ slightly based on the IdP you use:

1. The auth extension contacts the IdP.
2. The extension uses the script secure arguments that you supply, such as the client ID, client secret, and tenant ID in the case of Microsoft Azure, or the Okta API key, in the case of Okta, to contact the IdP.
3. On Microsoft Azure, if the authentication attempt is successful, the IdP sends an authentication token back to the extension.
4. The extension builds a URL string for the username, based on the user that is attempting to or has already logged in.
5. It supplies the username URL string and the authentication token back to the IdP.
6. If that is successful, the IdP returns an object that contains the user attributes. The extension parses this object.
7. The extension then builds a group URL string. The string can change based on the script secure arguments that you supply when you configure the extension.
8. The extension then sends the group URL string and the authentication token back to the IdP.
9. If that is successful, the IdP returns an object that contains the groups of which the user is a member. Depending on the total number of groups, the extension might have to make multiple requests to the IdP to retrieve the group information.
10. The extension caches the user information it has received, for as long as the "get user time to live" period lasts.
11. If you activated the getUserInfo script function for an extension, the extension returns the username, friendly name, and a string of roles to the authentication system.
12. The auth system uses this information to map the groups it received from the extension to Splunk roles, as you configured them, so that the user who logged in only has access to resources that those roles allow.

Configure and activate authentication extensions to interface with your identity provider

You can configure authentication extensions using either Splunk Web or configuration files. You must have already configured the Splunk Enterprise instance to use SAML as an authentication scheme before you configure authentication extensions.

Control how often an activated extension interacts with your identity provider

When you configure an authentication extension to connect to your IdP to obtain user attributes, you must understand how the local user information cache on the Splunk platform instance determines when the authentication system uses extensions to communicate with the IdP. The "get user info time-to-live" setting controls this behavior.

When you perform a task as a logged in user, the authentication system checks the user information cache to see if the information in this cache is older than the "get user info time-to-live". If it is, then the authentication system contacts the IdP using the extension and retrieves user information, then updates the local user information cache. You can set the "get user info time to live" either in Splunk Web or by using the authentication.conf configuration file.

If you set the "get user info time-to-live" too low, the authentication system makes more calls to the IdP for get user information, which can result in performance degradation on your IdP, depending on the number of other clients that interact with the IdP. If you set it to high, the authentication system makes fewer calls to the IdP, which can result in users retaining access to things that they should not because of the increased interval between user information retrievals.

Configure authentication extensions for Microsoft Azure using Splunk Web

1. Log into your Splunk Enterprise instance as an administrator-level user.
2. From the system bar, Click Settings > Authentication Methods.
3. Click "Configure Splunk to use SAML". The "SAML configuration" dialog box appears.
4. In the Script path field within the Authentication Extensions section of the "SAML configuration" dialog box , type in SAML_script_azure.py.
5. In the Script timeout field, type in 300s.
6. In the Get User Info time-to-live field, type in 3600s.
7. Click the Script functions field.
8. In the pop-up window that appears, click getUserInfo.
9. Under Script Secure Arguments, click Add Input.
10. In the Key field, type in clientID.
11. In the Value field, type in the Azure client ID.
12. Repeat Steps 9-11 as necessary to add the other script secure arguments shown in the table after this procedure..
13. Repeat Steps 7-8 to add the login script function.
14. Repeat Steps 9-11 to add the same Script Secure Arguments for the login script function that you did for the getUserInfo script function.
15. Click Save. Splunk Cloud saves the Azure configuration and returns you to the SAML Groups page.

Script Secure Argument	Value
clientSecret	The Azure client secret that the Splunk platform should use for authentication
tenantId	The Azure tenant ID value
groupType (Optional)	transitive (If you want the Splunk platform to retrieve roles that are in nested groups within the Azure environment)

Configure authentication extensions for the Okta identity provider

1. Log into Splunk Enterprise as an administrator level user.
2. From the system bar, click Settings > Authentication Methods.
3. Click "Configure Splunk to use SAML". The "SAML configuration" dialog box appears.
4. In the Script path field within the Authentication Extensions section of the "SAML configuration" dialog box , type in SAML_script_okta.py.
5. In the Script timeout field, type in 300s.
6. In the Get User Info time-to-live field, type in 3600s.
7. Click the Script functions field.
8. In the pop-up window that appears, click getUserInfo.
9. Under Script Secure Arguments, click Add Input.
10. In the Key field, type in apiKey.
11. In the Value field, type in the API key for your IdP.
12. Repeat Steps 9-11 as necessary to add the other script secure arguments shown in the table after this procedure.
13. Click Save. Splunk Cloud saves the Okta configuration and returns you to the SAML Groups page.

Script Secure Argument	Value
baseURL	The URL of your Okta instance.
OKTA_USER_SEARCH_INPUT (Optional)	The attribute that the script function is to use as the username attribute for authentication or user info retrieval. Use this script secure argument when you have configured the IdP to use a different attribute for user logins, like, for example, the samAccountName attribute. This argument is specific to the Okta auth extension.

Configure authentication extensions using configuration files

On Splunk Enterprise only, you can also configure authentication extensions using the authentication.conf configuration file. You must have already configured the authentication system to use SAML as an authentication scheme.

1. Open a shell prompt.
2. Change to the $SPLUNK_HOME/etc/auth/scripts directory on your Splunk Enterprise instance. You might need to create this directory if it does not exist.
3. Copy the commonAuth.py script from the $SPLUNK_HOME/share/auth/scriptSamples directory to the $SPLUNK_HOME/etc/auth/scripts directory.
4. Depending on the IdP you use for SAML, do one of the following:
   • If you use Microsoft Azure or Okta for an IdP, copy the Azure or Okta extensions from the $SPLUNK_HOME/share/auth/scriptSamples directory to $SPLUNK_HOME/etc/auth/scripts. You might need to edit these extensions depending on your specific use case.
   • If your IdP is neither of these, you can use or modify either of the scripts, or write your own script.
5. (Optional) Use a text editor to modify the IdP-specific script to include specific information about your IdP. The information that you provide here depends specifically on the IdP that you use for SAML.
6. Change to the $SPLUNK_HOME/etc/system/local directory.
7. Using a text editor, create or edit the authentication.conf configuration file. At a minimum, add the following entries to the file:

   [samlsettings-<yourkey>]

scriptPath = <name of authentication extension> scriptFunctions = login;getUserInfo scriptSecureArguments = <key:value>;[<key:value>;...]

1. Restart the Splunk platform.
2. Log into the Splunk platform as a known SAML user and confirm that login is successful.

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

Setting	What it does
scriptPath	The name of the extension that performs the connection to the IdP during the login or user retrieval process. Splunk includes two scripts for Microsoft Azure and Okta, SAML_script_azure.py and SAML_script_okta.py. You can use these scripts if you use one of those IdPs, or modify either as a base for a custom script for your IdP.
scriptFunctions	The script functions that the extension is to use when it connects to the IdP to log in or retrieve user information. In nearly all cases, this is one of "getUserInfo" or "login". What script function you use depends on your IdP and the type of user information that the IdP accepts. The Azure script has a "getUserInfo" function with different methods for retrieving groups depending on how you configured the IdP.
getUserInfoTTL	Determines how long the Splunk platform retains user information that it has retrieved from the IdP. When this time expires, the Splunk platform considers the user information it has in its cache stale, and makes a new connection to the IdP the next time a user either logs into or performs a task on the Splunk platform. See "Control how often an activated extension interacts with your identity provider" earlier in this topic.
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 attributes that the extension needs to initiate a connection to the IdP for login or user information retrieval. You must provide these items in <key:value> format, for example clientID:myAzureClientId. Separate multiple key-value pairs with a semicolon.

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

Troubleshoot problems with authentication extensions

When a script function within an authentication extension runs, it takes in various arguments and returns results that it receives from an IdP assertion. Typically, the auth system supplies the arguments and processes their input automatically. If you use Splunk Enterprise, you can also run the authentication extensions manually using a Python interpreter to troubleshoot a problem with group information retrieval.

The following table lists the arguments that the script functions take from and the results that they return to the auth system. When you run the scripts manually, you must supply the arguments in the shown format:

Setting	Arguments	Returns
getUserInfo	--username=<username> --encodedOutput=true|false The --encodedOutput argument tells the auth system to expect and decode output that the extension has encoded into the base64 encoding scheme. This lets you generate output in cases where groups that the extension retrieves from the identity provider contain colons or semicolons.	--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>; --encodedOutput=true|false <roles>	--status=success|fail --groups=<group> --groups=<group> ...

---