Set up SAML authentication for Splunk Cloud Gateway

You can set up SAML authentication for your users if you're using Splunk Cloud Gateway and an MDM provider, or if your users are registering using the authentication code. Ping Identity, IBM, CA, and Shiboleth are immediately supported and don't require scripted authentication. Other identity providers (IdPs) are not immediately supported and require scripted authentication.

For user registration steps, see Register a device if your organization uses SAML authentication in the Install and Administer Splunk Cloud Gateway manual.

If you're using Splunk Secure Gateway, see Set up SAML authentication for Splunk Secure Gateway.

Requirements

Use a supported IdP, Splunk platform version, and registration method.

Supported IdPs

Splunk Cloud Gateway works with any IdP that supports Attribute Query Request (AQR), including these identity providers:

• Ping Identity
• IBM
• CA Single Sign-on
• Shibboleth

You can use other IdPs if you set up scripted authentication.

Supported Splunk platform versions and registration methods

See the following compatibility matrix for compatible Splunk platform versions and registration methods:

Splunk platform version	Splunk Cloud Gateway version	Authentication method
Splunk Cloud version 8.1.2009 or higher	Splunk Cloud Gateway version 1.9.0 or higher	Authentication code In-app registration with hostname In-app registration with MDM
Splunk Enterprise version 8.1.0 or higher	Splunk Cloud Gateway version 1.9.0 or higher	Authentication code In-app registration with MDM

Other requirements

To use SAML authentication, you must enable token authentication. Enable token authentication in Settings > Tokens > Enable token authentication in Splunk Web.

Enabling token authentication in Splunk Cloud grants the token_auth role to every user with the sc_admin role. The token_auth role has the following capabilities:

• edit_tokens_all
• edit_tokens_own
• edit_tokens_settings
• list_tokens_all
• list_tokens_own

Users with the token_auth role also receive the scripts necessary to configure scripted authentication for Okta and Azure.

If your users are registering in the mobile app with hostname registration, provide your users your Splunk Cloud instance name. Users enter this in the form of https://<splunk-cloud-instance-name>.splunkcloud.com during in-app registration.

Use Ping Identity, IBM, CA, or Shiboleth

Splunk Cloud Gateway doesn't require scripted authentication with the following IdPs:

• Ping Identity
• IBM
• CA
• Shiboleth

To use one of these providers, enter the provider's Attribute Query Request (AQR) information in Settings > Authentication Methods > SAML Settings > SAML configuration in Splunk Web.

These IdPs don't require any additional configuration, other than entering the AQR information in Splunk Web. If you're using a different IdP, set up scripted authentication so that Splunk Cloud Gateway supports the IdP you're using.

Use an IdP that isn't immediately supported

Set up scripted authentication if you're using an IdP that isn't supported out of the box. First, write a script for SAML authentication. Then, set up scripted authentication for SAML in Splunk Web.

See Create the authentication script for more information about setting up scripted authentication.

Prerequisites

• Have the admin role.
• Obtain an API key value from your IdP.
• Obtain your base URL for your IdP from your IdP.

Write a script for SAML authentication

You can view sample Okta and Azure scripts in $SPLUNK_HOME/share/splunk/authScriptSamples. In the script, define your IdP's base URL and an API key name.

Save the script as a Python file to $SPLUNK_HOME/etc/auth/scripts.

The following is an example script for how to set up SAML authentication with Okta:

from commonAuth import *
import requests
import json

BASE_URL = '<your base URL for your IdP>'
​
def getUserInfo(args):
        # Here, we are extracting the okta API key from authentication.conf under scriptSecureArguments
        API_KEY = args['<API key name>']
        API_KEY_HEADER = 'SSWS ' + API_KEY
        OKTA_HEADERS = {'Accept':'application/json', 'Content-Type':'application/json', 'Authorization':API_KEY_HEADER}
​
        usernameStr = args['username']
        nameUrl = BASE_URL + '/api/v1/users/' + usernameStr
        groupsUrl = nameUrl + '/groups'
​
        nameResponse = requests.request('GET', nameUrl, headers=OKTA_HEADERS)
        groupsResponse = requests.request('GET', groupsUrl, headers=OKTA_HEADERS)
​
        roleString = ''
        realNameString = ''
        fullString = ''
        if groupsResponse.status_code != 200 or nameResponse.status_code != 200:
                print(FAILED)
                return
        nameAttributes = json.loads(nameResponse.text)
        realNameString += nameAttributes['profile']['firstName'] + ' ' + nameAttributes['profile']['lastName']
        groupAttributes = json.loads(groupsResponse.text)
        for i in range(0, len(groupAttributes)):
                roleString += groupAttributes[i]['profile']['name']
                if i != len(groupAttributes) - 1:
                        roleString += ':'
        fullString += SUCCESS + ' ' + '--userInfo=' + usernameStr + ';' + realNameString + ';' + roleString
        print(fullString)
​
if __name__ == "__main__":
        callName = sys.argv[1]
        dictIn = readInputs()
​
        if callName == "getUserInfo":
                getUserInfo(dictIn)

Set up scripted authentication with SAML in Splunk Web

After creating your script, set up scripted authentication with SAML in Splunk Web.

1. In Splunk Web, navigate to Settings > Authentication Methods.
2. Click SAML Settings.
3. Click SAML Configuration.
4. Click Authentication Extensions.
5. In the Script Path field, enter the name of your authentication script.
6. Set script timeout and Get User Info time-to-live. Recommended value is 3600s.
7. In the Script Functions field, enter getUserInfo.
8. In the Script Secure Arguments section enter the following information:
   1. Enter the API key name from your authentication script in the Key field.
   2. Enter the API key from your IdP in the Value field.
9. Click Save.

(Optional) Use SAML authentication with Mobile Device Management (MDM)

MDM is required to use SAML authentication if you're using Splunk Enterprise. To use SAML authentication with MDM, first set up SAML authentication and then configure MDM. To configure MDM, see Set up MDM and In-app registration for iOS devices or Set up MDM and In-app registration for Android devices.

To use SAML with an MDM provider, you must be using SSL protocol on Splunk Web and use a trusted certificate

If you're already using MDM and would like to use SAML authentication, complete the following steps:

1. Set up SAML authentication.
2. In the Configure tab of Splunk Cloud Gateway, click Get Existing Instance ID File. Do this for all your instances that you're using with the Connected Experiences apps. You don't need to generate a new instance ID file.
3. Upload the file to your MDM provider.

For user registration steps, see Register a device if your organization uses both SAML authentication and an MDM provider in the Install and Administer Splunk Cloud Gateway manual.