Bulk user migration runbook

You're migrating users into IntelliAuth from another platform (Auth0, your old custom auth, a CSV your HR team produced). Tens of thousands of records. One mistake on a large import is hours of cleanup.

This runbook is the procedure several teams have used successfully. Follow it.

Phase 0 — Inventory + preflight (½ day)

Before you touch anything, know what you have.

Count the source records

Export from the source platform. Count the rows. Note distribution by:

State (active / disabled / pending verification).
Identity type (password vs federated).
Email domain (% from each domain).
Group memberships.
Custom attribute coverage (which attributes are populated, on what % of users).

This is your reference. Anything that doesn't match in IntelliAuth at the end of the migration is drift you need to investigate.

Decide the password strategy

For users with passwords, you have three options. Read Migrate from Auth0 for the full discussion. Quick summary:

Reset on first sign-in — bulk-import with password_must_be_reset: true. Every user changes their password on first IntelliAuth sign-in. Most painful for users; cleanest migration.
Live migration via broker — needs the source platform to be online during the cutover. The source verifies; IntelliAuth provisions on success. Less painful for users.
Just-in-time at first IntelliAuth sign-in — hybrid. New users sign in; if not found in IntelliAuth, fall back to source; provision in IntelliAuth on success.

Pick one. Document the choice + the reasoning in the runbook.

Decide the federated identity strategy

For users with Google / GitHub / SAML identities:

Pre-configure the matching federation connections in IntelliAuth (per Social providers and SAML applications).
Don't import the federated identities directly — let them auto-link on first sign-in (per the email-matched account linking default).

Pick a date + communicate

Send the email N weeks in advance:

The cutover date + time.
What users need to do (probably: nothing for federated; first-sign-in reset for password users).
Where to get help.

A typical comms cadence: announce 2 weeks before, remind 1 week before, remind 1 day before, alert when complete.

Phase 1 — Build the import file (1-2 days)

Export from source

Pull the user records from the source platform. Get every field you care about.

Transform

The source's field names rarely match IntelliAuth's. Write a small transformation script:

Map source fields to IntelliAuth fields (per bulk import format).
Normalise email casing (IntelliAuth treats User@cymmetri.com and user@cymmetri.com as the same; clean the source).
Split name into given_name + family_name if your source mixes them.
Drop fields IntelliAuth doesn't accept (password hashes, source-platform internal ids).
Map custom attributes if the schemas differ.

The output is an NDJSON file with one user per line.

Validate locally

Before uploading, check the file:

Every line is valid JSON.
Every email is unique (no duplicate rows).
Every email matches RFC 5321 / 5322.
Required fields are present per the IntelliAuth schema.

Catch problems here, not in the import.

Phase 2 — Staging rehearsal (1 day)

Don't import into production first. Always rehearse.

Provision a staging tenant

If you don't already have one, get your platform admin to provision staging-cymmetri. Configure it to roughly mirror production:

Same authentication policy.
Same MFA enforcement (probably).
Same federation connections (use staging credentials on the IdP side).
Same custom attribute schema.

Import the file into staging

Users → Bulk import → NDJSON → upload your file. Watch the import progress.

Common issues that surface in staging (and not in production, if you've rehearsed):

The custom-attribute schema differs slightly.
A group named in the import doesn't exist.
A password fails the policy.
An email contains characters the source allowed but IntelliAuth doesn't.

Fix each. Re-import. Iterate until the staging import is clean.

Verify staging counts

After import: count users in staging. Compare to your source-of-truth count.

Match: continue.
Drift: investigate. Find the missing rows; fix; re-import the deltas with upsert mode.

Test sign-ins on staging

Have a few colleagues sign in via staging:

Password user → reset their password → sign in. Confirm the policy lets them through.
Federated user → sign in via Google → confirm auto-link.
SSO user → sign in via SAML → confirm JIT provisioning.

Each shows you whether the migration is correct end-to-end, not just "rows arrived".

Phase 3 — Cutover plan (½ day)

Write the runbook for cutover day. A typical structure:

T-1 day: final source-data export. Re-transform. Final pre-flight validation.
T-0:00: comms goes out. "Authentication is being migrated; expect brief disruption."
T-0:05: source platform put into read-only / disabled mode.
T-0:10: NDJSON file uploaded to production tenant.
T-0:?? (depends on size): import completes. Verify counts.
T-0:??+5: spot-check sign-ins. A few from each identity type.
T-0:??+15: if all clean, comms goes out. "Migration complete; you may need to reset your password on first sign-in."
T-0:??+1h: monitor audit for sign-in failure spikes; reach out proactively.
T-0:??+24h: review delta in active sessions; investigate stragglers.

Phase 4 — Cutover day

Execute the runbook. Two people; one drives, one watches; both with access to the runbook and the rollback path.

Watch for:

The import's failed count going up — log each error; decide between fixing-and-re-importing vs hand-fixing the user records afterward.
A spike in user.signed_in.failed on the audit log post-migration — usually password-policy mismatches; communicate and provide reset paths.
Federation connections failing — usually a configuration mismatch between source and IntelliAuth; verify metadata is current.

Phase 5 — Rollback (only if necessary)

If the migration goes badly, the rollback path is:

Re-enable the source platform.
Send the comms: "we're rolling back; sign-ins are temporarily disabled in IntelliAuth; use <source-platform>."
Disable the IntelliAuth tenant's user-facing applications (Applications → bulk-disable customer-facing apps).
Triage the issues; plan the next attempt.

The IntelliAuth-side data isn't lost — it's still there. You can re-resolve and re-cutover later. Rollback is "stop the bleed, go back, fix, try again."

Phase 6 — Post-cutover (1 week)

Watch the audit log + dashboards for the first week. Investigate any anomalies.
Drain support tickets — first-week tickets are usually password-reset / "I forgot how MFA works" issues; standard responses.
After a week of stability, decommission the source platform (per your offboarding plan).

Common pitfalls

No staging rehearsal. "It's just a CSV; how hard can it be?" Production blows up in week 3 when a user with a weird email format sees they can't sign in.
No comms. Users wake up on cutover day, confused about why their password no longer works.
No rollback plan. Halfway through cutover, something's wrong; the team panics.
Counting only the rows imported. Drift between source and destination is normal; the post-migration spot-check is what catches it.
Underestimating support load. Tens of thousands of users + a forced reset = tens of thousands of support contacts in the first 48 hours. Plan support staffing.