Web Single Sign-On: Understanding WS-Federation
It’s 2026. If you listen to the keynote speakers at identity conferences, the world is a utopia of Passkeys, Verifiable Credentials, and OIDC running on everything from your watch to your refrigerator.
But then you go to work.
Web Single Sign-On: Understanding WS-Federation
It’s 2026. If you listen to the keynote speakers at identity conferences, the world is a utopia of Passkeys, Verifiable Credentials, and OIDC running on everything from your watch to your refrigerator.
But then you go to work.
Walk into the server room of any Fortune 500 company—metaphorically or physically—and the shiny future fades. You find the “long tail” of enterprise infrastructure. You find the systems that actually move the money. These massive, hulking beasts of software were written when flip phones were status symbols and “cloud” just meant rain.
Modern developers usually inherit these systems with a mix of confusion and dread. You’ve got SharePoint farms that haven’t been touched since 2019, legacy ASP.NET applications that refuse to die, and Dynamics CRM instances that hold the entire customer database. You hit a wall. You know OAuth2. You dream in JSON. But suddenly, you are staring at XML schemas, SOAP envelopes, and something called “Passive Requestor Profiles.”
Here is the hard truth: This is not dead technology. It is foundational technology.
If you break the WS-Federation trust, the CFO is locked out of their financial reports. The supply chain software stops talking to the warehouse. The business grinds to a halt.
Consider this guide your bridge. We aren’t going to pretend WS-Federation is the future of greenfield development. It isn’t. If you are building a new app today, use OIDC. But understanding how WS-Fed works is critical for the “Wrap and Adapt” strategy dominating the industry right now: keeping legacy apps alive while securing them with modern identity providers. Most of this traffic still flows through Microsoft ADFS, the primary vehicle for this protocol.
If you want to call yourself a complete identity architect, you can’t just know the new stuff. You have to know the old stuff, too.
What is WS-Federation? (Defining the Legacy)
WS-Federation (WS-Fed) is the grandfather in the room. It is part of the larger, somewhat infamous “WS-*” suite of SOAP-based specifications. At its core, it is an XML-based protocol used to transport authentication tokens between a Security Token Service (STS) and a web application.
To really get WS-Fed, you have to split your brain into two modes.
First, there is the Active Profile. This involves SOAP/WCF machine-to-machine calls. It is heavy, complex, and frankly, a headache we are going to ignore today.
Second, and most importantly, there is the Passive Requestor Profile.
When we talk about Web Single Sign-On (SSO) with WS-Fed, this is what we mean. “Passive” is just fancy spec-speak for “the browser does the work.” The client is passive; the browser is the mule. The protocol relies on standard HTTP redirects (302s) and form POSTs to move the user around, rather than complex SOAP envelopes sent by a backend client.
The WS-Federation 1.2 Specification defines the rigorous mechanics, but you don’t need to memorize the spec. You just need to understand that the browser is doing the heavy lifting of transporting the token from point A to point B.
The Vocabulary of WS-Federation (Jargon Buster)
If you are coming from a modern OIDC or SAML background, WS-Federation feels like visiting a foreign country. The concepts are identical, but the locals use different words. If you try to ask for a “Service Provider” here, you’ll get blank stares. You need a translation layer to survive.
Security Token Service (STS): This is the boss. In modern terms, this is your Identity Provider (IdP). It validates credentials and mints the token. In 90% of enterprise cases, your STS is Active Directory Federation Services (ADFS) or Entra ID (formerly Azure AD). If the STS is down, nobody logs in.
Relying Party (RP): This is the application. In SAML/OIDC, we call this the Service Provider (SP). It “relies” on the STS to tell it who the user is. It doesn’t check passwords; it checks signatures.
Realm: This is the unique identifier for the Relying Party. It isn’t just a name; it’s a strict key. Usually a URI like urn:sharepoint:portal. If the Realm in your config doesn’t match exactly (case-sensitive, character-for-character) what the STS expects, authentication fails immediately. No error message, just failure.
Endpoint Reference (EPR): Simply put, this is the URL where the token gets sent.
Claims: The cargo inside the container. These are the user attributes wrapped inside the token—User Principal Name (UPN), Email, Role, Group Membership.
How Does the WS-Federation Passive Flow Work?
This is the technical core. Forget REST APIs where you exchange keys in the background. WS-Fed relies on a “Redirect Dance” involving the user’s browser. It is a choreography that must happen in a specific order. If the music stops, the user is stranded.
Here is the play-by-play:
The Unauthenticated Request: The user types https://portal.company.com into their browser. They want in.
The Stop & Redirect: The Relying Party (RP) looks for a session cookie. It finds nothing. It halts the request immediately. It constructs a 302 Redirect to the STS URL. This isn’t a blind redirect; it carries vital query string parameters, specifically wa=wsignin1.0 (the action) and wtrealm (who is asking).
Authentication (The Challenge): The browser obeys the redirect and lands on the STS login page. The STS takes over. It challenges the user. This could be a simple password form, a smart card prompt, or Windows Integrated Auth (Kerberos) if they are on the corporate network.
Token Issuance: Once the STS is satisfied the user is who they say they are, it generates a signed XML token. Note: This is usually a SAML 1.1 or 2.0 assertion, but it is wrapped inside a WS-Fed response envelope.
The POST Back: The STS sends a 200 OK response to the browser. This page contains a hidden HTML form and a snippet of JavaScript. The JavaScript automatically submits (POSTs) the form back to the RP’s wreply URL. This form contains the wresult—the actual token.
Validation & Session: The RP receives the POST. It extracts the wresult. It validates the digital signature against the STS’s public certificate (which it already has trusted). It reads the claims (“Oh, this is Bob from Accounting”). Finally, it sets its own session cookie. The dance is over; the user is in.
sequenceDiagram
participant User
participant Browser
participant RP as Relying Party (App)
participant STS as STS (ADFS)
Note over User, RP: 1. Unauthenticated Request
User->>Browser: Access Application URL
Browser->>RP: GET / (No Session)
Note over RP, STS: 2. Redirect to STS
RP–>>Browser: 302 Redirect
Note right of Browser: Location: https://sts.example.com<br/>?wa=wsignin1.0&wtrealm=…
Note over Browser, STS: 3. Authentication
Browser->>STS: GET /adfs/ls/?wa=wsignin1.0…
STS->>User: Challenge (Password/MFA)
User–>>STS: Credentials
Note over STS, Browser: 4. Token Issuance
STS–>>Browser: 200 OK (HTML Form with Token)
Note right of Browser: Form contains hidden inputs:<br/>wa=wsignin1.0<br/>wresult=<RequestSecurityTokenResponse>…
Note over Browser, RP: 5. POST Back (Passive)
Browser->>RP: POST /signin (wresult)
Note over RP: 6. Validation
RP->>RP: Validate Signature & Claims
RP->>RP: Create Session Cookie
RP–>>Browser: 302 Redirect to Original URL or 200 OK
Browser->>User: Display App Content
WS-Federation vs. SAML vs. OIDC: What’s the Difference?
A common confusion—even among seniors—is treating WS-Fed and SAML as enemies. They aren’t. They are often partners.
Think of it like logistics. WS-Federation is the transport truck; SAML is the cargo. WS-Fed usually carries a SAML token inside its envelope.
The real difference lies in the mechanics of the truck. The SAML Protocol uses <SAMLRequest> messages that are Base64 encoded blobs. They are massive. WS-Federation, on the other hand, uses lightweight URL parameters (wa, wctx) to initiate the flow. It’s chatty, but the initial request is lighter.
Compared to OIDC, however, the gap is massive.
OIDC is JSON/REST-based. It’s built for mobile apps, Single Page Applications (SPAs), and APIs. It is sleek, modern, and developer-friendly.
WS-Fed is XML/SOAP-heavy. It is strictly browser-centric.
You cannot easily use WS-Fed for a native iOS app or a React SPA because of its reliance on XML parsing and specific redirect behaviors. It just wasn’t built for that world. For a deeper comparison of the two dominant modern protocols, read our guide on OIDC vs SAML.
The Developer’s View: URL Parameters and Config
If you open Chrome DevTools and watch the network tab during a WS-Fed login, you won’t see clean JSON objects. You will see a URL that looks like a query string explosion.
Understanding these parameters is the difference between fixing a bug in five minutes or five days. When a user screams “I can’t log in,” this URL is the first thing you check.
Here is the anatomy of a WS-Fed request:
https://sts.example.com/adfs/ls/?wa=wsignin1.0&wtrealm=urn:app:portal&wreply=https://portal.com/signin&wctx=RmFsc2U=
Let’s dissect the corpse:
wa=wsignin1.0: The Action. This tells the STS, “I want to sign in.” It is the command. If you see wsignout1.0, the user is trying to leave.
wtrealm=urn:app:portal: The Realm. This answers “Who is asking?” It must match the identifier configured in the STS exactly. If you have a typo here, you’re dead in the water.
wreply=https://portal.com/signin: The Reply URL. This answers “Where do I send the token?” Security teams watch this closely to prevent open redirect attacks.
wctx=…: Context. This is opaque data (similar to RelayState in SAML). The RP sends it, and the STS must return it unchanged. It’s the “backpack” you hand the bouncer. Often used to remember deep links—so if a user clicks a link to a specific quarterly report, they land on that report after login, not the generic homepage.
Why Does WS-Federation Still Matter in 2026?
If this technology is so old, why are we wasting pixels on it?
Because companies rarely rewrite working software. And they never rewrite infrastructure that works.
An enterprise is not going to rewrite a massive SharePoint 2019 farm or a custom .NET 4.5 ERP system just to support OIDC. The cost is astronomical, and the risk is too high.
The winning strategy for 2026 is Hybrid Identity.
You use a modern Customer Identity Access Management (CIAM) system (like SSOJet or Okta) to handle the user’s authentication. This gives you the cool stuff: MFA, Passwordless, Biometrics, and a slick UI via OIDC.
Then, that modern system translates the identity into a WS-Fed token and hands it off to the legacy backend. This “translation layer” allows you to modernize the experience without rewriting the application. You wrap the old code in new security. To see how legacy protocols fit into a broader strategy, check our Ultimate Guide to Enterprise SSO.
Common Pitfalls and Security Risks
Implementing WS-Fed isn’t just about getting the green light; it’s about avoiding the red sirens. Here is where the bodies are buried.
Infinite Loops (The Redirect of Death): The RP redirects to the STS. The STS thinks the user is authenticated and posts back. The RP fails to read the cookie or validate the token, so it treats the user as anonymous and redirects back to the STS. The browser bounces back and forth until it crashes. This is often caused by time synchronization issues (Clock Skew) or HTTP/HTTPS mismatches.
Certificate Expiry: This is the number one cause of outages in federated environments. The Token Signing Certificate on the STS (ADFS) rotates automatically every year. If the RP doesn’t have metadata monitoring to pick up the new key, it will reject all tokens signed by the new cert. Monday morning, nobody can log in.
“Golden SAML” & Token Theft: Since WS-Fed uses XML tokens, it is susceptible to XML Signature Wrapping attacks if the validator is weak. Furthermore, if an attacker steals the token signing key, they can forge a token for any user—a technique known as “Golden SAML.” Reference the OWASP Identity Management Guide for best practices on session management and token validation.
Conclusion
WS-Federation is a “heritage” protocol. It requires respect, not disdain. It powers the applications that pay the bills.
While no one should build a new application on WS-Fed in 2026, mastering it is a superpower for the modern DevOps engineer. It allows you to bridge the gap between the shiny new world of cloud identity and the iron-clad reliability of on-premise infrastructure. When the shiny new tools fail to connect to the old money-makers, you’ll be the one who knows how to fix the XML.
Since WS-Fed relies heavily on XML assertions, understanding the underlying token structure is vital. Read How SAML SSO Works to decode the payload inside the transport.
Frequently Asked Questions
Is WS-Federation the same as SAML?
No. While they both typically use XML tokens to convey identity, they are different transport protocols. SAML uses specific protocol messages (SAMLRequest/SAMLResponse) often Base64 encoded, while WS-Federation uses specific URL parameters (wa, wresult) defined in the WS-Trust stack to transport the token.
Why would I use WS-Federation instead of OIDC in 2026?
You generally wouldn’t choose it for new development. However, it is strictly required for integrating with legacy Microsoft ecosystem applications like on-premise SharePoint, older Dynamics CRM, or classic ASP.NET Web Forms applications that do not support OIDC.
What is the “Passive Requestor Profile”?
This refers to the specific workflow in WS-Federation designed for web browsers. It relies on HTTP redirects and standard GET/POST methods to move users between the application and the STS, as opposed to the “Active” profile which uses SOAP web services for machine-to-machine communication.
Can I use Multi-Factor Authentication (MFA) with WS-Federation?
Yes, but the MFA challenge occurs at the Identity Provider (STS) level. When the application redirects the user to the STS (like ADFS or Entra ID), the STS performs the MFA check before issuing the token. The application itself does not need to handle the MFA logic.
*** 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/understanding-ws-federation-web-single-sign-on
About Author
