Implementation blueprint
Migrating from homegrown or workforce IAM to modern CIAM
For: Teams replacing a homegrown auth system, or a workforce IAM misused for customers, with a purpose-built CIAM.
Updated 2026-07-19
Problem context
Homegrown auth and workforce IAM repurposed for customers both hit the same wall: they cannot scale to consumer volumes, lack B2C UX and self-service, or cannot meet enterprise SSO and compliance demands. The migration is unavoidable, but it touches every logged-in user, so risk management dominates the design.
The core technique is lazy migration. Users are moved on their next successful login: the new CIAM verifies the password against the old hash (or accepts a one-time verifier), then stores it in its own format. This avoids forcing password resets on your entire base, which would crater engagement.
Reference architecture
Core flows
Lazy migration on first login
On a user's next login, the new CIAM verifies credentials against the legacy store, then writes the user into its own directory. Subsequent logins are fully native. The Cognito example below shows the pattern with SRP-hashed exports.
Data objects & boundaries
- Legacy user record
- The source of truth during coexistence; may hold non-portable password hashes.
- Password hash
- The critical portability question: bcrypt/argon2 can often be imported; proprietary or SRP hashes force lazy verification.
- Migration state
- Per-user flag tracking migrated vs not, so login can route to the right store.
- Identifier mapping
- Maps legacy user IDs to new CIAM subject IDs so existing sessions and links keep working.
Required standards & protocols
- OpenID Connect (OIDC) for the new authentication surface
- Bulk import APIs for portable hashes; lazy verification for non-portable ones
- OAuth 2.1 for downstream API access after cutover
Build-vs-buy decisions
| Decision | Build if | Buy if |
|---|---|---|
| Run the migration in-house vs vendor-assisted | You have a small, well-understood user base and clean hashes. | You have millions of users, messy hashes, or need lazy-migration tooling out of the box. |
| Keep the legacy system as an IdP | Never, long term; only during coexistence. | You want the legacy store retired, so pick a CIAM with strong import and lazy-migration support. |
| Password hashes vs forced reset | You can import the hashes directly, always prefer this. | Hashes are non-portable, use lazy verification, not a mass reset. |
Weigh the whole picture with the build-vs-buy worksheet.
Anti-patterns
Big-bang cutover
Flipping all users at once with no dual-run turns any defect into a total outage of login; phase it.
Forcing a password reset for everyone
Mass resets crater engagement and flood support; migrate hashes or verify lazily instead.
Not planning for non-portable hashes
SRP and proprietary hashes cannot be imported directly; design lazy verification before you start.
Dropping identifier continuity
If subject IDs change without a mapping, existing sessions, links, and integrations break.
Implementation checklist
- Inventory the legacy user store and its password-hash format
- Decide bulk import (portable hashes) vs lazy verification (non-portable)
- Stand up the new CIAM alongside the legacy store (coexistence)
- Dual-run and migrate users lazily on next login
- Maintain an identifier mapping for session and link continuity
- Monitor the migrated-vs-remaining long tail
- Cut over once the legacy store is drained, then decommission it
- Avoid any forced password reset for the whole base
What to require of a platform
- Bulk user import including common password-hash formats
- Lazy / just-in-time migration hooks for non-portable hashes
- Custom database or import connectors to the legacy store
- Identifier mapping and account linking
- Zero-downtime dual-run support
Related guides
Head-to-head comparisons
Compliance
Transformation patterns
FAQ
- Do I have to reset everyone's password to migrate?
- No, and you shouldn't. Migrate users lazily on their next login, verifying against the old store then re-hashing, or bulk-import portable hashes. A mass reset craters engagement and floods support.
- What if my password hashes aren't portable?
- Use lazy verification. If the legacy hashes are proprietary or SRP-based, validate the first login against the old system, then store the credential in the new format. Design this before you start, not after.