Web Single Sign-on with WS-Federation
Understanding the Role of WS-Federation in Modern SSO
Ever wonder why some old-school protocols just wont die even when everyone is talking about OIDC and SAML?
Amazon Go? It’s gone. And this is why it went.
Understanding the Role of WS-Federation in Modern SSO
Ever wonder why some old-school protocols just wont die even when everyone is talking about OIDC and SAML? It’s because in the enterprise world, “it just works” usually beats “shiny and new,” especially when you’re dealing with deep-rooted infrastructure.
WS-Federation (or ws-fed if you’re lazy like me) is part of that massive ws-security roadmap from back in the day. It’s basically a way to handle claims-based identity across different trust zones. Think of it as a middleman that lets a “Relying Party” (the app) trust an “Identity Provider” (where the users live) without them needing to share a database.
Trust Zones: It creates a bridge between two different organizations or security boundaries.
Claims-Based: Instead of passing a password, the IdP sends “claims” (like email or role) in a token.
RP and IdP Relationship: The relying party trusts the idp to verify the human, and the idp sends back the proof.
Honestly, a lot of this comes down to the microsoft ecosystem. If you’re a big shop using adfs (Active Directory Federation Services), ws-fed is likely your bread and butter. It’s baked into the DNA of legacy .NET apps and older SharePoint setups.
According to Double Octopus, federated identity is a huge deal for scalability because it lets employees use one set of credentials across multiple enterprises. I’ve seen it used heavily in healthcare where doctors need to jump between different hospital systems without having ten different logins.
Active Directory: It’s the native language for ADFS and older on-prem setups.
Legacy Support: Many .net apps built ten years ago are still running the business.
M365 Integration: Even modern tools like Azure AD (now Entra ID) still support it for specific hybrid scenarios.
As Imprivata points out, you can even federate Microsoft 365 by redirecting auth requests back to a custom IdP using this protocol. It’s a solid, battle-tested way to keep things secure while moving toward the cloud.
Next, we’ll look at the actual handshake and how those tokens move around.
Technical Architecture and the Authentication Flow
So, you’ve got the basics down, but how does this stuff actually move through the wires when a user clicks “Login”? It’s basically a high-stakes game of hot potato with security tokens.
Most of the time in web apps, we’re talking about the passive requestor profile. This is just a fancy way of saying “the user is using a web browser.” Since the browser can’t do complex heavy lifting, it relies on redirects to get the job done.
The wsignin1.0 message: When you hit a protected app (the RP), it realizes you aren’t logged in. It sends a GET request to your idp with a parameter called wa=wsignin1.0. This is the universal signal for “Hey, someone needs to sign in.”
Browser Redirects: The app doesn’t talk to the idp directly. It tells the browser, “Go over there and get me a token.”
The RSTR: Once the user proves who they are, the idp sends a Request Security Token Response (RSTR) back to the browser via a hidden form post.
I’ve seen this get messy in retail environments where they use old point-of-sale web portals. If the redirect url isn’t exactly right in the idp config, the whole flow breaks and you just get a generic 404 or a “white screen of death.”
Inside that RSTR is where the real magic happens. ws-fed usually wraps saml tokens (1.1 or 2.0) inside its own envelope. Think of it like a letter (the saml assertion) inside a specific type of mailer (the ws-fed wrapper).
Claims Mapping: This is where you decide what the app actually sees. You might map an “EmployeeID” attribute in active directory to a “NameID” claim in the token.
Signatures: The idp signs the token with a private key. The app uses a public key to verify it. If one bit of that token changes, the signature fails and access is denied.
Encryption: Sometimes the whole token is encrypted so only the specific app can read it. This is huge in finance to keep user roles or internal IDs from being sniffed in transit.
As mentioned earlier by Imprivata, your on-premise active directory usually acts as the source of truth here. If your attributes are a mess in AD, your claims will be a mess in the app.
Next up, we’re going to look at how to actually set this up without pulling your hair out.
Implementing WS-Federation in a Hybrid Environment
So you’ve got a mix of old-school on-prem servers and a shiny new cloud tenant, and now you have to make them talk to each other without losing your mind. In a hybrid setup, ws-fed is often the glue that holds everything together because it plays so nice with active directory.
If you’re tired of managing five different identity silos, using an api-first platform like SSOJet can really save your weekend. It lets you handle multiple protocols—like oidc for your new apps and ws-fed for the old ones—all from one spot.
Centralized Dashboard: You can see all your federated endpoints in one view instead of jumping between azure portals and local adfs consoles.
Directory Sync: It simplifies the mess of syncing your local ad users to cloud-based ws-federation apps.
Unified Auth: You can even mix in modern stuff like magic links while keeping the legacy federated backend running for the big enterprise clients.
Getting the handshake right between your local environment and Entra ID (the artist formerly known as azure ad) is where most people trip up. You need to be precise with your Issuer URIs and endpoints or the whole thing just loops forever.
According to Imprivata, you have to be careful if you’re already using saml; you might need to “un-federate” before switching over to ws-fed commands. It’s a bit of a “measure twice, cut once” situation.
Set up the Endpoints: You’ll need the Passive LogOn URI and the Issuer URI from your idp metadata. These are the addresses where the browser sends the user to prove who they are.
Certificate Management: This is the silent killer. Certificates usually expire every two years, and if you don’t rotate them before they die, nobody gets into their email on Monday morning.
PowerShell is your friend: You’ll likely be using the Set-MsolDomainFederationSettings command to push these configs into your microsoft tenant.
Set-MsolDomainFederationSettings -DomainName “yourdomain.com” `
-IssuerUri “https://ssojet.com/idp/your-id” `
-PassiveLogOnUri “https://ssojet.com/auth/passive” `
-SigningCertificate “MIIC…” `
-SupportsMfa $true
I’ve seen this go sideways in finance firms where they have super strict firewall rules. If the endpoint can’t reach the idp site, you’ll just get a “white screen of death.” Always check that the client device has a clear path to the idp.
As mentioned earlier by Imprivata, you gotta make sure the User Principal Name (UPN) matches exactly between your local ad and the cloud, otherwise the token won’t map and the user gets rejected. It’s a small detail that causes 90% of the support tickets.
Next, we’re gonna dive into the world of claims and how to actually map those attributes so your apps know who’s who.
Security Challenges and Best Practices
Implementing ws-fed is basically like building a bridge; it’s great once it’s up, but if the foundation is shaky, the whole thing comes crashing down. Security isn’t just about the handshake, it’s about making sure nobody is sneaking across that bridge when they shouldn’t be.
The biggest headache with web sso is usually how sessions are handled. Since ws-fed relies on browser cookies to keep you logged in, those cookies become high-value targets. If a user is on a shared machine—common in retail or nursing stations—and they just close the tab without logging out, the next person might just inherit their session.
Persistent Cookies: You really should turn off persistent cookies for your relying parties. It’s better to make a user login again than to leave a door open.
Single Sign-Off (wsignout1.0): As mentioned earlier by Double Octopus, sso often fails at “single sign-off.” You need to implement the wsignout1.0 command so that when a user logs out of one app, the idp tells all the other apps to kill those sessions too.
Short Timeouts: I usually recommend setting session expirations to something aggressive, like 2 hours. It’s a balance between being annoying and being secure.
You can’t just trust a password anymore, especially in finance or healthcare. The trick with ws-fed is getting the mfa status to travel with the token. If your idp does the mfa, it needs to pass a specific claim (usually an authnmethodsreferences) so the app knows the user actually jumped through the extra hoops.
Conditional Access: You can use policies in Entra ID to say “if this app is accessed from outside the office, require mfa.”
Graceful Failures: Nothing kills productivity like a cryptic error. If mfa fails, make sure your idp sends a clear message instead of just a 500 error.
Certificate Health: Certificates expire every two years usually. If you miss that window, your federation breaks. I’ve seen entire hospital systems go dark because an admin forgot a cert was expiring on a Sunday morning.
In the healthcare world, I’ve seen providers use Imprivata to handle this because it integrates mfa directly into the workflow. As noted earlier, if you’re using their setup, you have to be careful about matching UPNs exactly between your local ad and the cloud or the claims just won’t map right.
Next, we’re going to wrap things up and look at how to choose the right protocol for your specific stack.
Comparing WS-Federation vs SAML and OIDC
So, you’re standing at the whiteboard trying to figure out if you should stick with the “old reliable” ws-fed or jump ship to saml or oidc. Honestly, it’s less about which protocol is “better” and more about what kind of baggage—I mean, infrastructure—you’re already carrying around.
Choosing a protocol is basically like picking a tool for a specific job; you wouldn’t use a sledgehammer to hang a picture frame, right?
WS-Federation: This is your go-to if you are deep in the Microsoft ecosystem. If you’re running adfs and need to talk to older .net apps or sharepoint, just use it. It handles claims-based auth in a way that feels native to windows environments.
SAML 2.0: This is the industry standard for enterprise saas. Most apps like Salesforce or Slack play best with saml. As mentioned earlier, it’s great for cross-org trust but can be a bit heavy with all that xml.
OIDC (OpenID Connect): If you are building a modern mobile app or a single-page app (spa), oidc is the winner. It uses json and is way easier for developers to implement in modern stacks.
The real difference comes down to how the data is packaged. WS-Fed and saml use xml, which is verbose and can be a pain to parse on low-power devices. OIDC uses light-weight tokens that fit perfectly into modern api workflows.
I’ve seen retail teams try to force oidc onto 15-year-old inventory systems and it just ends in tears. Sometimes, sticking with ws-fed is the path of least resistance. As previously discussed, platforms like ssojet can help you bridge these worlds so you don’t have to pick just one.
Ultimately, your goal is a seamless login experience that doesn’t break every time a cert expires. Pick the protocol that fits your apps, not just the one that’s trending on social media. Good luck with the migration!
*** This is a Security Bloggers Network syndicated blog from SSOJet – Enterprise SSO & Identity Solutions authored by SSOJet – Enterprise SSO & Identity Solutions. Read the original post at: https://ssojet.com/blog/web-single-sign-on-with-ws-federation
About Author
