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 SAML and OAuth/OIDC SSO with WorkOS, focused on audit, cutover, and decommissioning steps.

Why it matters: It matters because SSO migration decisions affect enterprise access continuity, IdP coordination, and lifecycle governance across human identities, service access, and federated login paths.

👉 Read WorkOS's migration guide for homegrown SSO to WorkOS

Context

Homegrown SSO becomes a governance problem when connection logic, tenant routing, and IdP quirks live in code only a handful of engineers understand. In identity programmes, that creates dependency risk, change-control drag, and brittle recovery paths whenever certificates, claims, or enterprise IdP settings change.

This guide frames migration as an operational transition, not a simple feature swap. The practitioner question is how to preserve access continuity while moving authentication handling, connection mapping, and admin setup into a model that reduces bespoke maintenance without losing control over SAML and OAuth/OIDC behaviour.

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: What breaks when a custom SSO implementation is too tightly coupled to tenant-specific IdP settings?

A: Changes to ACS URLs, NameID formats, redirect URIs, or claims mappings can break login for a single customer or a whole tenant. In practice, the coupling turns authentication into a brittle release surface, where small IdP changes create outages or manual support work.

Q: How do you know when an SSO migration is actually complete?

A: A migration is complete when every connection is active in the new system, old handlers receive no traffic, successful sessions continue across the customer base, and customer-facing setup guides point to the new admin flow. If any legacy dependency remains in use, the cutover is still partial.

Q: What is the difference between direct reconfiguration and a proxy-based SSO migration?

A: Direct reconfiguration asks each customer to update their IdP settings, which is practical for a small number of connections. A proxy-based migration preserves the existing callback URL and forwards requests to the new service, which reduces customer rework when many connections must move gradually.

Technical breakdown

SAML connection migration and callback handling

A homegrown SAML integration usually hard-codes the ACS URL, SP Entity ID, signing keys, response encryption settings, and attribute expectations for each tenant. Migration works only if the new callback path can preserve those identity bindings while rerouting assertions cleanly. When the system has many tenants, the proxy pattern becomes a routing layer that forwards SAML responses to a new service based on tenant context. That means the old callback is no longer the identity processor, only the handoff point. The operational risk is malformed routing, inconsistent NameID mapping, or breaking IdP-initiated flows during transition.

Practical implication: inventory every SAML dependency before cutover and validate routing logic against tenant-specific assertion handling.

OAuth and OIDC redirect flow migration

OAuth and OIDC migrations hinge on client IDs, redirect URIs, scopes, and any custom claims used to match a login to an internal user record. The callback endpoint must exchange the authorization code reliably and then map the resulting profile back to the correct tenant or account. If a deployment supports both legacy and migrated connections, the initiation endpoint becomes a decision point that sends some users to the new flow and others to the old one. This is less about authentication theory than about avoiding mismatched redirects, broken session linkage, and hidden dependency on legacy handlers.

Practical implication: keep legacy and migrated redirect logic side by side until each connection proves stable in production.

Decommissioning old SSO code without breaking access

Decommissioning is a control exercise, not a cleanup task. Legacy SSO code should only be removed after every connection is active in the new system, successful sessions are observed, and no traffic reaches the old handlers. The article also shows why IdP certificate renewal, readable error handling, and admin self-service matter after cutover, because they shift ongoing operational burden away from bespoke code. If old libraries, undocumented callbacks, or customer-facing setup guides remain, the migration is incomplete even if authentication appears to work.

Practical implication: tie code removal to verified session telemetry, clean log evidence, and updated customer-facing setup documentation.

Breaches seen in the wild

• Salesloft OAuth token breach — hackers stole OAuth tokens to access Salesforce data via Salesloft.
• Dropbox Sign breach — compromised Dropbox Sign service account exposed API keys and OAuth tokens.

Read our 52 NHI Breaches Analysis report for a comprehensive view of breaches impacting Non-Human Identities including AI Agents.

NHI Mgmt Group analysis

Homegrown SSO is a governance liability before it is a technical stack choice. Once connection state, tenant routing, and IdP-specific exception handling are embedded in custom code, the organisation inherits knowledge concentration risk and brittle change control. That is not simply an engineering debt issue. It is a lifecycle governance problem because access continuity depends on undocumented identity behaviour that only a few people can safely modify. Practitioners should treat bespoke SSO as a governed identity asset, not a convenience layer.

Connection migration exposes how much of enterprise access management lives outside formal IAM process. The article shows that redirect URIs, ACS URLs, NameID formats, attribute mappings, and customer admin instructions all become part of the control plane. That means the real migration surface is not one callback endpoint, but the full set of identity dependencies that determine whether a user can authenticate without intervention. For IAM and IGA teams, this is a reminder that federated access is a lifecycle object with configuration state, not a static integration.

Proxy-based cutover is a useful pattern, but it shifts the assurance burden to routing integrity. When legacy callbacks forward requests to a new identity service, the security question becomes whether the proxy consistently resolves the correct tenant and preserves the original request context. That makes observability, mapping accuracy, and rollback discipline the decisive controls. The practitioner conclusion is straightforward: migration success depends on whether the intermediary layer can be audited like any other privileged identity path.

Managed federation does not eliminate identity governance, it relocates it. Moving SAML and OAuth/OIDC handling out of custom code can reduce maintenance load, but the organisation still owns entitlement mapping, connection onboarding, and offboarding decisions. The mature posture is to recognise that enterprise SSO is a governed access fabric, not a one-time implementation. Teams that treat migration as a pure engineering project will miss the ongoing lifecycle controls that determine whether authentication remains stable after the cutover.

Named concept: callback routing dependency. In this migration pattern, the callback endpoint becomes a single point where authentication state, tenant identity, and legacy-versus-new processing decisions converge. That concentration matters because any mismatch between routing logic and identity context can affect every login path for a tenant. Practitioners should recognise callback routing as a governed dependency with blast-radius implications, not as a simple URL change.

From our research:

• Only 20% have formal processes for offboarding and revoking API keys, and even fewer have procedures for rotating them, according to Ultimate Guide to NHIs.
• 96% of organisations store secrets outside of secrets managers in vulnerable locations including code, config files, and CI/CD tools.
• For the broader lifecycle view, Ultimate Guide to NHIs , Key Challenges and Risks connects offboarding gaps to visibility, rotation, and privilege control.

What this signals

Callback routing dependency: migration work exposes a familiar identity pattern. When authentication state, tenant context, and legacy-versus-new processing all converge in one path, the risk is not just outage. It is that the organisation has built a privileged decision point without treating it like one. Teams should expect tighter audit requirements around who can modify routing logic and how rollback is validated.

The governance signal is that SSO migration is now inseparable from lifecycle discipline. Enterprise access paths need the same offboarding, exception handling, and documentation rigor that IAM teams apply to other non-human and federated credentials. That is where the operational resilience gains will come from, not from the code move alone.

For practitioners

• Audit every SSO dependency before migration Document ACS URLs, SP Entity IDs, signing and encryption settings, NameID formats, redirect URIs, scopes, custom claims, and tenant identification logic before changing any flow. Treat the inventory as the baseline for deciding whether a connection can be moved transparently or needs customer reconfiguration.
• Separate migrated and legacy paths during cutover Keep a routing map that sends only verified connections to the new callback handler while leaving unmigrated tenants on the legacy path. Validate each switch with successful session telemetry and rollback capability so a bad mapping does not disrupt enterprise access.
• Use the proxy pattern only with strict routing validation If you have many connections, preserve the existing callback URL as a proxy and confirm that every forwarded request retains the correct tenant context. Test RelayState handling, redirect behaviour, and fallback logic so the proxy cannot misroute one customer’s authentication traffic to another.
• Retire old SSO code only after traffic drops to zero Remove legacy libraries, handlers, and documentation only after logs show no requests hitting the old flow and all connections have active status with successful sessions. Keep DNS resolution for any residual callback domains until customer IdP settings have fully converged.

Key takeaways

• Homegrown SSO often becomes an identity governance problem because connection logic and tenant routing are trapped in custom code.
• The migration surface includes assertions, redirect handling, and customer admin setup, so cutover success depends on preserving identity context end to end.
• Practitioners should treat decommissioning as a control milestone, with telemetry and documentation proving that the legacy path is truly retired.

Key terms

• Sso Connection: An SSO connection is the configured trust relationship between a service provider and an identity provider for a specific tenant or customer. It includes the identifiers, URLs, certificates, and claim mappings needed to authenticate users reliably without custom rework.
• Callback Proxy: A callback proxy is an intermediary endpoint that receives authentication responses and forwards them to a new identity service when a connection has been migrated. It preserves the external URL while the underlying processing path changes, which can reduce customer reconfiguration during cutover.
• Nameid Format: NameID format is the structure used in SAML to identify the authenticated subject, such as email address, persistent identifier, or transient identifier. It affects account matching, tenant routing, and whether a migration can preserve user identity without changing customer settings.
• Federated Access Lifecycle: Federated access lifecycle is the governed set of steps that creates, updates, validates, and retires external identity connections over time. It matters because SSO is not static infrastructure. It changes with certificates, claims, tenant mappings, and decommissioning decisions.

Deepen your knowledge

SSO migration, federation dependencies, and lifecycle controls are core topics in our NHI Foundation Level course, the industry's only accredited NHI security programme. If you are replacing custom authentication code with governed identity flows, it is worth exploring.

This post draws on content published by WorkOS: Migrating from a homegrown SSO implementation to WorkOS. Read the original.