Configuring Microsoft’s Active Directory Federation Services (ADFS) Security Assertion Markup Language (SAML) Single Sign On (SSO) with Splunk Cloud

samlThe title is definitely a mouth full…. It is easier to say “Configure ADFS SAML SSO with Splunk> Cloud“, that’s for sure, but we did get all of the definitions of acronyms down in one shot….

I’ve put together a couple of blog postings now on SAML configurations for Splunk> Cloud. One for Okta , one for Azure. ADFS is definitely a bit more involved than those other two Identity Providers (IdP), and can be a bit more tricky depending on your implementation, but with this following guide, you should be well on your way to integrating ADFS to your Splunk> Cloud instance!

I am a Cloud Services Advisory Engineer on the Customer Adoption and Success Team (CAST) within Splunk>. My focus is to assist our customers in their experience with our Cloud service for Splunk>. With our 6.4.x version of Splunk> Cloud, which this posting is about. The configuration for SAML definitely works quite well, but is not the most user friendly to configure. As well, which we will get into later, if you choose to sign your SAML Authorization Requests and Responses, and you have a certificate within your IdP that is signed by a 3rd party Certificate Authority (CA) such as Verisign, GeoTrust, GoDaddy, etc., then you will require the assistance of Splunk> Cloud Operations (Ops) in order to have your certificates put into place.

So let’s get started!

index

 

Who do you need?

  1. An administrator for your ADFS environment.
  2. An administrator for your local Identity Management system (Active Directory most likely)
  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.
  4. Splunk> Ops (if you have a 3rd party signed CA or need any customization (claim rules) in your environment – see pre-requisite step below)

Here’s what you do:

Pre-requisite:

This step is requested to be performed so that our Splunk> Cloud Support and Operations staff will know that you are integrating your instance with ADFS. It provides a mechanism to more effectively support you in your efforts to integrate with ADFS in case anything may go amiss, or you may have further questions around ADFS configuration that are not addressed in this posting.

  • Log into your Splunk> Customer Portal and create a Splunk> Customer support case.
    • A Priority of P3 or P4 is adequate.
    • Choose ‘Authentication & Security‘ for the Area
    • For the ‘Feature / Component / App‘ choose ‘SAML
    • In the ‘Subject‘ enter in something along the lines of ‘SAML Integration with ADFS
    • Add a summary in the ‘Description‘ that you are going to integrate your Splunk> Cloud instance with ADFS, and possibly a date/time you will be performing the integration if applicable.
    • It will be helpful if you indicate that you do have 3rd party CA signed certificates in your ADFS environment. This way, Splunk> Ops will know that they will need to assist you in placing the certificates onto the search head(s) that you will be integrating with ADFS.
  • Read all of the below Integration steps. There are some pieces that you may need to perform in your Identity Management environment before you integrate with ADFS. There are also possible affects to your current locally defined users in Splunk> Cloud. And there may be other topics that may require further discussions among your team members or questions with Splunk>.

ADFS Integration:

The following steps are specific to versions 6.4.x of Splunk> Cloud. ADFS is not supported under earlier versions of Splunk> Cloud.

  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 ADFS integration for each search head independently. In short, you’ll have multiple ADFS Relying Trusts, one for each search head (or search head cluster).
    Screen Shot 2016-09-01 at 9.36.26 AM
  2. Confirm that your instance is at version 6.4.0 or later by going to the top menu option ‘Support & Services‘ -> ‘About
    6.4.0.version
  3. Obtain your search head’s metadata.
    This can be obtained by, once logged into a session as an admin role user, entering the URL https://<acme>.splunkcloud.com/saml/spmetadata into your browser’s URL field.
    Something similar will be presented in your browser window:Screen Shot 2016-09-01 at 9.44.54 AM

    Save the metadata file into an XML file. You can either copy/paste the entire page into a text editor (such as Notepad) that does not format the text, or you can simply do a browser File->Save As action and save the page as an <filename>.xml file. It is very important that the file be straight text with no formatting or it will not upload into ADFS cleanly.

    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 (Notepad for example) and place a row above the certificate with the text ‘—–BEGIN CERTIFICATE—–‘ and a row below the certificate with the text ‘—–END CERTIFICATE—–‘. It should look something similar to:Screen Shot 2016-09-01 at 10.11.12 AM

  4. Within ADFS, go to the ADFS->Trust Relationships->Relying Party Trusts option and choose to “Add a Relying Party Trust….
    relying_trust

  5. Choose to import data from a file, choosing the XML metadata file that you created from the Splunk> Cloud Instance’s spmetadata URL:
    import_metadata

  6. After the import screen the next panel will open, enter in a Display Name that makes sense for you and per any naming conventions for the Relying Trust:
    relying_trust_name

  7. Choose the radio button “do not configure multi-factor authentication settings” and click Next
    do_not_configure

  8. Click through the next couple of panels in the Wizard, leaving the defaults as they are presented:
    click_through_2

    click_through_1

  9. Un-click the Edit Claim Rules dialog and click Close to exit the Trust Wizard
    close

  10. Go back into the Properties for the Relying Party Trust that you just saved as there are a couple of changes that need to be made:
    properties

  11. Click into the Identifiers tab. The default Relying party identifier for Splunk came in from the metadata file as ‘splunkEntityId’. Click to remove that default string and add a string that makes sense to you and adheres to your naming scheme. A typical string that is used is “splunk-” followed by the Splunk Cloud instance name, such as “splunk-acmecorp“:
    entity_id

  12. After you have entered a Relying party identifier choose the Encryption tab:
    encryption

  13. At this time, Splunk> Cloud 6.4.x does not support encryption. However, with Splunk> Cloud, everything is encrypted through https (SSL). Choose to remove the encryption certificate:
    remove_1

    remove_2

  14. Choose the Signature tab and make sure the Splunk Certificate was imported:
    certificate

  15. Click on the Advanced tab, the self signing certificate for Splunk Cloud instances are from a SHA-1 hash algorithm. Choose the Secure hash algorithm to be set as SHA-1.
    sha-1

    I know what you’re thinking… “SHA-1?! That’s so 2005!” – We know it, so the next release will support SHA-256. But for 6.4.x, it’s SHA-1 or nothing…

  16. Click on the Endpoints tab and make sure the Consumer Endpoints is the URL for the Splunk> Cloud Instance by the URL https://<name>.splunkcloud.com/saml/acs (note that the screen shot below includes a port, this is from an internal Splunk test instance, your Splunk Cloud URL will not contain a port number quantifier – if the metadata provided a port within the endpoint URL, please do take it out)
    As well, make sure the Logout Endpoints is also specific to your Splunk Cloud instance by the URL https://<name>.splunkcloud.com/saml/logout:

    Also, the metadata from the Splunk Cloud search heads will most likely have the search head’s hostname canonical name in the URL. In Splunk> Cloud we use ‘sh1.<customer>.splunkcloud.com’, ‘sh2.<customer>.splunkcloud.com‘, etc. for the search head OS DNS (A Record) name. Then we create a DNS Alias record (C-Name) for the search head such as ‘<customer>.splunkcloud.com‘ for a general search head, ‘es-<customer>.splunkcloud.com‘ for an ES search head, etc. The search head’s certificate, however, is tied to the C-Name record and not the A record. Thus, if your URL comes across in the metadata as ‘https://sh1.acme.splunkcloud.com:8080/saml/acs‘ – please do remove both the ‘sh1.’ and the port ‘:8080‘ from the URL. It should ONLY reflect the C-Name (Alias) DNS name of the search head, such as ‘https://acme.splunkcloud.com/saml/logout‘.

    endpoints

  17. Finish the properties modifications by clicking Apply then Ok:
    apply

    ok

  18. After finishing the Relying Party properties changes, choose the right panel option to Edit Claim Rules…:
    edit_claim_rules

  19. Choose to add a claim rule:
    add_rule

  20. Choose to Send LDAP Attributes as Claims and click Next:
    LDAP
  21. Enter in a name for the Claim rule name per your preferences and naming schemes. Choose the Attribute store to be Active Directory:
    rule_name
  22. For the first attribute, choose Display-Name and enter in the Outgoing Claim Type as the string “realName” without the quotes. The realName attribute will be the Splunk account’s Full Name and is displayed in many locations within the Splunk UI. This can be changed to your preference, however most commonly in ADFS it is the Display-Name.
    realname
  23. For the second attribute, choose E-Mail-Addresses and in the Outgoing Claim Type enter the string “mail“. This is the e-mail address that will be passed into Splunk and used as the Splunk account’s E-mail address.
    For the third attribute, choose Token-Groups – Unqualified Names and choose Role from the pulldown for the Outgoing Claim Type. This attribute will send over a list of groups the person is identified to. These groups will later be mapped into Splunk Roles to provide the appropriate permissions in Splunk that the users within the groups should acquire once authenticated.
    mail_roleHere is where we need to discuss something a bit further. The ‘Token-Groups – Unqualified Names‘ attribute is a list of all AD groups that a user is assigned to. These groups are then used in a mapping mechanism (see later section of this posting for Splunk> configuration) to map the AD Group to a Splunk> Role or multiple roles.Most entities choose to create several groups for each set of users that will be access each instance of Splunk> Cloud search heads. For instance, for the ‘Acme‘ company, we might have a set of users that need Admin role privileges in the general search head. So we can create an AD group named ‘splunk-admins‘ as an example, then another as ‘splunk-users‘. If we have an Enterprise Security search head (and thus a second ADFS Relying Trust) we could create additional groups named ‘splunk-es-admins‘ and ‘splunk-es-users‘. After these AD groups are created, we can then assign users to each group – those that need general search head admin role, those that just need user role, those that need access to the ES search head for various Splunk> roles, etc. Then in the Splunk> SAML group->role mapping (again shown later in this posting) we will set up the group name to map to the appropriate Splunk> roles.
  24. Click to Finish the claim rules. Then choose to add another new Claim Rule. For this new Claim Rule choose Transform an Incoming Claim and click Next
    finish
  25. Enter in a Claim Rule Name that adheres to your preferences and naming schemes. The Incoming claim type needs to be UPN:upn
  26. Choose Transient Identifier for the Outgoing name ID format: This Claim Rule will pass the value required for the NameID attribute. This attribute will be used by Splunk for the user’s account name in the Splunk Cloud instance. Click Finish then Apply and Ok to finish saving all claim rule work.
    transientNow here’s another interesting point in the overall configuration…. Some organizations have set up their AD environment where the main UPN for the NameID comes across with a value that does not match what they wish for it to be in their Splunk> Account name. For example, if you have been using Splunk> Cloud for quite a bit of time now with locally defined user accounts, you may have been using SAM account names for the name of the locally defined accounts. If the NameID attribute in the SAML Assertion contains something other than the SAM account name, then your users will come across into Splunk> as a net new user (as the NameID does not match the name of any existing accounts). Or, maybe the UPN comes across with the domain pre-fixed to the name you wish to use – such as ‘SPLUNK\MYNAME’. We cannot use a name with a ‘\’ character within it, and as well you’d like to see just ‘MYNAME’ and not ‘SPLUNK\MYNAME’. This is where things can get tricky, but there are ways around it. You will need to work with Splunk> Ops on ways to get a custom transformation claim rule written for your environment.For example, let’s say you are having the situation where the NameID is coming across as ‘SPLUNK\MYNAME’. Instead of creating a Transform Claim Rule as stated above, instead create a ‘Custom Claim Rule’. Within the ‘Custom Claim Rule’ you can specify a specific rule that will use the ‘regexreplace’ function to strip out the domain ‘SPLUNK\’ and replace it with just the remaining ‘MYNAME’ – but pass it along in the Assertion as the appropriate Transient claim type. An example customer claim rule is listed below.
    c:[Type == “http://schemas.microsoft.com/ws/2008/06/identity/claims/windowsaccountname”] => issue(Type = “http://schemas.xmlsoap.org/ws/2005/05/identity/claims/nameidentifier”, Issuer = c.Issuer, OriginalIssuer = c.OriginalIssuer, Value = regexreplace(c.Value,”(?<domain>[^\\]+)\\(?<user>.+)”,”${user}”), ValueType = c.ValueType, Properties[“http://schemas.xmlsoap.org/ws/2005/05/identity/claimproperties/format”] = “urn:oasis:names:tc:SAML:2.0:nameid-format:transient”);
    Of course, if you are a much more experience ADFS admin, you can go it alone, maybe leverage your GTS skillz (Google That Stuff) to create your own custom claim rule. But Splunk> Support/Ops/Engineering is at your disposal to help assist you with that effort if it is needed.NOTE: With Custom Claim Rules we have experienced issues with the Single Log Out (SLO) portion of the SAML integration with Splunk> Cloud. There are situations where the NameID that is transformed into Splunk>, as it now differs from the UPN, will not match the ‘session’ within ADFS for the user. So when Splunk> sends a Logout message back to ADFS, ADFS looks for a user that is logged in by the transformed NameID, can’t find it (as within ADFS it is identified by the original UPN value) and sends a message back to Splunk> basically saying “Dude, there’s no-one here logged in by that name!” and we end up with an error. Some customers have disabled SLO, others have worked with Splunk> and Microsoft to create custom claim rules to resolve the issue so that SSO and SLO all works the way they wish it to. Bottom line is that Splunk> is here to help you with the overall integration and will assist with custom claim rules and any SLO issues that you may run into.
  27. In this step you will need to enter into a PowerShell session. There will need to be a change to specific settings in ADFS due to the Splunk Self Signing Certificate.
    First use the Get-ADFSRelyingPartyTrust <trustname> command to list out the current settings:

    NOTE: I’ve run into a couple of instances where the ADFS cmdlets were not available in PowerShell on a customer’s system. Although I’ve not personally performed the installation of the role to obtain the ability to run the necessary ADFS commands, and most customers already knew what needed to be done (and to further exasperate the uncertainty here – I’m not an ADFS guru by any stretch of that meaning) there is a decent tech note on the subject here: https://technet.microsoft.com/en-us/library/dn479343(v=wps.630).aspx   where it states in order to use the ADFS commands, you need the ADFS Server Role installed:

    <snip>
    To use these cmdlets you must have previously installed the AD FS server role. This can be done using the Add Roles and Features Wizard in Server Manager or optionally, you can use the Install-WindowsFeature AD-Federation-Services cmdlet at a Windows PowerShell prompt to add the role.

    Once the role is added, you can list all the cmdlets that are available in the AD FS module by using the Get-Command * -module ADFS cmdlet.
    </snip>

    powershell1

  28. The setting we need to change is the SigningCertificateRevocationCheck setting. By default it is set to check certificates that are not self signing. We need to set it to None.
    powershell2
  29. Use the command Set-ADFSRelyingPartyTrust -TargetName <trustname> -SigningCertificateRevocationCheck None command to change the setting to None:
    powershell3
  30. Use the command Set-ADFSRelyingPartyTrust -TargetName <trustname> -SigningCertificateRevocationCheck None command to change the setting to None:
    trust1
  31. Choose to import the certificate that you saved from the Splunk Instance’s Metadata into a stand alone certificate file:NOTE: This has not been required for all customers. We have found that some customers have been required to import the Splunk> search head certificate into the AD server’s trusted chain, where as others have only needed the certificate within the Relying Trust in the ADFS configuration.

    What I suggest is to bypass this step in the initial setup attempt and only come back to it and import it into the AD server’s chain if required later. If you are unsuccessful in getting Auth requests and responses signed and there is an associated Eventlog message indicating that the certificate doesn’t exist to check the signature, then you may need to add the certificate to your key chain. Try it without doing the import first however, as this is especially helpful for those that have a large AD cluster as the certificate chain may not be replicated between nodes in the cluster – requiring an import onto each individual node in the cluster. In short, you may save some effort/time/work/management overhead if it ends up not being needed.

    trust2trust3
    trust4
    trust5
    trust6
    trust7
    Once you received the import was successful dialogue, you are finished with importing the certificate.

  32. Obtain the ADFS metadata from your Relying Trust to be imported into Splunk:
    Go to the ADFS->Endpoints option within ADFS:
    endpoints
  33. Locate the FederationMetadata URL in the Metadata section.
    locate
  34. This URL can then be accessed via a browser to download/save the XML metadata into a file:
    URLurl_file
    Save the XML metadata into a file on your desktop. It will be used to upload into Splunk> in the following steps.

Configure Splunk>

  1. On the Splunk instance as an Admin user, choose Settings->Access Controls->Authentication Method.  Choose SAML then click on the ‘Configure Splunk to use SAML’ button.
    within the SAML Groups setup page in Splunk, click on the SAML Configuration button in the upper right corner.
    SAML
  2. The SAML Configuration popup window will appear. Click on Select File to import the XML Metadata file (or copy and paste the contents into the Metadata Contents textbox) and click Apply.The following fields should be populated by the metadata:
    Single Sign On (SSO) URL
    Single Log Out (SLO) URL
    idP’s Certificate file
    Sign AuthnRequest (checked)
    Sign SAML response (checked)
    Enter in the Entity ID as ‘splunk-acmecorp‘ as was used in previous sections within step 11 of the ADFS configuration (above).saml_config
    NOTE: If you set signing of the Auth Requests and Responses, then ADFS also will need to be set to enable/disable signing. One way to just test if SAML is working without any certificates in the mix is to disable signing of Requests and Responses on both the ADFS side and the Splunk> side. Then once you have SAML working, the NameID and all attributes flowing as you expect, then later enable signing of the Requests and Responses. This is especially helpful when 3rd party signed certificates are in the mix. First get SAML working, then have Splunk> Ops put the certificate chain into place on the search head(s) and enable signing.
  3. Scroll down to the ‘Advanced Settings‘ section.
    Enter in the Fully Qualified Domain Name (FQDN) of the Splunk Cloud instance – ‘https://<customername>.splunkcloud.com
    Enter a ‘0‘ (zero) for the Redirect port – load balancer’s port.
    Set the Attribute Alias Role to ‘http://schemas.microsoft.com/ws/2008/06/identity/claims/role’
    It may also be necessary to set an Attribute Alias for ‘Real Name’ and ‘Mail’ – but not all implementations require these settings.Click Save to Save the configuration:
    advancedFor the ‘Attribute Alias Real Name’ and ‘Attribute Alias Mail’ there may need to be an associated schema string added such as the ‘Attribute Alias Role’ (which has always been needed). There is a decent Microsoft Tech Net posting here https://technet.microsoft.com/en-us/windows-server-docs/identity/ad-fs/technical-reference/the-role-of-claims that describes some of the URI’s for various schema names. You would need to perform a SAML trace in a SAML Tracer Plugin for your browser after setup of Splunk. Doing so will then allow you to see the full assertion XML text and within it, see which schema names are being passed with the values you wish to utilize for the ‘realName’ and ‘mail’ attributes that Splunk utilizes.
  4. The next step is set up the SAML groups. Within the Splunk ‘Settings->Access Controls->Authentication Method->SAML Settings‘ page, click the green “New Group” button
    new_group
  5. Enter in a group name that associates with ADFS Active Directory passed group names, some examples follow
    group1group2
  6. Test the ADFS SAML configuration. Log into the environment through a clean browser session or an incognito browser session.NOTE: If you need to bypass ADFS authentication re-direct and get to the local Splunk user/pass auth screen, use the customer’s URL: https://<customer>.splunkcloud.com/en-US/account/login?loginType=splunk
  7. Also test logging out of Splunk, you should be re-directed to the Splunk SAML logout page as shown below:
    logout

Very nice walkthrough. Could we use a similar process for setting up our Splunk Enterprise 6.4.3 instance with ADFS? I’m guessing there are some subtle differences. The documentation I’ve found so far is nowhere near as good as this.

Chris
September 26, 2016

Yes – setup for on-prem is very similar to setup for Splunk Cloud, but of course on-prem you have access to the CLI! :) If you have third party CA certificates, the steps to setup some OPENSSLDIR directories, links, etc. are quite specific for those certificates (root, intermediate and leaf) to be parsed for signing the Auth Requests and Responses. When you get to that point, create a Splunk support ticket and request direction there and we will provide the specifics that are required for that piece of the puzzle.

Philip Greer
September 26, 2016

Hey thanks for the response. I followed this guide and have made some progress, but when it tries authenticating me via SAML I get an error message:

IDP failed to authenticate request. Status Message=”” Status Code=”Responder”

Gotta love the blank status message errors! :) I’m Googling for different solutions now, but there’s not much out there, probably since this piece is new with 6.4.x. I’ll see if we have support with Splunk and maybe I can open up a ticket and get some help. Very new to ADFS.

Chris
September 26, 2016

Hi Chris

Funnily enough I set this up today and had the same error message. My issue was caused by the “Sign AuthnRequest” and “Sign SAML response” boxes being unchecked within the SAML config window on the Splunk side of thing. I’m sure I ticked them earlier but weren’t selected when I was troubleshooting my issue.
Not sure if this helps your situation.

Brady
September 27, 2016

I was able to get it going yesterday afternoon. I journeyed through a few different error messages but I was finally able to get the claims set up correctly and got all other settings correct. I had to set a NotBeforeSkew of 1 on the ADFS side to get past a NotBefore condition error. And did have to disable the 2 settings that you mentioned. Thanks again and take care, this post helped immensely.

Chris
September 27, 2016

Great find Chris! That’s a setting we’ve had a customer, or few, have to set when there is enough time diff between their ADFS environment and the Splunk> Cloud instance. It’s one of our back pocket things to resolve stored in our internal FAQ. Since you’ve run into it, I’ll post the PowerShell command that is needed to change that setting to allow for a little higher skew in the Assertion “NotBefore” condition. Here’s an example of the SAML xml stanza:

Just for reference. And here’s the PowerShell command to change the setting as you did:

PS H:\> GetAdfsRelyingPartyTrust -Name | Set-AdfsRelyingPartyTrust -NotBeforeSkew 1

And the Splunk error to indicate you may need to set the -NotBeforeSkew:

“The conditions saml response failed validation. Failed assertion validity – Did not meet NetBefore condition. Assertion is invalid Verify the time in the response from IDP is in UTC time format.”

Philip Greer
September 28, 2016

Interesting that having them checked did not persist. But – we have had caching issues with the UI, even where going into the SAML settings right after saving the initial config, making a change and trying to re-save posts an error stating that the SAML configuration has already been saved (and can’t be saved again). Those UI issues have been resolved in the next release (6.5.0) – none the less if you exit out of the SAML mapping page and go back through Settings->Access Controls->Authentication Method and click on the ‘reload’ button, then go back into the SAML mapping screen to enter into the SAML settings, this should resolve the issues. The ‘reload’ simply re-reads the authentication.conf file to make sure your in memory store of the configuration file matches what is stored out on disk.
NOTE: As you found, the signing of auth requests and/or responses have to be set both on the Splunk side as well as in the ADFS Relying Trust. If one side says to sign and the other does not, no worky…

Philip Greer
September 28, 2016