How to support any SAML or OIDC identity provider with only one integration

Most teams start with a single SSO integration and think the job’s done. But every new enterprise customer brings their own identity provider, and their own quirks. Azure AD, Okta, Ping, ADFS… even “generic SAML” isn’t as generic as it sounds.

In this post, we’ll break down why supporting multiple IdPs is far trickier than the specs suggest, where the real engineering pain comes from, and how WorkOS turns that into a single integration that works with any SAML or OIDC provider.

‍The checkbox that’s not a checkbox

‍"We already support SAML."

‍It’s the answer you hear most often when a startup starts thinking about selling into the enterprise. And at first glance, it makes sense. You add a SAML-based login flow, get it working in staging, check the box labeled "SSO support," and move on.

But then the first enterprise deal lands. Their IT team asks for specific support for Okta. The next one uses Azure AD. The third uses Ping. Suddenly, the checkbox turns into a checklist, and that checklist keeps growing.

You start to realize that "supporting SAML" and "supporting identity providers" are very different things. The spec may be the same, but implementations are not.

Those early integrations usually bake in assumptions:

• A fixed NameID format.
• A specific certificate rollover strategy.
• Expectation of POST bindings.
• One flavor of metadata exchange.

When the next IdP behaves differently, those assumptions break, and you’re back in the weeds.

It’s not until the second, third, or fourth integration that teams realise: the real challenge isn’t building one SSO connection, it’s building something that survives them all.

B2B SaaS apps might support dozens of IdPs (even far more than 10) over time.

The reality of IdP diversity

Supporting the spec (SAML or OIDC) is easy. Supporting real-world identity providers is where complexity explodes.

SAML is a standard, but in the wild, it’s more like a loosely followed suggestion. Every IdP implements it a little differently, and those differences quickly add up.

Let’s see some examples:

• NameID Format: Azure AD defaults to transient, while Okta often uses emailAddress. Some break if you send the wrong one.
• Signed assertions vs responses: Some IdPs expect signed assertions only, others require both the response and assertion signed. ADFS, for example, fails silently if you sign the wrong part.
• Assertion encryption: Some IdPs encrypt assertions using unexpected algorithms or key formats.
• Binding types: Okta may use HTTP POST for login but HTTP Redirect for logout. ADFS prefers Redirect. Others mix them arbitrarily.
• Clock skew: Some IdPs have loose timestamp validation, others are extremely strict—leading to cryptic "assertion expired" errors.
• Required attributes: One IdP expects a firstName claim, another wants given_name. If your app assumes one, it fails for the other.

And that’s just SAML. OIDC providers introduce:

• Non-standard id_token structures.
• Unexpected nonce or state handling.
• Differences in discovery endpoint metadata.
• Variations in how refresh tokens are issued and scoped.

Real example: Azure AD vs Okta

• Azure AD will reject an assertion if your SP metadata doesn't exactly match the entity ID registered.
• Okta may be more forgiving, but will break if the ACS URL isn’t a perfect match.

Even the order of operations matters. Some IdPs initiate SP flow before metadata is fully propagated, causing flaky behavior that’s hard to trace.

By the time you've added a handful of conditionals, you're no longer maintaining a protocol implementation; you're maintaining a growing compatibility matrix.

The hidden support and maintenance cost

Getting your SAML integration working once is just the start. The real cost shows up later, in the form of brittle, ongoing upkeep which bleeds into support load, sales velocity, and customer success overhead.

Certificates & metadata

IdPs rotate certificates, change metadata, and sometimes break configs entirely. If your app doesn’t support automated metadata refresh or handle multiple certs, login flows will suddenly fail, often during critical business hours.

• IdPs rotate certs every 6-12 months. Some notify you. Others don’t.
• Many IdPs require manually uploaded SP metadata—and break silently if it’s stale.
• If your customer doesn’t handle it right, you’re the one debugging their XML.

Diagnosing errors

Debugging SAML is…not fun:

• Assertions are base64-encoded blobs in POST bodies.
• Errors are often invisible to users (or just show up as generic HTTP 500s).
• Most SAML errors are opaque. "Authentication failed" could mean anything.
• Tools for inspecting and testing SAML flows are limited and hard to use.
• Without structured logs and tools to inspect SAML requests/responses, it’s guesswork.
• Your support team becomes an identity team.

Even logging a failed login attempt can take hours to decipher.

There’s no standard CLI, no sandbox environments, and little support for local dev flows. Setting up a test IdP usually involves public URLs, manual metadata exchanges, and trial-and-error in clunky admin portals.

Even open-source libraries offer limited relief. They often skip critical validation steps unless configured just right.

SAML has all the complexity of a security protocol, and none of the modern tooling to help you work with it.

Long-tail edge cases

• ADFS silently fails if the SP entityID isn't wrapped in quotes in metadata.
• One IdP failed because the RelayState parameter exceeded 80 characters.
• Another dropped the POST body if the Content-Type header was slightly off.

Each new customer may introduce one of these edge cases. They don’t show up in unit tests. They show up in urgent Slack threads.

You don’t just build SAML, you inherit it. Along with its indefinite, unpredictable maintenance burden.

What clean abstraction looks like

Eventually, you hit a wall. Each new IdP forces you to splice in another special case, tweak another config path, and add yet another conditional that lives alongside the rest of the growing compatibility matrix.

Over time, your SSO code stops looking like an implementation of a protocol and starts looking like a collection of hotfixes for every possible environment.

At that point, maintaining branching logic per IdP becomes unsustainable, and the only scalable way forward is to step back and reframe the problem as an abstraction challenge.

A proper abstraction should:

• Unify login flows: Present a consistent authenticate() interface regardless of provider.
• Normalize attributes: Internally map each IdP's claims to a unified user object.
• Hide IdP-specific behavior: Handle binding type, cert parsing, and signing config without leaking that to the application layer.
• Handle metadata ingestion: Automatically generate and update SP metadata in IdP-compatible formats.
• Centralize error handling: Turn low-level SAML/OIDC errors into readable, actionable diagnostics.

This is the abstraction we eventually built at WorkOS. It wasn’t an optimization. It was a necessity.

Once your product is being evaluated by 5, 10, 20 enterprise customers, SSO becomes your login system. It has to work for every customer, no matter how their IdP interprets the spec.

How to add support for any IdP in a day with WorkOS

1. Install the SDK for your language or framework.
2. Configure the IdPs you want.
3. Configure redirect URIs and get your API key.
4. Add the auth endpoint in your app using the WorkOS SDK’s workos.userManagement.getAuthorizationUrl() method.
5. Handle the callback using workos.userManagement.authenticateWithCode() to exchange the code for a user profile.
6. Deploy and test with any IdP—no custom code per provider needed.

With that, your app can authenticate users from any SAML or OIDC IdP without additional engineering work.

!!For more details, follow our quickstart.!!

Final thoughts

Supporting SSO isn’t about checking the "SAML" box. It’s about building a system that adapts seamlessly to every customer’s identity stack. The one-integration approach means you can scale to any number of IdPs without re-architecting your auth layer.

Whether you roll your own abstraction or use WorkOS to get there faster, treating identity as a platform-level concern, not just a feature, is what separates the SSO checkbox from true enterprise readiness.

‍Sign up for WorkOS today.