If you’re a Microsoft shop and have tried to set up SSO for Lattice via ADFS, then you’ve probably ran into similar issues as I have. You’ll find that it’s supported, but there aren’t really instructions for it — just a link to a page from Microsoft about generic config steps (this is based off the current state of their support article on how to configure SSO).

While I’m sure their support would have been happy to help resolve the issue, I’m a bit curious and impatient when it comes to these kinds of things and like to figure them out myself. I also like to get it taken care of in the same sitting. So, I decided to see how far I could get. Cue a bit of config toying as well as some digging through a few SAML requests and event logs, then “voilá!” A working setup!

The process really wasn’t too bad, and I thought I might save some others the time and document it here. May this help put an end to your Google-ing.

Environment

Product/Website

• Lattice / lattice.com

SSO Environment

• ADFS 3.0 (i.e. Windows Server 2012 R2 which is SAML 2.0 compliant)

Assumptions

• You have the admin access to both Lattice and your ADFS Server
• Your ADFS server is already set up and functional

Setting Up the Trust

First things first: Create the Relying Part Trust in your local environment. While not difficult, the steps needed here aren’t explicitly defined in Lattice. If you’re new to ADFS, it may be confusing.

1. From your main ADFS server and open up the AD FS Management Console.
2. Go to the Relying Party Trusts folder and under Action select Add Relying Party Trust…
3. Data Source – You’ll be asked how you want to configure the Trust. While a metadata file is provided, I could not get this to work for me. But it does contain the info you’ll need. For now select Enter data about the relying party manually.
4. Display Name – Set the Display Name to whatever cosmetic identifier you’d like – I chose Lattice. Set any tech notes you’d like to keep about the config, then click Next >.
5. Profile – Select AD FS profile from the options as we’ll want SAML 2.0 integration. Do not click the alternate option of AD FS 1.0 and 1.1 profile. Click Next >.
6. Certificate – Skip the step for an option token encryption certificate. I do not believe Lattice supports this option as I could not find a token cert for them. Just click Next >.
7. URL – Check the box Enable support for the SAML 2.0 WebSSO Protocol as this is what we’ll be using to communicate with Lattice. For the Relying party SAML 2.0 SSO service URL, enter your Assertion Consumer Service (ACS) URL as provided by Lattice: https://router.latticehq.com/sso/[subdomain]/acs. We’ll add onto this later.
8. Identifiers – The Relying party trust identifier should be set to your Lattice Entity ID: https://router.latticehq.com/sso/[subdomain]/metadata. Enter this value, click Add, then Next >.
9. MFA – If you use ADFS based MFA, configure it here in accordance with your standard policy, otherwise leave the default select option of I do not want to configure and click Next >.
10. Authorization – Configure your default user access policy. Due to the fact that Lattice does not automatically create accounts based on SAML authentication, I recommend Permit all users to access this relying party as only those with accounts will be allowed in. It’s easy to deny all and allow your primary user group through later.
11. For what’s available with prompt-based config, you’re now good to go! Click Next >, then click Close. I’d opt not to open the Claim Rule Editor.

Additional Trust Configuration

Now that the initial setup is done, there’s still a bit more we need to set ourselves that the setup helper didn’t do. This is the part that takes a tiny bit more digging or understanding of ADFS/SAML to configure. If you’re unfamiliar with the product and standard, you may get stuck. While the metadata file provided by Lattice didn’t work to import into ADFS, it still contains the info we need. Pop the link for it into your browser and you should see something along the lines of the following, except subdomain is replaced with your own domain.

From this, we can see that we need to add two missing things:

1. An ACS Redirect Endpoint, as the setup helper likely only added a POST
2. Our NameID claim, as be default no claims are sent with a new Relying Party Trust

First, to add and verify our ACS Endpoints:

1. Right-click on your new trust object, click Properties, then go to the Endpoints tab.
2. You should only see one endpoint in here so far, which is a POST binding. Click on it, then click Edit and set it as the Default option. Click OK to exit.
3. Now click Add SAML…, set the Endpoint type to SAML Assertion Consumer, the Binding to Redirect, the Index to 1, and the Trusted URL to what shows in your metadata file. This should be https://router.latticehq.com/sso/[subdomain]/acs. Once done, click OK, then OK again.
4. That’s it for ACS! Honestly the setup should work fine without configuring the Redirect; however, it’s a typical part of config and in the Lattice setup, so I would recommend adding it as a fail-safe regardless.

The last and more critical part of the setup is creating the proper claim rules, as Lattice doesn’t directly address this at all. What Lattice is expecting to see, however, is shown in the metadata file for your company. In the above screenshot, we can see that it’s expecting a NameID field to be submitted in the format of an email address. While setting this up is easy, the method of doing so is less intuitive than one might think.

1. First we’ll need to open our Claim Rule Editor. Do so by right-clicking on your Lattice trust object and clicking Edit Claim Rules...
2. Click Add Rule…, then select the template Send LDAP Attributes as Claims.
3. Name the claim rule whatever you’d like; I chose Send Email. Select your attribute store, that’s Active Directory in my case, then map the following claim and click OK.
   1. LDAP Attribute: Email-Addresses
   2. Outgoing Claim Type: Email-Address
4. Next, we’ll add a transform rule to submit the claim properly to Lattice. Click Add Rule…, then select the template Transform an Incoming Claim.
5. Name the claim rule as you see fit. I chose Transform Email to Name ID. Set the following options:
   1. Incoming claim type: E-Mail Address
   2. Outgoing claim type: Name ID
   3. Outgoing name ID format: Email
   4. Select the radio button for Pass through all claim values
6. Click OK, then make sure the rules are ordered with Send Email as the first item and the transform rule as the second item. Click OK to finish.

And now you should be good to go on your local config!

Lattice Configuration

Typically ADFS is pretty easy to configure on the third-party side, and Lattice is no different. All that should need to be done at this point is to import your own metadata file into Lattice. By default, your Federation metadata is available via the following URL [your.federation.domain]/FederationMetadata/2007-06/FederationMetadata.xml. Enter this URL into your browser. If prompted, download and open the file in a text editor, then copy all contents. Paste these into your Lattice SSO Config page, click Update Settings, and you’re finished! I’d also recommend checking the box to force all non-admin users to use SSO as Lattice does not expire passwords that I’m aware.

If your metadata file is not available at the above URL, be sure to check it’s published and available via the AD FS Management Console. Go to AD FS > Service > Endpoints and look under the Metadata category for the line with Federation Metadata set as the type. This item should tell if you if the endpoint URL is enabled on both your internal and proxy server, as well as what that URL is.

Troubleshooting Tips

In the event this guide does not work for you, there are a few things I’d recommend looking at to dig figure out a resolution:

1. Check your Lattice metadata file for any specific config options. This should be https://router.latticehq.com/sso/[subdomain]/metadata
2. Check the event logs on your ADFS server. While sometimes the entries contain an overload of information, you typically can get the key pieces you need to understand the failure such as NameIDPolicy was not satisfied, or other parts of your config that may not be mapping right.
3. Leverage a tool to decrypt & decode SAML requests from your machine. While things like Fiddler are great for decrypted web traffic analysis, SAML requests are encoded and will often leave you searching for some Base64 decoder online. The quickest and easiest method I’ve found to work with these issues is to use something like Firefox’s plugin SAML tracer which will flag and report decoded SAML traffic.