Migrating homegrown SSO to WorkOS: what IAM teams need to know

At a glance

What this is: This is a migration guide for replacing homegrown SSO with WorkOS, and its core finding is that the hardest part is not the code swap but documenting fragile SAML and OAuth/OIDC dependencies before cutover.

Why it matters: It matters because IAM teams often inherit bespoke SSO paths with hidden certificates, attributes, and routing logic that can disrupt customer access if they are not governed like production identity infrastructure.

Context

Homegrown SSO often becomes a shadow identity platform. Once SAML assertions, OAuth/OIDC callbacks, tenant routing, certificate handling, and attribute mapping are embedded in application code, the control plane is no longer just authentication. It becomes a governance problem for IAM teams responsible for reliability, change control, and customer access continuity.

The article frames migration as a choice between per-connection reconfiguration and a proxy-based transition, depending on scale. That distinction matters because it changes who must touch the IdP, how much operational coordination is required, and how much of the legacy stack can be retired without breaking enterprise access.

Key questions

Q: How should teams migrate homegrown SSO without breaking enterprise logins?

A: Start by inventorying every SAML and OAuth/OIDC dependency, then migrate one connection at a time or use a proxy if the tenant count is large. Keep legacy and new routes in parallel until successful sessions prove the new path is stable. Decommission old handlers only after logs show no traffic to them.

Q: Why do homegrown SSO systems become risky to maintain over time?

A: They accumulate undocumented assumptions about certificates, redirect handling, tenant routing, and IdP configuration that only a few engineers understand. Once those assumptions are buried in application code, every change becomes a coordination exercise rather than a governed identity update.

Q: What breaks when SAML or OIDC connections are migrated without full inventory?

A: Teams lose track of which ACS URLs, NameID formats, scopes, claims, and signing settings are tied to each customer. That makes cutover brittle because the new flow cannot be validated against the exact behaviour the old flow depended on.

Q: What should IAM teams do when some customers cannot switch IdPs immediately?

A: Use a proxy or staged migration model so the existing callback keeps working while migrated connections are routed to the new system. For customers that still require local IdP changes, give them a self-serve setup flow and only decommission the old path after stable sessions are proven.

Technical breakdown

Why homegrown SSO becomes hard to unwind

A bespoke SSO stack usually accumulates connection-specific assumptions over time. In SAML, those assumptions include ACS URLs, SP Entity IDs, request signing, response encryption, NameID formats, and custom attributes. In OAuth/OIDC, the equivalents are client IDs, redirect URIs, scopes, and claims. The technical problem is not just protocol support but hidden coupling: once tenant identification, login routing, and IdP configuration are embedded in application logic, migration requires a precise inventory of every dependency before any callback is changed.

Practical implication: inventory every SAML and OAuth/OIDC dependency before changing a single redirect or ACS path.

Proxy-based migration as a cutover control

For larger connection sets, the proxy pattern preserves the existing callback URL while forwarding migrated SAML responses or OIDC callbacks to a new system. That works because the legacy endpoint remains the public interface while the routing decision is made internally based on whether a connection has already been imported. The real architecture question is whether the proxy can safely distinguish migrated from unmigrated connections without breaking RelayState handling, callback integrity, or tenant resolution during the transition.

Practical implication: treat the proxy as a temporary routing layer and validate that it preserves callback state correctly.

Why IdP changes are the real migration constraint

The article shows that many migrations stall not because the application cannot accept a new SSO provider, but because customers would have to reconfigure their IdP. SAML request signing keys, response encryption keys, and non-standard NameID formats are the main blockers. Where those settings cannot be transferred transparently, the migration path shifts from backend plumbing to customer-admin coordination through a self-serve setup flow. That is a protocol and governance constraint at the same time.

Practical implication: separate transparently migratable connections from those that require customer-side IdP reconfiguration.

Breaches seen in the wild

• Salesloft OAuth token breach: hackers stole OAuth tokens to access Salesforce data via Salesloft.
• Klue OAuth Supply Chain Breach: OAuth tokens compromised in Klue integration breach affecting 700+ organisations via Salesforce data access chain.

Read and download The State of NHI & AI Agent Breach Report 2026, covering 150+ breaches impacting Non-Human Identities including AI Agents.

NHI Mgmt Group analysis

Homegrown SSO creates governance debt long before it creates technical debt. The article describes a common pattern where a weekend integration becomes a critical path system that only a few engineers understand. That is not just operational fragility. It is an identity governance problem because ownership, documentation, and change control are no longer aligned with the access path. Practitioners should treat bespoke SSO as production identity infrastructure, not application glue.

Connection-level migration is really a control-plane migration. Moving enterprise SSO is not simply a protocol switch from SAML or OAuth/OIDC to another implementation. It changes how connection state, redirect handling, certificate renewal, and customer onboarding are governed. The practical implication is that IAM teams need a migration model that can distinguish transparent cutover from customer-managed reconfiguration, because one sequence does not fit every connection.

Custom SSO exposes the limits of application-owned identity. When login routing, tenant resolution, and attribute mapping live inside the product team’s codebase, identity decisions are divorced from IAM governance processes. That creates brittle dependency on a small number of maintainers and makes decommissioning slow. For practitioner teams, the lesson is that identity logic should be governed as a lifecycle asset, not left as embedded product behaviour.

Proxy cutover is a temporary control, not a permanent architecture. The proxy approach reduces customer disruption, but it also introduces a second path that must be monitored until the legacy handlers are retired. That dual-running period is where leakage, misrouting, and incomplete decommissioning tend to hide. The decision point for teams is not whether a proxy works, but how quickly they can remove the old endpoint once successful sessions are stable.

Connection migration should be sequenced by risk, not by convenience. The article implicitly separates low-risk, transparently migratable SSO connections from cases that require IdP-side reconfiguration. That distinction should drive rollout order, customer communication, and decommission criteria. IAM programmes that ignore this sequencing tend to inherit prolonged parallel operation and avoidable support burden.

From our research library:

• Across one million observed logins, 1 in 4 were password-based rather than SSO, 2 in 5 were not protected by MFA and 1 in 5 used a weak, breached or reused password.

What this signals

Governance, not just code, determines whether SSO migration succeeds. The article is a reminder that identity systems age into operational dependencies that need ownership, documentation, and retirement criteria. Teams that treat SSO as embedded product logic usually discover the governance gap only during cutover, when one misconfigured callback can affect many customers.

Connection-specific migration paths are now the practical norm for enterprise identity change. Some integrations can be flipped centrally, while others require customer-side reconfiguration because signing keys, encryption keys, or NameID formats cannot move cleanly. That means IAM programmes need a rollout model that can support parallel operation without turning temporary coexistence into a permanent state.

For practitioners

• Audit every SSO dependency before migration Document ACS URLs, Entity IDs, redirect URIs, signing keys, encryption settings, NameID formats, custom claims, and tenant routing logic for each connection before changing handlers.
• Segment connections by migration path Place low-count environments on per-connection reconfiguration and reserve the proxy pattern for larger connection sets that would otherwise force customer-by-customer IdP changes.
• Build a temporary routing map Maintain a live map of migrated and unmigrated connections so the initiation endpoint can send each login to the correct handler during cutover.
• Validate customer-visible identity attributes Test that profile fields such as email, NameID, and custom claims still map cleanly to existing user records after the new callback path is enabled.
• Retire the legacy SSO path only after proof of stability Keep legacy handlers until all connections show active status, successful sessions are visible, and logs confirm the old endpoint is no longer receiving traffic.

Key takeaways

• Homegrown SSO becomes fragile when protocol settings, tenant routing, and identity attributes are scattered across application code instead of governed as a lifecycle asset.
• The article shows that migration strategy depends on scale, with direct reconfiguration fitting smaller sets and proxy cutover helping when many customer connections must move.
• The control that matters most is disciplined inventory and phased retirement, because stable cutover depends on knowing exactly what each connection expects.

Key terms

• Sso Migration: The controlled move from one authentication integration to another without interrupting user access. In practice, it means preserving login continuity while the application, identity provider, and routing logic are reconfigured in phases.
• Proxy Cutover: A transition pattern where the existing callback or assertion endpoint stays in place and forwards traffic to a new identity system. It reduces customer-side changes, but it also creates a temporary dual-path state that must be tightly monitored.
• Identity Attribute Mapping: Identity attribute mapping is the process of defining how identity data fields correspond across source systems, directories, applications, and governance tools. It ensures that attributes such as department, title, or role are populated consistently, which supports automation, reporting, compliance, and reliable access decisions.
• Endpoint Inventory: A maintained record of every API route, owner, exposure level, and business purpose. It is a foundational governance control because teams cannot secure, review, or monitor what they do not know exists, especially in fast-changing cloud and partner ecosystems.

Deepen your knowledge

NHI governance, identity lifecycle management, and workload identity security are core topics in our NHI Foundation Level course, the industry's only accredited NHI security programme. If you are building or maturing an IAM programme, it is worth exploring.