With every problem there is an opportunity to learn something new, and every Salesforce Admin I’ve ever met loves learning new things in Salesforce. We’re often the first ones to admit, “I was wrong – I didn’t know how to do that, but I’m going to use it now!” It doesn’t matter how long you’ve been using Salesforce – especially with frequent releases (and release notes the length of a short novel!), there’s always something new to learn.
With this love of learning in mind, I wrote this article in collaboration with Vincent Finet, a Salesforce Technical Architect who taught me something new about troubleshooting an error associated with Single Sign-On. Errors like this are particularly frustrating for users, because Single Sign-On is supposed to make life easier, not more difficult. This guide will give you a fast and easy way to troubleshoot the error, to ensure your users are logged in and working as efficiently as possible.
What Is the SAML Assertion Validator?
Once upon a time, there was this “Single Sign-On Error” screen… What happens next?
A new thing I recently learned is how to check the SAML Assertion Validator for Single Sign-On errors. If you’re a new admin, this might sound scary and technical, but it’s really not. If you have Single Sign-On for your org, and a user gets an error, checking the SAML Assertion Validator is one way to troubleshoot the problem.
As a consultant, I work in my clients’ Salesforce orgs. There’s a bunch of them, and they all have different methods of signing on; they all use different Single Sign-On apps, 2FA, etc. And as we all know, Salesforce requires a unique username. Usually, the Single Sign-On username needs to match the Salesforce username as well.
Well, eventually it happened – I got this error. I was still able to log in via a different method, but not via Single Sign-On.
After going through the stages of Salesforce Admin grief (denial, frustration, googling, SF Support Case), I posted in the #whyadminsdrink channel in the #OhanaSlack user group.
In addition to my fellow admins sharing in my frustration, I got a very useful piece of advice from a fellow architect, Vincent Finet, with a simple: “Did you check the SAML Assertion Validator?”
Of course, I had not. So Vincent explained what it is and how to use it.
The SAML Assertion Validator is an out-of-the-box feature from the Salesforce setup menu that helps to debug the last SAML operation on your organization.
It might not help a lot in production if you are concerned about one specific user, when you may have thousands of other users connecting at the same time. However, it will help you in identifying what might be wrong with your current SAML configuration in a sandbox or if you have very few connections.
Where Is the SAML Assertion Validator?
In the setup menu, of course! Log in to your organization as a System Administrator. In the setup menu, look for Single.
The “Single Sign-On Settings” page appears, and on top, a button called “SAML Assertion Validator”. What are you waiting for? Click it!
Now you are on the page, it doesn’t look so great, does it? Well, wait for it…
Let the Magic Begin!
Ask your user to perform the login process one more time. When the user sees the error message on screen, refresh your own screen.
Magic! You’ll see a full description of the validation process including the success (bravo!) and the failure (oh no!). At the end of the list, you’ll have the full error message, which may explain your issue.
Let’s take a look at an example:
Here we see two issues:
- Something seems to be wrong with the timestamps (step 4).
- The subject does not match a Salesforce user (message at the bottom of the second image).
Timestamps Issue
Did you notice that there is a mismatch about timestamps in step 4? What does this mean?
Well, when Salesforce receives the data from the identity provider (aka. the SAML envelope), it contains a timestamp: a date and a time. This timestamp represents the current time when the envelope was created by the identity provider server. This server uses a specific time setting. Note that the setting may not be identical to the one that Salesforce uses.
So, in other words, this happens when the identity provider server is not totally in sync in terms of time with Salesforce. For example, on one side, at the same exact instant of time, it’s 7.45am. And on the other side, it’s 7.48am.
The server creating the assertion is using its own time. When Salesforce receives this with its own time, the value seems way too far in the past (or even in the future). Therefore, the test is failing.
How do you resolve this? You can try checking the identity provider to have a better server time. Or you can try to set a validation period larger than “currently”.
Subject Mismatch Issue
The error message is quite clear in the previous page. The “subject” (identifying the user trying to connect to Salesforce, who was identified from the Identity Provider) is not found in the table “User” in Salesforce.
In which field (in the table) “User” is used to search for a user depends on your Single Sign-On setting – it could be the Email, the FederationId, or any other field.
How do you resolve this? Simply align the two sources of information so that the subject sent by the identity provider is identical in the field you choose on the User table. Additionally, please note that the matching is case-sensitive!
Final Thoughts
There you have – a simple way to troubleshoot your Single Sign-On error. Thanks to Vincent for his help – you can reach him via LinkedIn or Trailhead.
In my humble opinion, this is absolutely one of the best things about the Salesforce community. I got to meet someone new, and learn something incredibly useful.
No judgment on whether I should have known that piece of information already, as there’s no gatekeeping of knowledge. Vincent and I aren’t even in the same country – we just happened to be in the same Slack group. He saw my frustration, had a suggestion, and it worked! This is part of the reason I always encourage people to start Trailhead, particularly if you’re looking to transition to a technical career.
Have you come across any similar errors? Let us know in the comments.