Configuring Okta SAML Single Sign On with Splunk Cloud - Using the Okta Splunk Cloud App

This blog post is an update to Philip Greer’s blog for the 6.4.x “Configuring Okta Security Assertion Markup Language (SAML) Single Sign On (SSO) with Splunk Cloud."

This post steps you through the Okta integration with Splunk Cloud by using the Okta Splunk Cloud App, which was not available for 6.4.x. Some of this post may repeat the prior blog's content, but by using the Okta Splunk Cloud pre-canned App, the number of steps to configure have been greatly reduced. There have also been updates to the Splunk Cloud configuration, which are part of this blog.

So, let’s get to it—below is a quick how-to on setting up Okta to provide SAML SSO with your Splunk Cloud 6.6.x instance using the Okta Splunk Cloud App.

Who do you need? 

1. An administrator for your Okta instance
2. An administrator for your local Identity Management system (Active Directory, LDAP, etc)
3. An administrator for your Splunk Cloud instance. If they’re all the same person (you), you’re in luck. Otherwise you’ll have to find time for all of you to discuss the SAML integration, put in change control, schedule a time to implement, etc.
    

Splunk Metadata:

1.    First have your Splunk Cloud administrator log into your instance as a user with the ‘admin' role. If you have multiple search heads in your Splunk Cloud environment (aka a general search head at https://<acme>.splunkcloud.com and/or possibly an Enterprise Security search head at https://<es-acme>.splunkcloud.com) you will need to perform a separate Okta integration for each search head independently. In short, you’ll have multiple Okta apps, one for each search head (or search head cluster).

2.    Obtain your search head’s metadata.

a)    Log into your Splunk Cloud instance as a user with the admin role

b)    Go to the Settings -> Access Controls menu option.

c)    Click on the ‘Authentication method' link. Click on the ‘SAML' radio button

d)    Click on the ‘Configure Splunk to use SAML' link below the SAML radio button

Click Download File. This will download the Splunk Metadata file, which will be added to Okta when configuring the Okta Splunk Cloud App.

As an alternative to obtaining the search head’s metadata via the Splunk UI download, you can also do the following:

a)    Login to your Splunk Cloud instance with a user that has the “admin” role.

b)    Enter the URL https://<acme>.splunkcloud.com/saml/spmetadata into your browser’s URL field. This will present the metadata in the browser or automatically download the metadata file depending upon the browser being used.

3.    After using one of the above methods to obtain the Splunk Metadata, something similar will be presented in your browser window or the downloaded metadata file (the screenshot below is formatted but the contents should be similar)

From the metadata, capture the search head’s certificate (masked out above) between the XML tags ‘<ds:X509Certificate>' and ‘</ds:X509Certificate>'.

Save the certificate into a non-formatted text file (e.g. Notepad) and place a row above the certificate with the text (5 dash characters on each side of text). Example: Save As SplunkCert.txt.

“-----BEGIN CERTIFICATE-----“

 and a row below the certificate with the text

“-----END CERTIFICATE-----“.

It should look something similar to:

Okta Integration:

We are now ready for the Okta side of the integration.

1.    Have your Okta admin log into your Okta instance as the Admin user.

2.    Enter into the Admin functionality within Okta

3.    Click on the link to ‘Add Applications'

4.    Click in the search box to 'Search for an application'

5.    Search for the text 'splunk'

Select the 'Splunk Cloud' App

Click 'Add'

6.    The Okta Splunk Cloud App settings page will be displayed

NOTE: As noted earlier, this post is for Okta integration using the Okta Splunk Cloud App; there is also an Okta Splunk Enterprise App. Although some customers have been successful in using this app to integrate Okta with their Splunk Cloud instance, there’s been more confusion and mis-steps in the configuration when using this app.

The previous Okta blog for integrating with Splunk Cloud started from scratch with a new Okta app. At the time, that was the most consistent method to reach a working integration with Okta and Splunk Cloud. Configuring the integration using a new Okta app should still work, but more steps are required. Please refer to the prior blog for steps to configure the integration if wanting to integrate by creating a new Okta app.

7.    'Application label' – This is the application name of the Okta Splunk Cloud app.  If you would like to change from the default name of Splunk Cloud, you can make the change here. Make the label something that helps identify which search head functionality your will users will be logging in to (for multiple search heads).

NOTE: If there are multiple search heads you would want to change the Application Label to something like 'Splunk Cloud – Core' for the Splunk core search head and 'Splunk Cloud – ES' for the Enterprise Security search head.

'Site URL' - This is the landing page on which users are taken to in case of IdP initiated flow. This would be the base URL for your Splunk Cloud instance: 'https://<acme>.splunkcloud.com' where <acme> is the canonical DNS name of the instance and/or search head (in the case of multiple search heads or clustered search heads—such as a general ad-hoc search head at ‘https://acme.splunkcloud.com’ and a separate search head for Enterprise Security at ‘https://es-acme.splunkcloud.com').

'Entity ID' – Enter a unique name for the 'Entity ID'.  A suggested Entity ID name to uniquely identify the Splunk Cloud search head is ‘splunk-' followed by the first field of the canonical name ‘https://acme.splunkcloud.com'.  In this case, that would make the Entity ID ‘splunk-Acme' for this example.

NOTE: This field is case sensitive so the case must match when used elsewhere. For example, when it is used in the Splunk SAML configuration, the case must match.

'Application Visibility' – you can modify these settings per the requirements of your organization.

'Done' – click Done when completed with the General Settings.

8.    The next step in Okta is to 'Assign' the Okta Splunk Cloud App to people/groups you wish to test with to confirm SSO is working with your Splunk Cloud instance. After it's confirmed working, you can continue to Assign the People/Groups needed for access to your Splunk Cloud instance.

The screenshots below are an example of Assigning People for testing.

Assign People – Click the Assign drop down and select "Assign to People"

Search for the Person

Click Assign

Click Save and Go Back to complete the Assignment

Click Done

9.    Configure the Sign On settings

Click the 'Sign On' Tab selection

Click 'Edit'

10.    Next, we will assign the 'role'. The ‘role‘ is a list of groups that the user is assigned to within Okta and/or your Identity Management system (Active Directory, LDAP, etc.)

'Role' - Click the 'role' drop-down and select 'Regex'

In the 'Regex' field type in '.*'

The '.*' regex will default to all Roles defined for the People to be sent over as part of the SAML response to attempt to map the Okta Role to the Splunk Role.

You can also be more selective of the groups that are passed across in the SAML response 'role' attribute (going from Okta into Splunk). The regular expression can be more restrictive to only pass over a subset of the groups the user is assigned to.

For example, you could enter the regular expression ‘splunk_.*' into the filter field of the 'role' attribute and only those groups that match the string starting with ‘splunk_' will be passed through.

NOTE: The 'role' field is very important. This is how we will map group or groups the user is set to within your AD/LDAP environment to the Splunk>Cloud role (or roles) they should acquire once authenticated into your Splunk Cloud instance.

Recommendation:  Splunk roles are mapped to the groups a user is part of in your AD/LDAP environment. Typically, users are already assigned to a set of groups based on their role within the organization. However, we recommend setting up a new set of groups that are specific to and solely for the users that will need access to the Splunk Cloud instance search head(s), which can make this easier to manage.

For example, you can create a group 'splunk_admins' and 'splunk_users' (as examples) in your AD/LDAP environment. You can then assign your users that need the ‘admin' role in Splunk, or just ‘user' role in Splunk to those two groups. Setting up the group to Splunk roles mapping is covered a little later in these instructions.

Examples:

• splunk-acme-admins - For those users that need access to the Splunk instance and should have the admin Splunk role
• splunk-acme-user - For those users that just need the user role
• splunk-acme-mycustomrole - For those users that should map to a custom role in Splunk that you’ve created
• splunk-es-acme-admins - For those users that need to log into the https://es-acme.splunkcloud.com search head and need the admin role
  
  

Thus, there may need to be some change control set up to create these groups and assign the specific users to those groups before you integrate Okta with your Splunk Cloud instance.

Click 'Enable Single Logout' checkbox (the Signature Certification field will also display)

Signature Certificate – Select the 'SplunkCert.txt' you created from the Splunk Cloud instance Metadata Step #3 above.

Click Upload once the file is selected. After successful upload, you should see some of certificate data in the Text Box.

NOTE: If the file does not upload, please make sure you are only uploading the Certificate portion of the Metadata and not the entire Metadata.xml file.

11.    Select the 'Application username format' in the Credential Details section. 

'Okta username' is the default

This is the value that is passed as part of the SAML response as the 'nameID' attribute. The contents of this attribute will be used as the Splunk account name once the user is authenticated into Splunk.

NOTE: If you have existing locally defined accounts in your Splunk Cloud instance, it would be good to have the users that authenticate through SAML to come across into Splunk with the same account name.

For instance, if your locally defined user for ‘Joe Schmoe’ has a Splunk account by the name of ‘jschmoe’, it would be good to have the SAML authenticated user to come across with the ‘nameID' as the same string ‘jschmoe’. If, however, Joe Schmoe logs into Okta as ‘jschmoe@acme.com’ then the ‘nameID' within the ‘Okta username’ will come across into Splunk as the string ‘jschmoe@acme.com’ and thus be seen by Splunk as a net new account.

What does this mean? It means that if Joe Schmoe has a bunch of knowledge objects saved under his old account named ‘jschmoe’, when he logs in via SAML he will no longer have access to those knowledge objects. They are owned by a completely different user under the account ‘jschmoe’ instead of his new account named ‘jschmoe@acme.com’ that was instantiated through the SAML authentication. Not good…

Luckily, there are other options in the pulldown for the ‘Application username format' as shown below.

But what if those pulldown choices do NOT match what your user logs into? Now what? The Custom option will allow you to use the expression language to create a string specific to what you need to have users come across via SAML just as they were named when they were locally defined accounts. If this is a net new instance and you’re just getting up and running with Splunk, the topic is moot; but if you’ve had users for a long time and they have a lot of stuff they don’t want to lose, this piece is important.

Click Save to save the settings.

12.    On this same page, Click on the “Identity Provider metadata” link on the same page.

This will download the Okta Identity Provider Metadata. This downloaded file will be used to upload into Splunk or copy/paste the contents into Splunk.

NOTE: Make sure this page has been Saved before downloading the “Identity Provider metadata”. If you download before saving, some of the metadata may not be available when importing into Splunk.

NOTE: You can also click on View Setup Instructions to view the instructions that are part of this App.

NOTE: By using the Okta Splunk Cloud App, in addition to the “role” attribute set above, there are two other attributes that are automatically set that will be passed to Splunk Cloud from Okta as part of the SAML assertion. These attributes are named ‘mail', and ‘realName'.  These are automatically set to the following values:

The ‘mail' attribute is the string that will be populated into your Splunk user’s ‘e-mail’ field for their account.

The ‘realName' attribute is the string that will be populated as the ‘Full Name’ of the user in the Splunk account; this name is used throughout the Splunk UI. For example, it shows as the user’s name in the upper menu bar of the UI where the user can click to enter the menu to change their ‘User Settings' or ‘Logout' of their Splunk session.

NOTE: If the default values of 'mail' or 'realName' need to be changed from what the Okta Splunk Cloud App assigns, I would recommend using the previous blog mentioned at the top of this post, which will give instructions of creating a “New App”.  The “New App” will give you the option of additional selections via the drop-down for the 'mail' or 'realName' attributes.

Configure Splunk

If not already at the SAML configuration page, do the following: 

1.        Log into your Splunk Cloud instance as a user with the admin role

2.        Go to the Settings -> Access Controls menu option.

Click on the ‘Authentication method' link. Click on the ‘SAML' radio button

Click on the ‘Configure Splunk to use SAML' link below the SAML radio button.

3.    The SAML Configuration popup window will appear.

4.    Click on the ‘Select File' button next to the ‘Metadata XML File' entry row. Select the metadata XML file that you downloaded from Okta Splunk Cloud App earlier. Once selected click the ‘Apply’ button.

Several of the fields will populate from the XML data, such as:

Single Sign On (SSO) URL

Single Log Out (SLO) URL

Entity ID: Type in the ‘Entity ID' field to match the ‘Entity ID’ entered in Okta Integration Step #7 - ‘splunk-Acme' for instance. Again, remember that this is case sensitive so it should be typed in exactly as it during the Okta setup.

Sign AuthnRequest: Check

Verify SAML response: Check

5.    Scroll down to the Advanced Settings section

Fully qualified domain name or IP of the load balancer: Enter in the FQDN of your Splunk instance – aka https://<acme>.splunkcloud.com


Redirect port – load balancer port: Enter in a ‘0' (zero)

Save: Click Save to save the configuration.

6.    The next step is to set up the Okta/AD Groups to Splunk Role mappings.

Click on the green ‘New Group’ button in the upper right-hand corner of the SAML Groups configuration screen in Splunk.

In the ‘Create new SAML Group’ configuration dialogue:

Group Name: Enter the Okta/AD group

Splunk Role: Choose one or more ‘Splunk Roles’ that you wish to map to users that are assigned to that group from the ‘Available Item(s)’ box. The items you choose will populate over into the ‘Selected Item(s)’ box.

Save: Click the green ‘Save’ button once finished.

Perform this step for all Okta/AD groups that you are going to be mapping after initial testing is completed successfully.

7.    Now that you have mappings and the SAML configuration completed, your Splunk Instance is now set to re-direct authentication to your Okta IDP.

Test your setup by entering a new browser session or open up an incognito session of your browser. Go to your https://acme.splunkcloud.com URL and it should re-direct you to authenticate via your Okta instance.

You can also login as the Okta user that is assigned the new Splunk Okta app and click on the widget to initiate a SAML login.

8.     You should authenticate into Splunk. Click on your test user’s account name in the top menu and choose the menu option for ‘Account Settings' and check the values that are populated in the ‘Full Name' and ‘Email address' fields.

Also, from a Splunk 'admin' account check that the user’s roles are mapped correctly via the ‘Settings' -> ‘Access Controls' -> ‘Users' list in Splunk.

NOTE: If stuff is not working, there is a URL that will get your directly to your login authorization page for your locally defined Splunk accounts. For your Splunk Cloud instance, use the URL of the form:

https://acme.splunkcloud.com/en-US/account/login?loginType=splunk

You will be presented with the ole tried and true local authentication page to login to a locally defined Splunk account.

Also, you can use the above URL specific to your instance if you need to log into any existing locally defined account.

NOTE: A suggestion is for you to create your own locally defined account that has the admin role assigned to it. That way you always have a way to log in locally with admin role if anything is wrong with SAML—a back door way to fix stuff if it ever becomes needed (without having to log a support case with Splunk in order to have it done for you).

Troubleshooting: It is highly recommended to have a SAML tracer plugin for your browser (Chrome, Firefox, etc. all have a SAML tracer). This will allow you to easily capture the data that is being passed between your IDP and Splunk to determine what values are being passed within the Assertion attributes, etc., making it much easier to troubleshoot anything that might not be working or is not optimal for your preference. This may also be requested by Splunk Cloud Support Engineers.

NOTE: Splunk highly recommends that after SAML integration has been performed, any former locally defined user accounts should be removed through the UI by a user with the admin role. This does NOT remove that user’s knowledge objects, all it does it remove the locally defined password. By doing this, a user account can only log in via a successful SAML authentication.

9.     Also test the logout process. Choose the username in the upper menu bar of Splunk and choose the menu option ‘Logout'. You should be successfully logged out of the Splunk instance.

10.     If all is well, close the support ticket you opened in the pre-requisite steps.

----------------------------------------------------
Thanks!
John McCurdy