Skip to content

docs: Add migration guide for moving off legacy serverpod_auth#585

Merged
Zfinix merged 4 commits into
mainfrom
chore/migrate-from-legacy-auth
Jun 9, 2026
Merged

docs: Add migration guide for moving off legacy serverpod_auth#585
Zfinix merged 4 commits into
mainfrom
chore/migrate-from-legacy-auth

Conversation

@Zfinix

@Zfinix Zfinix commented Jun 8, 2026

Copy link
Copy Markdown
Contributor

Summary

Apps still on serverpod_auth_server need a single, ordered path to the modular auth stack now that Serverpod 3.5 ships serverpod_auth_core, _idp, _bridge, and _migration as the supported lineage. PRs #302, #445, and #477 each covered a slice; none merged. This PR consolidates them into one guide aligned with the current docs/11-upgrading/ layout that Jamiu's PR #563 just established.

This PR:

  • Adds docs/11-upgrading/03-migrate-from-legacy-auth.md with an ordered checklist covering dependencies, initializeAuthServices config, AuthMigrations.migrateUsers, the password-importing email endpoint, Google legacy external ID handling, and the Flutter session import.
  • Lists the four passwords.yaml entries JwtConfigFromPasswords requires (jwtRefreshTokenHashPepper, jwtHmacSha512PrivateKey, serverSideSessionKeyHashPepper, emailSecretHashPepper) so the server actually starts.
  • Documents the Endpoints/Protocol name collision that serverpod_auth_bridge_server and serverpod_auth_migration_server create with the project's own generated classes, and shows the show/hide clauses and file layout that resolve it.
  • Adds sidebar_label: Migrate from legacy auth so the entry fits the Upgrading sidebar.

Supersedes #302, #445, #477. Those PRs can be closed with a pointer to this one after merge.

End-to-end test

Built a 2.x scaffold (serverpod_cli 2.9.3), added serverpod_auth_server, applied legacy schema, seeded 3 users (email-only, Google-only, email), upgraded all pubspec entries to 3.5.0-beta.9, configured the modular stack per this guide, applied the modular schema, and ran AuthMigrations.migrateUsers.

Verification queries

```text
-- 3 legacy users mapped:
SELECT id, "oldUserId", "newAuthUserId" FROM serverpod_auth_migration_migrated_user;
id | oldUserId | newAuthUserId
----+-----------+--------------------------------------
1 | 1 | 019ea6e9-9d54-7a02-85a2-a9de9d2385fe
2 | 2 | 019ea6e9-9db8-72d7-9756-5fa71f456a55
3 | 3 | 019ea6e9-9ddb-72fc-889b-8f84b89c7eeb

-- 2 legacy passwords carried over (email users only, Google user excluded):
SELECT count(*) FROM serverpod_auth_bridge_email_password; -- 2

-- 3 external user IDs seeded (Google sub for Bob, email fallback for Alice + Carol):
SELECT "userIdentifier" FROM serverpod_auth_bridge_external_user_id;

-- 3 new AuthUser rows:
SELECT count(*) FROM serverpod_auth_core_user; -- 3

-- Idempotency: rerunning migrateUsers returned 0.
```

Closes serverpod/serverpod#5110
Closes serverpod/serverpod#3663
Closes serverpod/serverpod#3450

@Zfinix Zfinix self-assigned this Jun 9, 2026
@Zfinix Zfinix requested review from Swiftaxe and developerjamiu June 9, 2026 10:51
Comment thread docs/11-upgrading/03-migrate-from-legacy-auth.md Outdated
Comment thread docs/11-upgrading/03-migrate-from-legacy-auth.md Outdated
Comment thread docs/11-upgrading/03-migrate-from-legacy-auth.md Outdated
Comment thread docs/11-upgrading/03-migrate-from-legacy-auth.md
Comment thread docs/11-upgrading/03-migrate-from-legacy-auth.md Outdated
Comment thread docs/11-upgrading/03-migrate-from-legacy-auth.md Outdated
Comment thread docs/11-upgrading/03-migrate-from-legacy-auth.md Outdated
Comment thread docs/11-upgrading/03-migrate-from-legacy-auth.md Outdated
Comment thread docs/11-upgrading/03-migrate-from-legacy-auth.md Outdated
Comment thread docs/11-upgrading/03-migrate-from-legacy-auth.md Outdated
Comment thread docs/11-upgrading/03-migrate-from-legacy-auth.md Outdated
Comment thread docs/11-upgrading/03-migrate-from-legacy-auth.md Outdated

@developerjamiu developerjamiu left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LGTM

@Swiftaxe Swiftaxe left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Splendid work!
LGTM

@Zfinix Zfinix merged commit ac1709f into main Jun 9, 2026
4 checks passed
@Zfinix Zfinix deleted the chore/migrate-from-legacy-auth branch June 9, 2026 14:37
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

3 participants