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. You can use the script to query users on an Azure IdP by either their principal name, object ID, or e-mail address,
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.

   Authentication extensions have a retrieval limit of 1000 groups. If a user on an IdP is a member of more than 1000 groups, the extension only retrieves the first 1000 groups it finds.

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.

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 too 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 and activate authentication extensions to interface with Microsoft Azure

You must have already configured the Splunk platform instance to use SAML as an authentication scheme before you can configure authentication extensions.

There are two steps to configuring authentication extensions for Microsoft Azure: The first is configuring your Microsoft Azure tenant to allow authentication extensions to run against it. The second is to configure the extension to interface with Microsoft Azure.

Configure your Microsoft Azure tenant to let authentication extensions run on it

Before you can configure authentication extensions to run on Microsoft Azure, you must configure Microsoft Azure to let scripts run on the Azure tenant. If you do not log into Azure as an administrative user, the following described items might not appear or be available to you.

1. Log into Microsoft Azure as an administrative user for your tenant.
2. Select Azure Active Directory.
3. In Azure Active Directory, select App Registrations.
4. Select the All Applications tab.
5. Use the search field to locate your Splunk Azure app configuration under "All Applications".
6. Select the Azure app configuration after you locate it to display its properties.
7. In the Properties page for your app, select API Permissions.
8. Select Add a Permission.
9. Select Microsoft Graph > Application Permissions.
10. In the search field, type in "User.Read.All". The permissions list updates to show permissions that match what you typed.
11. Select the User drop-down permission.
12. Check "User.Read.All".
13. Select Add permissions.

    Certain secure scripted arguments that appear in the following script secure argument configuration table might require additional permissions.

14. On the "API Permissions" page, select Grant admin consent for <directory>. The "Status" for the permission you configured updates to say "Granted for <directory>".

Changes take effect immediately. You can close the browser window that has the connection to Azure.

Configure authentication extensions for Microsoft Azure using Splunk Web

Configure authentication extensions from Splunk Web on the Splunk platform instance where you want the extensions to run.

Splunk Enterprise versions 9.2 and higher, and Splunk Cloud Platform versions 9.2.2403 and higher introduced the groupAttribute setting, which lets you specify the Group property that the extension is to return. By default, the extension returns the id property for backwards compatibility.

1. Log into your Splunk Enterprise instance as an administrator-level user.
2. From the system bar, Select Settings > Authentication Methods.
3. Select 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. Select the Script functions field.
8. In the pop-up window that appears, select getUserInfo.
9. Under Script Secure Arguments, select 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.

    The login script function uses the same script secure arguments as the getUserInfofunction.

14. Select Save. Splunk Cloud saves the Azure configuration and returns you to the SAML Groups page.

Configure this script secure argument	With this value	Required?
clientSecret	The Azure client secret that the Splunk platform should use for authentication	Yes
tenantId	The Azure tenant ID value	Yes
azureUserFilter	The attribute that the script function is to use as the username attribute for authentication or user info retrieval.	No
encodeOutput	false if the Azure user name contains special symbols and you don't want the authentication extension to encode its output. By default the authentication extension encodes its output (encodeOutput=true)	No
servicePrincipalId	The "Object ID" retrieved from the "Enterprise Application Overview" page for the Azure SSO application. Requires the Application.Read.All Azure API permission.	No
groupAttribute	The attribute that the script function is to use as the group attribute for retrieving a list of groups for a user. By default, the authentication extension retrieves the Azure group's object IDs. Requires the Group.Read.All Azure API permission.	No
groupSearchFilter	The attribute that the script function is to use to filter user's groups. The supplied value is appended to the end of the API request verbatim. The filter must begin with '$'. Requires the Group.Read.All Azure API permission. Example: $filter=startswith(displayName, 'a')&$count=true	No

Configure and activate authentication extensions to interface with Okta

You must have already configured the Splunk platform instance to use SAML as an authentication scheme before you can configure authentication extensions.

Unlike with Microsoft Azure, you do not need to perform any setup on the IdP prior to configuring authentication extensions

Configure authentication extensions for the Okta identity provider in Splunk Web

1. Log into Splunk Enterprise as an administrator level user.
2. From the system bar, select Settings > Authentication Methods.
3. Select "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. Select the Script functions field.
8. In the pop-up window that appears, select getUserInfo.
9. Under Script Secure Arguments, select 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. Select Save. Splunk Cloud Platformsaves the Okta configuration and returns you to the SAML Groups page.

Script Secure Argument	Value
baseUrl	The URL of your Okta instance. Must begin with either http:// or https://.
oktaUserSearch (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.
encodeOutput (Optional)	false (If the Okta user's name contains special symbols and you don't want the authentication extension to encode its output)

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>;...]

8. Restart the Splunk platform.
9. 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

If an authentication extension that you configured doesn't run as you expect, or doesn't run at all, you can use this section to find and fix potential problems.

Troubleshoot authentication extension errors

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.

You can find more information about how an authentication extension ran by reviewing the following log files:

Auth Extension	Detailed log file name	Search string
SAML_script_azure.py	$SPLUNK_HOME/var/log/splunk/scripted_authentication_azure.log	index="_internal" source="*splunk_scripted_authentication_azure.log"
SAML_script_okta.py	$SPLUNK_HOME/var/log/splunk/scripted_authentication_okta.log	index="_internal" source="*splunk_scripted_authentication_okta.log"

The log file that the Splunk platform instance generates depends on the authentication extension that you use. If an error occurs, it also appears in the $SPLUNK_HOME/var/log/splunk/splunkd.log file. The individual log files for each script contain more detailed information about the error. The following procedure lets you view the log files directly on the Splunk platform instance:

1. Open the Search app on your Splunk platform instance. From the Splunk Cloud system bar, select Apps > Search & Reporting.
2. Copy the search string from the "Search string" column of the previous table for the authentication extension that you are using.
3. Paste this search string into the search bar on the Search & Reporting page.
4. Run the search. The Splunk platform returns logs that match the string you entered.
5. Review the search results. Errors have a tag of ERROR and warnings have a tag of WARNING. All other activity includes the INFO tag. These tags can help you identify problems that are happening with the authentication extension.

Troubleshoot problems with the Microsoft Azure authentication extension

The following table lists some common problems that can happen when you use the authentication extension for Microsoft Azure. Follow the procedures in the table to address the problem that matches or is close to the problem you are experiencing.

Log file error message	Problem	Solution
It appears your clientId and/or tenantId are incorrect. Please refer to the Microsoft docs to retrieve those values: https://docs.microsoft.com/en-us/azure/active-directory/develop/howto-create-service-principal-portal#get-tenant-and-app-id-values-for-signing-in	tenantId or clientId is not valid	Refer to the official Azure documentation to retrieve the Application (client) ID and Directory (tenant) ID
It appears your clientSecret is incorrect. Please refer to the Microsoft docs to retrieve that value: https://docs.microsoft.com/en-us/azure/active-directory/develop/howto-create-service-principal-portal#option-2-create-a-new-application-secret	clientSecret is not valid	Refer to the official Azure documentation to create a new Client secret https://docs.microsoft.com/en-us/azure/active-directory/develop/howto-create-service-principal-portal#option-2-create-a-new-application-secret
You do not have sufficient API privileges. Please refer to the Splunk docs to set API privileges for your Azure AD application	You haven't enabled API permissions.	See "Configure your Microsoft Azure tenant to let authentication extensions run on it" earlier in this topic.
Unable to get user info for username=nonexistent. This script only officially supports querying usernames by the User Principal Name, Object ID, or Email properties. To use other user properties, please use the 'azureUserFilter' argument and refer to the Graph API docs fo r a full list of properties: https://docs.microsoft.com/en-us/graph/api/resources/user?view=graph-rest-1.0#properties	The extension couldn't find the user you specified	Check if the username used to query the authentication extension exists and the value of the "azureUserFilter" if it is used
You might be trying to use a filter property that does not exist. Please refer to the Graph API docs for a full list of supported properties: https://docs.microsoft.com/en-us/graph/api/resources/user?view=graph-rest-1.0#properties	The azureUserFilter is not valid	Refer to the Graph API docs for a full list of supported properties: https://docs.microsoft.com/en-us/graph/api/resources/user?view=graph-rest-1.0#properties
Failed to find custom group attribute '<attribute>' in groups API response	The supplied value for the groupAttribute argument does not exist	* Refer to the Graph API docs for a full list of supported properties: https://docs.microsoft.com/en-us/graph/api/resources/user?view=graph-rest-1.0#properties Confirm that you have set the groupAttribute attribute. If you have set it, confirm that you have applied the correct property for this attribute.
Failed to get user group membership for username=<username> with status=<status> and response=<response>	The extension couldn't find any groups for the user. This could be due to an invalid groupSearchFilter if you supplied that attribute.	Look for the error in the response section of the log file.
Failed to get appRoleAssigments for service principal=<servicePrincipalId> with status=<status> and response=<response>	The extension couldn't get the groups that were assigned to the service principal.	Look in the error in the response section of the log file. It is likely that the service principal ID is incorrect.

Troubleshoot problems with the Okta authentication extension

The following table lists some common problems that can happen when you use the authentication extension for Okta. Follow the procedures in the table to address the problem that matches or is close to the problem you are experiencing.

Log file error message	Problem	Solution
It appears your baseUrl and/or apiKey are incorrect. Please check your Okta instance URL and refer to the Okta docs to retrieve the apiKey: https://developer.okta.com/docs/guides/create-an-api-token/create-the-token/	Either baseUrl or apiKey is not valid	Check the Okta URL instance provided and refer to the official Okta documentation to retrieve the API token https://developer.okta.com/docs/guides/create-an-api-token/create-the-token/
The user you are querying (<user>) does not exist	The extension couldn't find the user you specified	Check if the username used to query the authentication extension exists
It appears you are using a search parameter that does not exist. Please refer to the Okta docs for examples: https://developer.okta.com/docs/reference/api/users/#list-users-with-search	The oktaUserSearch argument you supplied is not valid	Refer to the official Okta documentation for a full list of search parameters https://developer.okta.com/docs/reference/api/users/#list-users-with-search
Search query returned an empty response using attribute=<oktaUserSearch value> to do a lookup for value=<user>	The extension couldn't find the user you specified using the oktaUserSearch argument	Check if using correct "oktaUserSearch" and if Okta user has the correct information
Returned more than one result while fetching get user info for username=<username>. Check your search criteria.	The oktaUserSearch argument returned more than one user entry	Check the "oktaUserSearch" value and your Okta users for duplicate information

Authentication extension script functions and their arguments

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> ...

---