Configuring WS-Federation Single Sign-on for Resources
Why we still care about WS-Federation in a modern stack
Ever feel like you’re stuck in a time machine when a client asks to integrate an old sharepoint farm?
Configuring WS-Federation Single Sign-on for Resources
Why we still care about WS-Federation in a modern stack
Ever feel like you’re stuck in a time machine when a client asks to integrate an old sharepoint farm? You want to use oidc for everything, but suddenly you’re staring at an xml configuration that looks like it belongs in 2008.
Despite what the latest tech blogs say, ws-federation (ws-fed) isn’t dead—it’s just living in the basement of every major enterprise. If you’re dealing with “big corp” identity, you’re going to hit this protocol eventually. We see ws-fed constantly in industries like healthcare and finance where systems don’t get updated unless they’re literally on fire.
One core concept you gotta understand here is Passive Federation. Basically, this just refers to browser-based flows. Instead of a backend server making “active” web service calls to an identity provider, everything happens via the user’s browser using HTTP GET and POST redirects. It’s the old-school way of doing SSO before everyone moved to modern apis.
It’s often the only way to talk to:
According to research by Okta, while modern protocols are growing, a huge chunk of enterprise apps still rely on legacy integrations to keep the lights on. (Secure Access to Legacy Web Applications with Okta)
In this diagram, the user tries to access a resource at the RP, gets redirected to the IdP for credentials, and then is sent back with a signed token. It’s a classic redirect loop.
Honestly, it’s not about choosing the “coolest” tech; it’s about what actually connects. If you can’t bridge that gap, you’re leaving users locked out. Next, we’ll look at how the actual handshake works under the hood.
Core components of the WS-Fed handshake
If you’ve ever tried to explain ws-fed to a junior dev, you probably saw their eyes glaze over the second you mentioned xml namespaces. It feels clunky compared to oidc, but once you get the hang of the handshake, it’s actually pretty logical—in a “2005 enterprise” sort of way.
At its heart, ws-fed is just a conversation between two parties that have agreed to trust each other beforehand. You have the Identity Provider (IdP), which is the boss that knows who the user is, and the Relying Party (RP), which is the app just trying to let someone in.
Metadata Exchange: This is the “handshake” before the handshake. Both sides swap xml files containing public keys and endpoints so they recognize each other’s signatures.
The STS (Security Token Service): This is the engine inside the idp. It takes the user’s credentials and spits out a signed token that the app can actually understand.
The wtrealm Parameter: This is super important. It’s a string (usually a URL or URI) that tells the idp exactly which app is asking for a login. If this doesn’t match what’s configured on the server, the whole thing breaks with a generic error.
The diagram shows the metadata exchange happening out-of-band, followed by the runtime flow where the wtrealm parameter identifies the target application to the STS.
Once the idp says “yep, this is Bob,” it has to send Bob’s info over. This happens via Claims. Think of claims as digital sticky notes—one says “Email: [email protected]”, another says “Role: Manager”.
Attribute Mapping: You have to tell the idp which database fields go into which claims. In healthcare, this might be a specific provider ID; in retail, maybe it’s a store location code.
The UPN Headache: A lot of legacy apps flat out fail if they don’t see a User Principal Name (UPN). If your api expects http://schemas.xmlsoap.org/ws/2005/05/identity/claims/upn and you send email instead, the app will just act like it doesn’t know who you are.
According to technical documentation from Microsoft, ws-fed remains a core part of adfs and azure environments because it handles “passive” (browser-based) federation so reliably for apps that can’t handle modern tokens.
Understanding the WS-Fed XML Token
Before we get into the setup, we need to look at what’s actually inside the envelope. When the idp sends the user back to your app, it sends a <RequestSecurityTokenResponse>. This is the big wrapper that contains the actual proof of identity.
Inside that wrapper, you’ll find the <Assertion> tag. This is the meat of the sandwich. It contains the Issuer (who sent it), the Subject (who the user is), and the AttributeStatement (the claims like email or roles).
One thing that trips people up is that ws-federation is just the protocol used to transport the security token, which is usually formatted as a SAML 1.1 or 2.0 assertion. Think of ws-fed as the envelope and SAML as the letter inside. If you open the envelope and can’t read the letter because the signature is wrong, the whole thing is useless. You’ll see a <Signature> block at the bottom—if even one character in the xml is changed by a proxy or a bad middleware, the signature validation will fail and you’ll be stuck debugging for hours.
Step-by-step setup for your resources
Setting up a relying party trust (RP) always feels like a high-stakes game of “match the xml tags” where one wrong character ruins your whole afternoon. honestly, I’ve seen senior architects get humbled by a simple trailing slash in a federation metadata url.
Here is how you actually get this running in a real environment like adfs:
Obtain Metadata URL: Go to your IdP (like ADFS) and find the Federation Metadata path—usually something like /FederationMetadata/2007-06/FederationMetadata.xml. You’ll need this for your app to trust the IdP.
Configure Relying Party Trust: In the ADFS Management console, right-click “Relying Party Trusts” and add a new one. This is where you paste your app’s URL and set the identifier (the wtrealm).
Map Claims: You gotta define “Issuance Transform Rules.” This is where you tell the server to take the “E-Mail-Address” from Active Directory and map it to the long ws-fed schema URL for email.
Test Endpoint: Hit your app’s login URL. If it redirects to the IdP and back without a “400 Bad Request”, you’re golden.
In a healthcare setting, for example, missing a single claim like a staff id can block doctors from accessing patient records, so “testing in prod” isn’t an option.
If you’re tired of manually messing with xml files every time a new client wants to onboard, you should look into Identity Brokering or Protocol Translation. This is a strategy where you put a “bridge” in the middle that talks ws-fed to the old stuff and oidc to your new stuff.
This is where a tool like SSOJet comes in handy. It acts as that bridge so you don’t have to write custom xml parsers for every legacy app. You can use the ssojet api to manage your enterprise directory sync, and it abstracts away the messy handshake logic.
flowchart LR
App[Modern App] –>|OIDC| SJ[[SSOJet Bridge]]
SJ –>|WS-Fed| LegacyIDP[Old ADFS / LDAP]
LegacyIDP -.-> Metadata[XML Metadata]
Using an api-driven strategy means you can automate the onboarding of new enterprise customers. According to a 2023 report by Gartner, organizations that use identity orchestration tools reduce their integration costs by nearly 30% because they aren’t rebuilding the wheel for every legacy protocol.
Common pitfalls and how to fix them
Ever spent three hours debugging a login loop only to realize one server thinks it is 2:05 PM while the other swears it is 2:10 PM? Yeah, ws-fed is notoriously picky about timing and certificates, and it won’t hesitate to lock your users out without a clear explanation.
The most common “fire” I see in production is the dreaded expired signing certificate. When the thumbprint in your app doesn’t match the one the idp is using, everything stops.
Clock Skew: Servers aren’t always perfectly in sync. If your app server is even two minutes ahead of the idp, it might reject a token because it thinks the “valid from” time is in the future.
Token Validation: Most libraries let you set a ClockSkew buffer (usually 5 minutes) to handle this. It’s a lifesaver in distributed retail environments where ntp sync might be flaky.
SAML inside WS-Fed: As I mentioned before, ws-fed is just the carrier. If you’re seeing “invalid signature” but the certs look fine, check if the idp is using SHA-256 while your legacy app only understands SHA-1. This happens a lot with older .NET apps.
A 2023 report by Cloudflare emphasizes that expired certificates remain a leading cause of enterprise downtime, often because manual tracking fails in complex identity chains.
The diagram illustrates a signature failure: the IdP signs the assertion with its private key, but the RP fails to verify it because the public key in its config is outdated.
Honestly, the best way to avoid these headaches is to automate your metadata refreshes. If you’re still hardcoding cert strings in a web.config file, you’re just waiting for a 2 AM support call. Keep your configs dynamic, watch your logs for “NotBefore” errors, and you might actually get some sleep.
*** 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/configuring-ws-federation-single-sign-on-for-resources
About Author
