Recently there was a blog posting that described how to configure a Splunk Cloud (version 6.4.x) instance with Okta SAML 2.0. A bit of background on SAML was provided on why Single Sign On seems to be such the rage these days.
My role at Splunk>, as an Engineer on the Cloud Adoption team as part of our Customer Success organization, means that I exist here to help make our customers happy. Not having to type in a username and password to log into Splunk> to bring up your boss’s ‘TPS Reports’ dashboard is just one small way to bring happiness. A team in your company must have come together and convinced management to purchase the proper features and functionality of an Identity Provider (IdP) – In this case Azure! Smiles ensued. Another way to ride the highway to bliss is for your organization’s over-worked IT Infrastructure staff to not have to own the hardware, floor space and admin head count to support that awesome instance of Splunk> that you’re getting huge piles of value out of. A smart team at your company bought Splunk> Cloud and the party keeps on rolling!
So let’s get right down to it – below is a quick how-to on setting up Azure to provide SAML SSO with your Splunk> Cloud 6.4.x instance.
Who do you need?
1) An administrator for your Azure instance
2) An administrator for your local Identity Management system (Active Directory most likely, if you’re investing into an Azure instance you most likely leverage Microsoft software infrastructure on premise)
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 run the calendar dice and find time for you all to discuss SAML integration, put in change control, scheduled a time to implement, etc.
Initially, configuration of Azure was a bit more ‘manual’. With the awesome work of other Splunkers – Rahul Dimri et. al. – there is a pre-canned app in the Microsoft Azure Gallery/Marketplace. This app reduces the number of steps required for an SSO integration.
Login to https://manage.windowsazure.com
Navigate to your directory by selecting the Azure Active Directory on the left hand pane. If you want a separate directory then create one, or else select the directory in which you want users to access splunk.
In the “Add an application for my organization to use” dialogue, click on the search box on the top right hand side and type the word “splunk“, then search for the application by clicking on the search icon ( magnifying glass)
There is a lot of text on the right hand column of the dialogue. Place your mouse cursor within that column and press the tab key. Pressing the tab key will show a “DISPLAY NAME” text box on the bottom of the column. Enter a name for this application. In this example we will call it “SplunkSamlAppForAzure“. Click on the check mark in the bottom right to save your app.
On the second page, enter the:
Enter the “SIGN ON 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 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 (or cluster) for Enterprise Security at ‘https://es-acme.splunkcloud.com‘)
Enter the “IDENTIFIER“, this is essentially the ‘entity ID’ for the SAML configuration. In Azure you must use a URI – so use the URL of your Splunk> Cloud instance: ‘https://acme.splunkcloud.com
Enter the “REPLY URL”. This is the SAML target and is the URL: ‘https://<acme>.splunkcloud.com/saml/acs’ where again ‘<acme>’ is the DNS name of the instance.
Leave “Configure the certificate used for federated single sign-on (optional).” unchecked, you may want to explore this if you need to select a specific cert , or create a new cert to sign the assertions with. We will let it pick a default cert in this configuration.
Click on the right arrow to proceed to the next configuration page 3.
On page 3 of the configuration dialogue, click to “Download metadata” and save it to a file on your local system. This file will be needed when configuring the Splunk> Cloud instance for SAML in later steps
You can skip the “View <app> configuration instructions
Check the checkbox to confirm you have configured Splunk.
Click on the right arrow and complete the configuration dialogue.
- Once back at the app main page, click on the “ATTRIBUTES” tab at the top.
- Add a second user attribute
Enter the name “mail” for the “ATTRIBUTE NAME
Select the value “user.mail” from the “ATTRIBUTE VALUE” pulldown menu.
Click on the blue ‘cloud’ with a thunderbolt icon (on the left of “DASHBOARD” tab) to go back to the main app screen. Click on “Assign Accounts” and then add the users that you want to have access to the application.
Splunk> roles are mapped to the groups a user is part of in Azure Active directory. Typically users are already assigned to a set of Azure/AD 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). For example, you can create a group “splunk_admins” and “splunk_users” (as examples) in your Azure/AD. You can then assign your users that need ‘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.
When Azure passes information on the groups that a user is assigned to within the SAML Assertion, they are passed along by the group’s unique “Object ID” and not by the Azure/AD group’s name. So for the ability to map Azure/AD groups to Splunk> roles, we will need to collect information about the Groups that you are using. The object Id for each group you are using can be found by going to your Azure Directory Page and then navigating to the group whose Object Id is to be retrieved.
For example, the graphic below shows a group that is named “splunkUsers”. When this is passed along to Splunk> in the SAML Assertion (XML) it is passed along by the “OBJECT ID” of “10ad<blahblahblah>3d“. So for the group to Splunk> role mapping, we will need to record that Object ID for later use. I suggest a simple document or spreadsheet that contains the “DISPLAY NAME“, then use the ‘copy to clipboard’ button to the right of the “OBJECT ID” to copy/paste into the document/spreadsheet. Then add the Splunk> role or roles (you can map to more than one Splunk> role if desired) that you will be mapping to.
NOTE: At this time, the use of Object ID is the only way to map groups to Splunk> roles for Azure. There is an enhancement request to find another way that is more ‘user friendly’ to map roles. Hopefully future versions of Splunk> and/or Azure will provide a mechanism that is more intuitive for this mapping mechanism.
Configure Splunk> SAML:
- Log into your Splunk> Cloud instance as a user with the admin role
- Go to the Settings -> Access Controls menu option. Click on the ‘Authentication method‘ link. Click on the ‘SAML‘ radio button, then click on the ‘Configure Splunk to use SAML‘ green button.
- The first thing we will do is set up the AD/Azure Group to Splunk> Role mappings. Remember that list of group Object ID’s we had you record earlier when setting up Azure? Get that out, then 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, paste in the first Object ID into the ‘Group Name’ field. Then 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. Click the green ‘Save’ button once finished. Perform this step for all AD/Azure groups (Object IDs) that you are going to be mapping. I have not come across an Azure Object ID for a group that has had capital letters within it. That being said, Splunk> will lowercase all letters in the ‘Group Name’ field once the mapping is saved. Behind the scenes, when the SAML Assertion comes over from an IDP into Splunk>, all groups within the ‘role’ attribute will be set to all lower case before looking up mapping settings. The Azure Object ID is long enough and random enough that there should never be a conflict between group names (Object IDs) caused by the lower case action. So this note is more just to notify you of the behavior in case you see a difference in case between what you’ve entered and what was saved and listed in the SAML Groups screen.
- With the mappings in place, it is now time to set up the SAML configuration. Back on the ‘SAML Groups‘ configuration page, click on the green ‘SAML Configuration‘ button in the upper right hand corner of the page.
Click on the ‘Select File‘ button next to the ‘Metadata XML File‘ entry row.
Select the metadata XML file that you saved from Azure earlier. Once selected click the ‘Apply’ button.
Several of the fields will populate from the XML data, such as ‘Single Sign On (SSO) URL‘ and the ‘Single Log Out (SLO) URL‘.Type in the same URL that you used earlier as the ‘IDENTIFIER‘ on step 8 of the Azure App configuration earlier. It should be something like ‘https://<acme>.splunkcloud.comNOTE: The ‘Sign AuthnRequest’ and ‘Sign SAML response’ checkboxes need to be un-checked. With Azure, signing of the requests and responses is not performed, so please do make sure both check boxes are blank, not checked, or otherwise the SAML Assertion will not be accepted by Splunk/Azure.
- Scroll down within the configuration dialogue to the “Advance Settings” section.For Azure, the SAML Assertion sends over data within a few schema named attributes. Enter the following values in each attribute:
Attribute Alias Role” :
“Attribute Alias Real Name” :
“Attribute Alias Mail” :
NOTE: There have been multiple instances where the ‘*/emailaddress’ attribute is not being passed by Azure. If the accounts are Microsoft accounts, then they will have the http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress attribute. If the accounts are sourced from Microsoft Azure Active Directory (most often the case where Azure is connected to internal), then most likely the e-mail address will be coming across through the “Attribute Alias Mail” of http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name For the ‘Fully qualified domain name or IP of the load balancer‘ enter in the FQDN of your Splunk> instance – aka ‘https://<acme>.splunkcloud.com
Enter in a ‘0‘ (zero) into the ‘Redirect port – load balancer port‘Click the ‘Save‘ button to save the configuration.
- Now that you have mappings and the SAML configuration, your Splunk> Instance is now set to re-direct authentication to your Azure 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 Azure instance.
NOTE: If stuff is not working – there is a URL that will get your directly to your login auth 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 and you will be presented with the ole tried and true local authentication page to login to a locally defined Splunk> account.
Also 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 preferences.
- You should authenticate into Splunk. Click on your test user’s account name in the top menu and choose the menu option for ‘Edit account‘ and check the values that are populated in the ‘Full Name‘ and ‘Email address‘ fields.
- In 6.4.x of Splunk, there is a way we can set the account name to use the value within the e-mail address that comes across via the SAML Assertion. However, this requires a Splunk> Support or Cloud Operations technician to manually modify your instance’s authentication.conf file for you. Remember that pre-requisite step of creating a support ticket for Splunk>? Use this ticket to request Cloud Operations to add the nameIdFormat parameter to your search head’s configuration.The parameter that will be added to your configuration file is:
nameIdFormat=urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddressOnce this setting has been put into place for you, your users when they come across via Azure SAML will obtain Splunk> account names that are populated with the value of the email address.NOTE: This behavior will be enhanced in future versions of Splunk> Cloud. At this time, however, the only two options for the account name for users of Azure as an IDP is the unique Object ID or the nameIdFormat of ‘.*:emailAddress’. Thus if you wish to have the Splunk> account name relect any other value (SAM Account Name for instance) – that is not currently possible (as of my understanding) with the current versions and capabilities of Azure and Splunk> 6.4.x.