the Federation ID
Module 5 of 7 in the chapter Salesforce as the Service Provider: SAML, chapter 6 of Securing Salesforce: Identity and Access. Each module stands on its own.
The question this module answers: When the assertion says who Priya is, how does Salesforce find her user record?
The identity provider tells Salesforce who
Section titled “The identity provider tells Salesforce who”In chapter 4, module 6, you saw the part of the assertion that says who to log in as: the subject. The identity provider authenticated Priya, and now it’s telling Salesforce, “log her in as this person.” That value is the key to the whole login. Get it wrong and Salesforce either finds no one, or worse, the wrong one.
So here’s the question I ask every class. When that value arrives, what field does Salesforce check? Where on the user record does it look?
Three ways to name her
Section titled “Three ways to name her”Salesforce gives you three choices, in the single sign-on setting’s SAML Identity Type (S1):
| Choice in Salesforce | The identity provider sends | Salesforce looks in |
|---|---|---|
| Assertion contains User’s Salesforce username | Her Salesforce username | The Username field |
| Assertion contains the Federation ID from the User object | A value both sides agree on | The Federation ID field |
| Assertion contains the User ID from the User object | Her Salesforce user ID | The record’s ID |
The one I teach, and the one most companies use for their staff, is the Federation ID. It’s a field on every Salesforce user record, under the user’s advanced details, and it’s there for single sign-on. You put a value in it that the identity provider also has for the same person, and that’s how the two sides match. It’s an important concept, and in my experience it’s on the test.
Salesforce’s own Help describes the options a little differently: it links the Federation ID to “external Experience Cloud users, also known as customers and partners”, and the user ID to “internal users in your org, also known as employees” (S1). Both work for staff. What matters is that the identity provider sends a value Salesforce can find.
What makes a good Federation ID
Section titled “What makes a good Federation ID”You don’t have to use the Salesforce username. The Federation ID can be any value the identity provider holds for that person: an employee number, or some other number or code that identifies them.
So why not just send the username? Or the email address? Think about what changes over time.
- Usernames change, and they often don’t look like anything the identity provider has.
- Email addresses change. People change their names, companies rename their domains, and a merger can give everyone a new address overnight.
- An employee number doesn’t. It’s given once, it stays with that person, and the identity provider already has it.
That’s why I like a stable code. Priya’s employee number is E10442. It goes in the Federation ID field on her user record, the identity provider sends it as the NameID, and the two match. If she changes her name or her email tomorrow, her login doesn’t notice.
At Steve Trucking, the staff come from Microsoft Entra ID, so the question to settle with the Entra admin is which of Entra’s values goes into the assertion for each person, and the same value goes into each user’s Federation ID.
Where in the assertion
Section titled “Where in the assertion”The second choice is SAML Identity Location (S1): where in the assertion the identity provider puts the value.
- In the subject: “Identity is in the NameIdentifier element of the Subject statement.” This is the usual place, and it’s where module 4’s sample has it:
<saml2:NameID>E10442</saml2:NameID>. - In an attribute: “Identity is in an Attribute element.” Then you also tell Salesforce the attribute’s name, so it knows which one to read.
Ask the identity provider which one it does, and set the same here (S2).
Capital letters
Section titled “Capital letters”One more thing that has caught people out. Is psmith the same as PSmith? Some identity providers don’t keep capitals the same every time. So when you first turn on SAML, Salesforce turns on Make Federation ID case-insensitive, which also stops you creating two users whose Federation IDs differ only in capitals. Salesforce recommends you keep it on (S1). I agree.
When there’s no match
Section titled “When there’s no match”What if the value arrives and no user has it? Then Salesforce has no one to log in, and the login fails. In Login History, look for the subject failing: Subject Confirmation Error, from chapter 4, module 6. The fix is almost always on one side or the other: the value is missing from the user record, or the identity provider is sending a different value from the one you expected.
And what about someone who has no Salesforce user at all yet? By default, Salesforce matches; it doesn’t create. Creating the user on the way in, from the assertion, is just-in-time provisioning, and that’s chapter 12.
Test knowledge. In my experience, know the Federation ID: it’s the field on the user record that Salesforce matches against the value in the assertion, and the alternative is the Salesforce username.
Watch it on video
Section titled “Watch it on video”In 2023 I made a video of just-in-time provisioning between two orgs: the attribute set at the identity provider, seen in the SAML tracer, and the user updated at login. The note under the video says what’s still right and what’s changed since.
What’s next
Section titled “What’s next”Module 6: making sure Priya lands on the page she asked for.
What an architect decides here
Section titled “What an architect decides here”- Which identity type: username, Federation ID or user ID, and the reason.
- Which value is the Federation ID: a stable code the identity provider already holds, not a name or an email that can change.
- Who fills it in, for every user, and how (by hand, a data load, or provisioning in chapter 12).
- Keep Federation IDs case-insensitive.
Explore
Section titled “Explore”- Step 2: Create a SAML Single Sign-On Setting in Salesforce (opens in a new tab) (Salesforce Help, Winter ‘27; checked 2026-11-07)