Last updated: June 2026
TL;DR
Dual-run is the IAM migration strategy where your old and new identity providers stay live at the same time, so you cut apps over one wave at a time, each with its own rollback, instead of betting a 50-plus-app estate on one big-bang weekend. Big-bang cutovers fail in predictable ways, and the failures all land at once. Dual-run spreads the risk. The short version:
- Coexistence is the whole trick. Both IdPs serve traffic during the migration. New apps land on the new provider, legacy apps keep trusting the old one, and you move the rest in planned waves.
- A brokered chain keeps one password story. The new IdP brokers the old one (or the reverse), so a user logs in once and never sees two prompts or a forced reset during the overlap.
- Waves get ranked, not guessed. Sequence apps by protocol, token coupling, traffic, business criticality, and blast radius. Easy and low-risk first, scary and central last.
- Rollback is a design input, not a hope. Each wave gets a defined revert (route flip, client config rollback, re-point the broker) and metrics that trigger it.
- Be honest about “zero downtime.” Dual-run buys you per-app, planned, reversible cutovers with little or no outage. The safety comes from coexistence plus rollback, not from any tool.
We run managed Keycloak for teams executing exactly these waves, so this is the same playbook we walk customers through before they pick a cutover weekend they will regret.
What is dual-run in IAM migration?
Dual-run means both your current and target identity providers run in production simultaneously while you migrate applications one wave at a time. Industry migration practice has converged on phased coexistence for large estates precisely because big-bang cutovers concentrate risk: AWS’s prescriptive guidance on identity provider migration frames phased moves as the default for reducing blast radius. The old IdP stays the safety net until the last app lands.
Here is the contrast that matters. A big-bang cutover flips every application from the old IdP to the new one in a single change window. When it works, it is fast. When it does not, and at 50-plus apps it usually does not, every login on every app breaks at the same moment, your rollback is a platform-wide revert under incident pressure, and your change advisory board never approves the next attempt.
Dual-run inverts that. You stand up the new IdP next to the old one, prove token and session behavior on low-risk apps first, then move the rest in waves. We have watched teams cut over a 12-app wave on a Tuesday afternoon and roll a single misbehaving app back in four minutes without touching the other eleven. That is the entire point: small, reversible moves instead of one terrifying one.
One honest caveat before we go further. Dual-run is more total work than a big-bang, not less. You operate two identity systems for the length of the migration, which is real overhead. What you buy with that overhead is predictability and a rollback path. For most large estates that trade is obvious, but pretend otherwise and you will under-resource the migration quarter.
How does the dual-run pattern actually work?
The pattern has three moving parts: both IdPs live, a brokered chain so users see one login, and an app-by-app cutover in waves. Microsoft’s application migration guidance for Entra ID describes the same shape: stand the new provider up, federate the two during the overlap, then move apps in batches. The federation link is what keeps users from ever seeing the seam.
The brokered chain is the piece teams underestimate, so let’s be precise about direction. There are two ways to chain the providers, and which you pick depends on where you are in the migration.
New IdP brokers the old one
Early in the migration, the old IdP still owns the user store and the credentials, so the new IdP brokers it. The new provider becomes a relying party (a SAML SP or OIDC client) in front of the old authority. New apps point only at the new IdP and never know the old one exists. When a user hits a new app, the new IdP transparently redirects to the old one for the actual login, then mints its own fresh tokens. This is the early-phase topology in our SiteMinder federation guide, where Keycloak brokers SiteMinder while you onboard modern OIDC apps.
Old IdP brokers the new one (or apps point straight at the new IdP)
Later, once the new IdP holds the user store (or federates the same LDAP/AD the old one read), you flip. The new provider becomes the authority. Apps repoint to it directly, and any legacy app that cannot move yet stays behind the old IdP, which now trusts an assertion from the new one. That is the late-phase direction covered in both our Cloud Foundry UAA migration playbook and the SiteMinder guide above. Those two posts are concrete instances of this exact pattern; this post is the judgment layer on top of them.
Most large migrations run both directions at once during the overlap. That looks messy on an architecture diagram and is completely normal in practice. The diagram is ugly for a quarter so the cutover is not.
How do you rank and sequence apps into waves?
You rank apps by five factors, then sequence the lowest-risk, highest-confidence apps first to build operational muscle before you touch anything central. The Open Group’s migration planning guidance in TOGAF calls this work-package sequencing by dependency and risk, which is exactly the discipline an IAM wave plan needs. The order is the strategy. Get it wrong and your first wave is also your worst incident.
Score every application on these five dimensions, then sort.
The five ranking factors
- Protocol. Standards-native OIDC apps with library-managed discovery are the easiest moves: change an issuer URL, a client ID, and a secret. SAML apps are next. Header-injection and proprietary-token apps are hardest and go last.
- Token coupling. How tightly does the app read provider-specific claims? An app that only needs
subandemailis trivial. An app parsing a vendor dialect claim through opaque-token introspection is a late wave. - Traffic. Volume sets your observation window. Low-traffic apps give you fast, low-stakes feedback. Save the highest-traffic apps for after the pattern is proven, never before.
- Business criticality. Revenue and compliance-critical apps move once you have repeated the cutover enough times that it is boring. Boring is the goal.
- Blast radius. If this app fails, how many users and downstream systems feel it? Shared-login portals and apps other systems depend on are high blast radius and belong in late, well-rehearsed waves.
Turning scores into waves
Give each factor a 1-to-5 score where 1 is easy or low-risk and 5 is hard or high-risk, then sum them. Wave 1 is your lowest-scoring cluster: stateless OIDC apps, low traffic, low coupling, low blast radius. Wave 1 exists to prove the pipeline and catch the boring failures (clock skew, CORS, redirect URIs) on apps nobody pages about. Each subsequent wave climbs the score. Your final wave is the handful of high-coupling, high-blast-radius apps you have now rehearsed the pattern around a dozen times.
A practical rule we use: no wave should mix your easiest and your scariest app. Keep waves internally similar in risk so that when something breaks, you already know roughly why.
How do you keep users sane during coexistence?
You give users exactly one password story by federating the two IdPs so credentials live in one place, never two. This is the make-or-break user-experience decision: a survey by the FIDO Alliance found that consumers abandon roughly a quarter of purchases when they hit login friction, and a forced password reset mid-migration is friction users did not ask for. During dual-run, a user should never see two login screens or a reset email.
There are three clean ways to keep one credential during the overlap, and they map directly to where the credentials actually live.
Federation or brokering (credentials stay upstream)
If most of your users actually originate from an upstream LDAP, Active Directory, or SAML source, you do not migrate passwords at all. Both IdPs federate the same upstream, so they see one source of truth and the user keeps the credential they already have. This is the cleanest case and, for workforce IAM, the common one. Wire it once and the password question disappears.
Brokered login (one IdP fronts the other)
When the old IdP owns local credentials, the brokered chain from the previous section carries the password story for free. The user authenticates at whichever IdP holds their credential, and the brokering provider mints tokens without ever asking again. One login, one prompt, no reset.
Migrate on first login
When you genuinely need to move credentials into the new store, do it silently. Stand up a thin federation provider that validates a user’s first login against the old system, then writes the credential natively into the new IdP on success. The user logs in normally and notices nothing. The shim retires once the trickle of first-logins stops. We cover the mechanics of this for a specific source in the UAA migration playbook; the strategy generalizes to any source.
The one option to avoid unless the user base is tiny: a mass forced reset. It converts a quiet infrastructure migration into a customer-facing event, spikes your support queue, and trains users to expect chaos from your identity team. Reserve it for the rare estate where no other path exists.
How do you design rollback for each wave?
Rollback is a per-wave design artifact: a defined revert action plus the metrics that trigger it, decided before the wave runs, not improvised during the incident. Google’s SRE workbook makes the case plainly: a deploy without a rollback plan and clear rollback signals is not a controlled change, it is a gamble. Dual-run earns its keep here, because both IdPs are live, so reverting a wave is a config change, not a platform rebuild.
What rollback actually means depends on how the wave cut over, and there are three common shapes.
The three revert mechanisms
- Route or DNS flip. If the wave moved traffic by repointing a hostname or a load-balancer route to the new IdP’s endpoints, rollback flips it back. Keep TTLs short during the migration window so a flip propagates in minutes, not hours.
- Client config revert. If each app cut over by changing its issuer URL, client ID, and secret, rollback restores the previous values. This is the most common and the cleanest. Keep the old IdP’s client definitions warm, not deleted, for the entire rollback window.
- Re-point the broker. If the wave changed which provider the brokered chain trusts, rollback re-points the broker to the prior authority. This is the heaviest revert and the reason late waves need the longest soak time.
The metrics that should trigger a rollback
Define the trip wires before you cut over, with numbers, not vibes. The three signals that matter:
- Authentication error rate. Watch failed-login and token-validation error rates per app against a pre-cutover baseline. A sustained jump (say, error rate above 2 percent for five minutes when baseline is near zero) trips the wire.
- Login latency. P95 login time creeping up signals broker misconfiguration, clock issues, or an overloaded new IdP. Set a threshold relative to baseline and alert on it.
- Support ticket volume. The human signal. A spike in auth-related tickets is often the first sign of a failure your dashboards missed, especially silent session or logout problems.
Write the rollback decision down as an if-this-then-revert rule and give one named person the authority to pull it without convening a meeting. The whole value of dual-run evaporates if rolling back requires a 30-minute bridge call to get permission.
When is a token compatibility shim worth building?
A thin claim-mapping shim is worth it when a small, known set of apps reads a provider-specific claim you can reproduce declaratively; a full translation layer that proxies and rewrites tokens at runtime is almost never worth it. The cost asymmetry is the whole decision. Industry research consistently ties accumulated technical debt to a large share of engineering capacity, with studies cited by McKinsey putting the tax at up to 40 percent of IT estate value. A runtime token translator is exactly the kind of permanent tax that starts as a temporary bridge.
Here is the line we draw, and we draw it hard.
When a thin shim is justified
Build the shim when the gap is a handful of claims your apps read and the new IdP can emit them natively through configuration. In Keycloak terms, that is protocol mappers: you reproduce a legacy claim like a custom user_name or a roles claim with a declarative mapper, ship it in your migration pipeline, and verify the output token against the old one claim by claim. That is not a translation layer. It is configuring the new IdP to honor the existing token contract, and it lives in version control next to the rest of your realm config. This is the right call, and the UAA playbook shows it in practice.
When to refuse the translation layer
Refuse to build a standalone service that intercepts tokens and rewrites their shape at runtime. The pitch is always reasonable: “we will run a proxy that translates old tokens to new ones so the apps never have to change.” What you actually get is a new piece of critical-path infrastructure that every login flows through, that needs its own HA, monitoring, and on-call, that nobody owns after the migration ends, and that quietly becomes permanent because removing it means touching the very apps you built it to avoid touching. We have seen these “temporary” translators outlive the migration by years.
The honest alternative is usually cheaper than it looks: change the app. If an app’s token coupling is so deep that only a runtime translator can save it, that app is telling you it needs a small code change, and a small code change with a clear owner beats a permanent platform component with none. The shim that lives in your IdP config is fine. The shim that lives in the request path is debt with a countdown timer you will never get to.
What does a dual-run timeline look like for 100 apps?
A 100-app estate typically runs two to four quarters of dual-run, dominated by app-team coordination rather than identity engineering. Gartner has long noted that large IAM programs routinely run multi-quarter timelines because the constraint is organizational coordination, not technology. The IdP build is weeks. The waves are the calendar. Below is the template we start from and then tune to the estate.
| Phase | Duration | Wave size | What happens | Checkpoint to pass |
|---|---|---|---|---|
| Phase 0: Build and prove | 3-4 weeks | 0 apps | Stand up the new IdP, federate the old one, verify token and session behavior, build the cutover and rollback runbooks | Token output matches the old IdP claim-for-claim on a test app; rollback rehearsed once |
| Phase 1: Pilot wave | 2-3 weeks | 5-8 apps | Lowest-score apps only: stateless OIDC, low traffic, low coupling. Prove the pipeline and catch the boring failures | Pilot apps stable for a full week; error rate and latency at baseline; one real rollback executed and recovered |
| Phase 2: Volume waves | 6-10 weeks | 10-15 apps per wave | The bulk of the estate moves in ranked waves, one every 1-2 weeks, each soaked before the next starts | Each wave hits baseline metrics before the next launches; no wave mixes easy and scary apps |
| Phase 3: Hard tail | 4-8 weeks | 3-6 apps per wave | High-coupling, high-blast-radius, header-injection, and legacy apps. Smaller waves, longer soak, broker re-points | Each hard app rehearsed in staging first; rollback window held warm for each |
| Phase 4: Decommission | 2-4 weeks | 0 apps | Freeze writes on the old IdP, hold it read-only and warm through the final rollback window, then retire it | Final rollback window elapsed with no incident; old IdP confirmed unused before shutdown |
Two notes on reading that table. First, the durations overlap less than they look: Phase 0 must finish before Phase 1, but inside Phase 2 you can run waves concurrently if you have the team to watch them. Second, the hard tail is where timelines slip, every time. Budget generously for Phase 3, because the apps that resisted earlier waves resisted for reasons that surface late.
For the planning-and-protocol side of a refresh (deployment models, compliance frameworks, and the upfront audit that feeds your wave ranking), our authentication modernization planning guide covers that ground. This post is the execution pattern that runs after that planning is done.
Frequently asked questions
What is dual-run in IAM migration?
Dual-run is an IAM migration strategy where your old and new identity providers both run in production at the same time. New apps land on the new provider, legacy apps keep trusting the old one, and you migrate the rest in planned waves. Both IdPs stay live, so every wave has a real rollback path instead of one all-or-nothing cutover.
How long does an SSO migration take?
It depends on app count, not identity engineering. The new IdP build and token mapping take a few weeks. The calendar time is the app waves: small estates land in a few weeks, while a 100-app enterprise estate typically runs two to four quarters of dual-run, dominated by app-team coordination rather than technical work on the identity layer itself.
How do you migrate SSO without downtime?
You run both identity providers simultaneously and cut apps over one wave at a time, each with its own rollback. Honestly, the right claim is “no big-bang outage” rather than magic zero downtime: each app moves in a planned, reversible window. The safety comes from coexistence plus a defined rollback, not from any single tool or vendor feature.
What triggers a rollback during a wave?
Pre-defined metric thresholds, decided before the wave runs. The three signals are authentication error rate jumping above baseline (for example, over 2 percent for five minutes), login P95 latency creeping up, and a spike in auth-related support tickets. Each trigger maps to a defined revert (route flip, client config revert, or broker re-point) that one named person can execute immediately.
Should I build a token translation layer for legacy apps?
Almost never. A thin claim-mapping shim configured inside the new IdP (Keycloak protocol mappers, for example) is fine because it lives in version control and honors the existing token contract. A standalone runtime proxy that rewrites tokens becomes permanent critical-path infrastructure with no owner. If an app needs that, it usually needs a small code change instead, which is cheaper long term.
Does dual-run mean managing two identity systems at once?
Yes, and that is the honest cost. For the length of the migration you operate both IdPs, including HA, patching, monitoring, and backups for the new one. What you buy with that overhead is per-app, reversible cutovers instead of a single high-risk event. For most large estates the trade is worth it, but plan and resource for two systems running in parallel.
Summary
Big-bang IdP cutovers fail in predictable ways, and they fail everywhere at once. Dual-run is the strategy that avoids that: keep both identity providers live, chain them so users see one login, and migrate apps in ranked waves where the easiest move first and the scariest move last after the pattern is proven. Each wave gets a real rollback (route flip, client config revert, or broker re-point) and metric triggers that decide when to pull it. Keep one password story through federation, brokering, or silent migrate-on-first-login, never a mass reset. Build thin claim-mapping shims in your IdP config, but refuse runtime token translators that become permanent debt. For a 100-app estate, plan two to four quarters and budget heavily for the hard tail. Done this way, the migration is a series of small, reversible moves instead of one outage with your name on it.
The part that quietly eats the quarter
The wave plan is the easy part to write. Operating a hardened, highly available new IdP next to the old one for the full length of a multi-quarter migration is the part that drains your team: HA, upgrades, patching, monitoring, and on-call for a brand-new identity platform at exactly the moment your architects are busy migrating apps.
That part is outsourceable. Skycloak runs the Keycloak side with an enterprise SLA, upgrades, and on-call handled, so your team spends the coexistence period moving apps instead of babysitting a new IdP. We have run these waves. If you are staring down a big-bang cutover, talk to us first and we will sanity-check your wave plan and rollback design for free.