Skip to content

docs: Document serverpod_auth_email setup and migrating from serverpod_auth to the new provider using serverpod_auth_migration #302

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
wants to merge 1 commit into
base: main
Choose a base branch
from
Draft

docs: Document serverpod_auth_email setup and migrating from serverpod_auth to the new provider using serverpod_auth_migration #302

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
209 changes: 209 additions & 0 deletions docs/06-concepts/11-authentication/01-setup_new.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,209 @@
# Setup

Serverpod comes with built-in support for authentication. It is possible to build a [custom authentication implementation](custom-overrides), but the recommended way to authenticate users is to use one of the `serverpod_auth_*` modules. The modules makes it easy to authenticate with email or social sign-ins and currently supports signing in with email, Google, Apple, and Firebase.

Future versions of the authentication module will include more options. If you write another authentication module, please consider [contributing](/contribute) your code.

![Sign-in with Serverpod](https://github.com/serverpod/serverpod/raw/main/misc/images/sign-in.png)

We provide the following packages of ready-to use authentication providers. They all include a basic user profile courtesy of `serverpod_auth_profile`, and session management through `serverpod_auth_session`.

|Package|Functionality|
|-|-|
|`serverpod_auth_email`|Ready to use email authentication.|
|`serverpod_auth_apple`|Ready to use "Sign in with Apple" authentication.|
|`serverpod_auth_google`|Ready to use "Sing in with Google authentication.|

If you would like the basic authentication offered by these package, but combine them with a different approach to session management or another kind of user profile have [a look at the underlying packages below](#Low-level building blocks).

## Sessions

When using any of the "ready-to-use" authentication providers listed above, session management based on `serverpod_auth_session` is already included.

Just follow any of the individual guides to set the `authenticationHandler` on your `Serverpod` instance.

## Email

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`.

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.


### Server setup

Add the module as a dependency to the server project's `pubspec.yaml`.

```sh
$ dart pub add serverpod_auth_email_server
```

Further it's advisable to depend on `serverpod_auth_session` directly as well, to avoid any lint warnings when using it later.

```sh
$ dart pub add serverpod_auth_session_server
```

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.

For this add an `email_account_endpoint.dart` file to the project:

```dart
import 'package:serverpod_auth_email_server/serverpod_auth_email_server.dart'
as email_account;

/// Endpoint for email-based authentication.
class EmailAccountEndpoint extends email_account.EmailAccountEndpoint {}
```

In this `class` `@override`s could be used to augment the default endpoint implementation.

Next, add the authentication handler to the Serverpod instance.

```dart
import 'package:serverpod_auth_email_server/serverpod_auth_email_server.dart';

void run(List<String> args) async {
var pod = Serverpod(
args,
Protocol(),
Endpoints(),
authenticationHandler: AuthSessions.authenticationHandler, // Add this line
);

...
}
```

In order to generate server and client the code for the newly added endpoint, run:

```bash
$ serverpod generate
```

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.

```bash
$ serverpod create-migration
```

As the last step, the email authentication package needs to be configured.
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.

```dart
import 'package:serverpod_auth_email_server/serverpod_auth_email_server.dart';

EmailAccounts.config = EmailAccountConfig(
sendRegistrationVerificationCode: (
final session, {
required final email,
required final accountRequestId,
required final verificationCode,
required final transaction,
}) {
// Send out actual email with the verification code
},
sendPasswordResetVerificationCode: (
final session, {
required final email,
required final passwordResetRequestId,
required final transaction,
required final verificationCode,
}) {
// Send out actual email with the verification code
},
);
```

<!-- TODO: Explain the need for an email provider -->

<!-- TODO: Explain deep link vs. "retype code" approach, and when one might want to send the "request ID" -->

Additionally you need to update the `passwords.yaml` file to include secrets for both `serverpod_auth_session_sessionKeyHashPepper` and `serverpod_auth_email_account_passwordHashPepper`.
These should be random and at least 10 characters long. These pepper values must not be changed after the initial deployment of the server, as they are baked into every session key and stored password, and thus a roatation would invalidate previously created credentials.

After a restart of the Serverpod the new endpoints will be usable from the client.

### Client setup


## App setup

<!-- TODO: Update fully -->

First, add dependencies to your app's `pubspec.yaml` file for the methods of signing in that you want to support.

```yaml
dependencies:
flutter:
sdk: flutter
serverpod_flutter: ^3.0.0
auth_example_client:
path: ../auth_example_client

serverpod_auth_session_flutter: ^3.0.0
```

Next, you need to set up a `SessionManager`, which keeps track of the user's state. It will also handle the authentication keys passed to the client from the server, upload user profile images, etc.

```dart
import 'package:serverpod_auth_session_flutter/serverpod_auth_session_flutter.dart' show SessionManager;

late SessionManager sessionManager;
late Client client;

void main() async {
// Need to call this as we are using Flutter bindings before runApp is called.
WidgetsFlutterBinding.ensureInitialized();

// The session manager keeps track of the signed-in state of the user. You
// can query it to see if the user is currently signed in and get information
// about the user.
sessionManager = SessionManager(
caller: client.modules.auth,
);
await sessionManager.init();

// The android emulator does not have access to the localhost of the machine.
// const ipAddress = '10.0.2.2'; // Android emulator ip for the host

// On a real device replace the ipAddress with the IP address of your computer.
const ipAddress = 'localhost';

// Sets up a singleton client object that can be used to talk to the server from
// anywhere in our app. The client is generated from your server code.
// The client is set up to connect to a Serverpod running on a local server on
// the default port. You will need to modify this to connect to staging or
// production servers.
client = Client(
'http://$ipAddress:8080/',
authenticationKeyManager: sessionManager,
)..connectivityMonitor = FlutterConnectivityMonitor();


runApp(MyApp());
}
```

### User consolidation

<!-- TODO: Explain how to connect with other providers -->

## Low-level building blocks

### Session Management

|Package|Functionality|
|-|-|
|`serverpod_auth_session`|Database-backed session handling, with flexible configuration per session.|
|`serverpod_auth_jwt`|JWT-based session implemented, which can also generate access token with public/private key cryptography to use with 3rd party services.|

### Authentication

The following package provide the core authentication functionality, but without providing a default `Endpoint` base implementation. Thus they can be combined with another session package and include further modification, like for example a custom user profile.

|Package|Functionality|
|-|-|
|`serverpod_auth_email_account`|Basic email authentication.|
|`serverpod_auth_apple_account`|Basic "Sign in with Apple" authentication.|
|`serverpod_auth_google_account`|Basic "Sing in with Google authentication.|

108 changes: 108 additions & 0 deletions docs/08-upgrading/06-upgrading-from-serverpod_auth.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,108 @@
# Upgrading from `serverpod_auth`

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.

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.
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).

Due to the modular approach, each used authentication provider (email, Apple, Google, etc.) needs to be configured individually for the migration.
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).

## General timeline

The suggested migration timeline applies to all auth providers.

1. Add and configure the new auth modules for the desired providers
2. Add the migration module and configure each auth provider and set up a background migration job <!-- TODO: Showcase this -->
3. Switch over all clients to use the new authentication endpoints
4. After a sufficient percentage of the userbase has migrated to the new endpoints, disable sign-ups via the legacy package <!-- TODO: Showcase this -->
5. Later on also disable logins and password resets on the `serverpod_auth` APIs
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
7. The next migration will then also remove obsolete tables

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`.
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.

## UserInfo / User ID

<!-- TODO: Explain how a look up can be made during the transition, but finally any foreign keys need to be migrated.
Depending on the project scale this might be easiest to do "at once", if possible.
We should probably showcase a full example here, and figure out how to integrate that into the migration that will drop the final tables.

Maybe add optional AuthUser relation, and then in the end make it required (while dropping the `serverpod_auth` `UserInfo`)
-->

## Sessions

<!-- TODO: Explain how all default modules use the new `serverpod_auth_session` and thus this only need to be configured once -->

## Migrating Email Authentications

<!-- TODO: The update with the final link -->
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).

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.

During a login we can verify the incoming credentials, and then migrate the entire account including the password.
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.

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.
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.

```dart
class EmailAccountEndpointWithMigration
extends email_account.EmailAccountEndpoint {
@override
Future<String> login(
final Session session, {
required final String email,
required final String password,
}) async {
// Add this before the call to `super` in the endpoint subclass
await AuthMigrationEmail.migrateOnLogin(
session,
email: email,
password: password,
);

return super.login(session, email: email, password: password);
}

@override
Future<void> startRegistration(
final Session session, {
required final String email,
required final String password,
}) async {
// Add this before the call to `super` in the endpoint subclass
await AuthMigrationEmail.migrateOnLogin(
session,
email: email,
password: password,
);

return super.startRegistration(session, email: email, password: password);
}

@override
Future<void> startPasswordReset(
final Session session, {
required final String email,
}) async {
// Add this before the call to `super` in the endpoint subclass
await AuthMigrationEmail.migrateWithoutPassword(session, email: email);

return super.startPasswordReset(session, email: email);
}
}
```

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).

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`.

```dart
AuthMigrationEmail.config = AuthMigrationEmailConfig(
importProfile: false,
);
```
Loading