Notifications
Clear all
Topic starter
04/06/2026 6:50 pm
TL;DR: A step-by-step migration from homegrown SAML and OAuth/OIDC connections to WorkOS centers on auditing current SSO dependencies, choosing either per-connection reconfiguration or a proxy approach, and cutover planning for zero customer downtime, according to WorkOS. The real issue is not the migration path itself but the operational fragility of bespoke SSO logic and the governance it leaves behind.
NHIMG editorial — based on content published by WorkOS: Migrating from a homegrown SSO implementation to WorkOS
Questions worth separating out
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.
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.
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.
Practitioner guidance
- 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.
- 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.
- 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.
What's in the full article
WorkOS's full blog post covers the operational detail this post intentionally leaves for the source:
- Code-level examples for Next.js and Express callback handling across SAML and OIDC.
- WorkOS Admin Portal setup flow for IT admins who must reconfigure IdP connections.
- CSV import details for proxy-based migration when customer IdPs cannot be changed.
- Event monitoring examples using the WorkOS Events API and Datadog integration.
👉 Read WorkOS's migration guide for homegrown SSO to WorkOS →
Homegrown SSO migration to WorkOS: what changes for IAM teams?
Explore further
04/06/2026 7:05 pm
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.
A few things that frame the scale:
- 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.
A question worth separating out:
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.
👉 Read our full editorial: Migrating homegrown SSO to WorkOS: what IAM teams need to know
