Migrating identity providers without a flag day: A zero-downtime playbook

Switching identity providers is a complex and high-stakes process that affects every user session, login flow, and SSO connection, presenting significant risks if not handled correctly. To avoid the pitfalls of a "flag day" approach—where all users are migrated simultaneously, leading to potential system-wide failures—WorkOS proposes a gradual migration strategy. This involves four phases: shadow authentication, just-in-time (JIT) provisioning on login, password hash import, and individual SSO connection cutover. Shadow authentication allows both the old and new providers to run concurrently, routing users based on their migration status, while JIT provisioning migrates users during their login process without disruption. Password hash import ensures inactive users can transition smoothly without requiring password resets, although some providers like Cognito may necessitate alternative actions. The SSO cutover phase requires careful coordination for each connection to avoid service interruptions, with the option of using a transparent proxy for larger scales. By implementing these phased steps, the risk of migration failures is minimized, making the transition seamless and avoiding the need for a risky, all-at-once switch.