Skip to content

Commit f7cb083

Browse files
tptp
committed
docs: Document serverpod_auth_email setup and migrating from serverpod_auth to the new provider using serverpod_auth_migration
Closes serverpod/serverpod#3663
1 parent b893c13 commit f7cb083

File tree

2 files changed

+219
-0
lines changed

2 files changed

+219
-0
lines changed

‎docs/06-concepts/11-authentication/01-setup_new.md

Lines changed: 111 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,111 @@
1+
# Setup
2+
3+
<!-- TODO: Describe modular approach, list major packages -->
4+
5+
## Sessions
6+
7+
## Email
8+
9+
To get started with email based authentications, add `serverpod_auth_email` to your project. This will add a sign-up flow with email verification, and support logins and session management (through `serverpod_auth_session`). By default this adds user profiles for each registration through `serverpod_auth_profile`.
10+
11+
The only requirement for using this module is having a way to send out emails, so users can receive the initial verification email and also request a password reset later on.
12+
13+
14+
### Server setup
15+
16+
Add the module as a dependency to the server project's `pubspec.yaml`.
17+
18+
```sh
19+
$ dart pub add serverpod_auth_email_server
20+
```
21+
22+
Further it's advisable to depend on `serverpod_auth_session` directly as well, to avoid any lint warnings when using it later.
23+
24+
```sh
25+
$ dart pub add serverpod_auth_session_server
26+
```
27+
28+
As the email auth module does not expose any endpoint by default, but rather just an [`abstract` endpoint](concepts/working-with-endpoints#endpoint-method-inheritance), a subclass of the default implementation has to be added to the current project in order to expose its APIs to outside client.
29+
30+
For this add an `email_account_endpoint.dart` file to the project:
31+
32+
```dart
33+
import 'package:serverpod_auth_email_server/serverpod_auth_email_server.dart'
34+
as email_account;
35+
36+
/// Endpoint for email-based authentication.
37+
class EmailAccountEndpoint extends email_account.EmailAccountEndpoint {}
38+
```
39+
40+
In this `class` `@override`s could be used to augment the default endpoint implementation.
41+
42+
Next, add the authentication handler to the Serverpod instance.
43+
44+
```dart
45+
import 'package:serverpod_auth_server/serverpod_auth_session_server.dart' as auth_session;
46+
47+
void run(List<String> args) async {
48+
var pod = Serverpod(
49+
args,
50+
Protocol(),
51+
Endpoints(),
52+
authenticationHandler: auth_session.authenticationHandler, // Add this line
53+
);
54+
55+
...
56+
}
57+
```
58+
59+
In order to generate server and client the code for the newly added endpoint, run:
60+
61+
```bash
62+
$ serverpod generate
63+
```
64+
65+
Additionally the database schema will need to be extended to add the new tables for the email accounts. Create a new migration using the `create-migration` command.
66+
67+
```bash
68+
$ serverpod create-migration
69+
```
70+
71+
As the last step, the email authentication package needs to be configured.
72+
For this set the `EmailAccounts.config` from package `serverpod_auth_email_account_server`, which contains the business logic used by the endpoint. This configuration should be added before the `await pod.start();` call. Callbacks need to be provided for at least `sendRegistrationVerificationCode` and `sendPasswordResetVerificationCode`, while the rest can be left to their default values.
73+
74+
<!-- TODO: Should we re-expose the config in order to not require yet another package? -->
75+
76+
```dart
77+
EmailAccounts.config = EmailAccountConfig(
78+
sendRegistrationVerificationCode: (
79+
final session, {
80+
required final email,
81+
required final accountRequestId,
82+
required final verificationCode,
83+
required final transaction,
84+
}) {
85+
// Send out actual email with the verification code
86+
},
87+
sendPasswordResetVerificationCode: (
88+
final session, {
89+
required final email,
90+
required final passwordResetRequestId,
91+
required final transaction,
92+
required final verificationCode,
93+
}) {
94+
// Send out actual email with the verification code
95+
},
96+
);
97+
```
98+
99+
<!-- TODO: Explain deep link vs. "retype code" approach, and when one might want to send the "request ID" -->
100+
101+
<!-- TODO: Mention required password configuration -->
102+
103+
After a restart of the Serverpod the new endpoints will be usable from the client.
104+
105+
### Client setup
106+
107+
<!-- TODO -->
108+
109+
### User consolidation
110+
111+
<!-- TODO: Explain how to connect with other providers -->

‎docs/08-upgrading/06-upgrading-from-serverpod_auth.md

Lines changed: 108 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,108 @@
1+
# Upgrading from `serverpod_auth`
2+
3+
With the release of Serverpod 3.0, the single legacy `serverpod_auth` package was replace with a set of modular packages providing flexible modules for users and profiles, authentication, and session management.
4+
5+
For an existing Serverpod application which makes use of `serverpod_auth` (which still works totally fine with 3.0) to upgrade to the new package, there exists `serverpod_auth_migration` to facilitate moving over all authentication data into the new models.
6+
Once the migration is complete, the legacy `serverpod_auth` module and the `serverpod_auth_migration` module can be removed (which will also remove the then obsolete tables from the database).
7+
8+
Due to the modular approach, each used authentication provider (email, Apple, Google, etc.) needs to be configured individually for the migration.
9+
No matter through which authentication provider(s) a user is migrated, their profile will always be migrated as well (unless the developers opts out of this).
10+
11+
## General timeline
12+
13+
The suggested migration timeline applies to all auth providers.
14+
15+
1. Add and configure the new auth modules for the desired providers
16+
2. Add the migration module and configure each auth provider and set up a background migration job <!-- TODO: Showcase this -->
17+
3. Switch over all clients to use the new authentication endpoints
18+
4. After a sufficient percentage of the userbase has migrated to the new endpoints, disable sign-ups via the legacy package <!-- TODO: Showcase this -->
19+
5. Later on also disable logins and password resets on the `serverpod_auth` APIs
20+
6. Once all users have been migrated (also via the background processes, albeit without passwords) remove the dependency on `serverpod_auth` and `serverpod_auth_migration` and delete all related code
21+
7. The next migration will then also remove obsolete tables
22+
23+
If the Serverpod application stores data with a relation to the `UserInfo` / user ID, this needs to be migrated to the new `UUID` id of the `AuthUser`.
24+
During the migration a mapping, if the user has been migrated, can be looked up via the `MigratedUser` entity. But as this model will be dropped with the removal of the `serverpod_auth_migration` package in step 6, one needs to ensure to also update ones own data to point to the new `AuthUser` IDs.
25+
26+
## UserInfo / User ID
27+
28+
<!-- TODO: Explain how a look up can be made during the transition, but finally any foreign keys need to be migrated.
29+
Depending on the project scale this might be easiest to do "at once", if possible.
30+
We should probably showcase a full example here, and figure out how to integrate that into the migration that will drop the final tables.
31+
32+
Maybe add optional AuthUser relation, and then in the end make it required (while dropping the `serverpod_auth` `UserInfo`)
33+
-->
34+
35+
## Sessions
36+
37+
<!-- TODO: Explain how all default modules use the new `serverpod_auth_session` and thus this only need to be configured once -->
38+
39+
## Migrating Email Authentications
40+
41+
<!-- TODO: The update with the final link -->
42+
Before starting with the email account migration, the email authentication from `serverpod_auth_email` must be [set up as described](06-concepts/11-authentication/01-setup_new.md#email).
43+
44+
Since the password storage format changed between the legacy and new modules, and because we only have access to the plain text password during `login` (when it's sent from the client), there are 2 scenarios of migrating user accounts and the email authentication.
45+
46+
During a login we can verify the incoming credentials, and then migrate the entire account including the password.
47+
In all other cases (e.g. a password reset or a background migration job) we can migrate the user profile and account, but not set its password. The password could be set on a subsequent login (if it matches the one from the legacy module), or in case the user did not log in during the migration phase, they will have to resort to a password reset.
48+
49+
In order to avoid creating duplicate accounts for the "same" user in both the legacy and new system, one needs to ensure that the migration is always called before the new module would attempt any user lookups or creations.
50+
To support this in the new endpoint, which now exists as a subclass in the Serverpod application, the migration methods need to each affected endpoint.
51+
52+
```dart
53+
class EmailAccountEndpointWithMigration
54+
extends email_account.EmailAccountEndpoint {
55+
@override
56+
Future<String> login(
57+
final Session session, {
58+
required final String email,
59+
required final String password,
60+
}) async {
61+
// Add this before the call to `super` in the endpoint subclass
62+
await AuthMigrationEmail.migrateOnLogin(
63+
session,
64+
email: email,
65+
password: password,
66+
);
67+
68+
return super.login(session, email: email, password: password);
69+
}
70+
71+
@override
72+
Future<void> startRegistration(
73+
final Session session, {
74+
required final String email,
75+
required final String password,
76+
}) async {
77+
// Add this before the call to `super` in the endpoint subclass
78+
await AuthMigrationEmail.migrateOnLogin(
79+
session,
80+
email: email,
81+
password: password,
82+
);
83+
84+
return super.startRegistration(session, email: email, password: password);
85+
}
86+
87+
@override
88+
Future<void> startPasswordReset(
89+
final Session session, {
90+
required final String email,
91+
}) async {
92+
// Add this before the call to `super` in the endpoint subclass
93+
await AuthMigrationEmail.migrateWithoutPassword(session, email: email);
94+
95+
return super.startPasswordReset(session, email: email);
96+
}
97+
}
98+
```
99+
100+
After this modification, the endpoint will always attempt a migration first, because then proceeding with the desired request (eg. registering a new account if none exists yet).
101+
102+
The migration works fully out of the box. But in case the existing `UserInfo` should not be moved to a new `serverpod_auth_profile` `UserProfile`, this can be disabled through the `AuthMigrationEmailConfig`.
103+
104+
```dart
105+
AuthMigrationEmail.config = AuthMigrationEmailConfig(
106+
importProfile: false,
107+
);
108+
```

0 commit comments

Comments
 (0)