From b014210fb211efc3803edbdc412cf3c0bc6c0f6d Mon Sep 17 00:00:00 2001 From: Chiziaruhoma Ogbonda Date: Fri, 29 May 2026 11:04:29 +0100 Subject: [PATCH 1/2] docs: Add getting started guide for email authentication setup --- .../11-authentication/01-getting-started.md | 93 +++++++++++++++++++ .../06-concepts/11-authentication/01-setup.md | 8 +- 2 files changed, 99 insertions(+), 2 deletions(-) create mode 100644 docs/06-concepts/11-authentication/01-getting-started.md diff --git a/docs/06-concepts/11-authentication/01-getting-started.md b/docs/06-concepts/11-authentication/01-getting-started.md new file mode 100644 index 00000000..ef7c6766 --- /dev/null +++ b/docs/06-concepts/11-authentication/01-getting-started.md @@ -0,0 +1,93 @@ +# Setup + +New projects created with `serverpod create` already include email authentication, wired up on both the server and the app. This guide shows how to turn it on, run it locally, and test the full sign-in flow. + +If you are adding the auth module to an older project that does not include this setup, follow [Migrate to the new auth module](./setup) instead. + +![Sign-in with Serverpod](/img/authentication/sign-in-widget-device.png) + +## Prerequisites + +- A project created with `serverpod create` on Serverpod 3.4 or later. These templates include the email auth setup. If you are upgrading an older project, follow [Migrate to the new auth module](./setup) to add it manually. +- Docker running, so the server can start its database. +- The Flutter SDK installed, to run the app. + +## What the template already includes + +When you create a project with `serverpod create`, the default server template configures email authentication for you: + +- The server (`my_project_server/lib/server.dart`) initializes authentication services with a JWT token manager and the email identity provider. +- The email and JWT refresh endpoints are already created under `my_project_server/lib/src/auth/`. +- The auth dependencies are added to the server, client, and app packages. +- The required secrets (`emailSecretHashPepper`, `jwtHmacSha512PrivateKey`, and `jwtRefreshTokenHashPepper`) are generated in `my_project_server/config/passwords.yaml`. +- An initial database migration that creates the authentication tables is included under `my_project_server/migrations/`. + +On the app side, `my_project_flutter/lib/main.dart` already creates the client with a `FlutterAuthSessionManager` and calls `client.auth.initialize()` on startup. The only thing left to do is show the sign-in UI. + +:::info +For local testing, the template logs verification codes to the server console instead of sending real emails, so you can run through the entire flow without connecting a mail service. See [Send real emails](#send-real-emails) when you are ready for production. +::: + +## Enable the sign-in screen + +The Flutter template ships a `SignInScreen` widget in `my_project_flutter/lib/screens/sign_in_screen.dart`. It shows the `SignInWidget` while the user is signed out, and your app's content once they sign in. It is referenced in `main.dart` but commented out by default. + +Open `my_project_flutter/lib/main.dart` and add the import, since `main.dart` does not reference the screen yet: + +```dart +import 'screens/sign_in_screen.dart'; +``` + +Then, in `MyHomePage`, comment out the plain `GreetingsScreen` body and uncomment the `SignInScreen` block so it reads: + +```dart +body: SignInScreen( + child: GreetingsScreen( + onSignOut: () async { + await client.auth.signOutDevice(); + }, + ), +), +``` + +That is the only change needed in the app. + +## Start the database and apply migrations + +From the server directory, start the database and apply the included migration to create the authentication tables: + +```bash +cd my_project_server +docker compose up --build --detach +dart run bin/main.dart --apply-migrations +``` + +This applies the migration and starts the server. + +## Run the app and test the flow + +With the server running, start the Flutter app from the app directory: + +```bash +cd my_project_flutter +flutter run +``` + +The app opens on the sign-in screen. To create an account: + +1. Choose to create a new account, enter your email, and continue to start registration. +2. Find the verification code in the server console. The template logs it instead of emailing it, with a line like `[EmailIdp] Registration code (you@example.com): 12345678`. +3. Enter the code, then set a password to complete registration. + +Once authenticated, the app shows your content with a sign-out button. + +## Send real emails + +The template logs verification codes so you can test locally. In production, send them through an email service instead. Connect your mail service in the `sendRegistrationVerificationCode` and `sendPasswordResetVerificationCode` callbacks in `my_project_server/lib/server.dart`. See the [Email provider setup](./providers/email/setup) for details on configuring an SMTP service. + +## Next steps + +- Customize the sign-in UI or build your own. See [Customizing the UI](./providers/email/customizing-the-ui). +- Configure password requirements, verification codes, and rate limiting. See [Email configuration](./providers/email/configuration). +- Restrict endpoints to signed-in users. See [The basics](./basics#requiring-authentication-on-endpoints). +- Add more sign-in options, such as Google or Apple. See [Identity providers configuration](./setup#identity-providers-configuration). diff --git a/docs/06-concepts/11-authentication/01-setup.md b/docs/06-concepts/11-authentication/01-setup.md index 4aa9cbe4..e710a425 100644 --- a/docs/06-concepts/11-authentication/01-setup.md +++ b/docs/06-concepts/11-authentication/01-setup.md @@ -1,6 +1,10 @@ -# Setup +# Migrate to the new auth module -Serverpod comes with built-in user management and authentication. It is possible to build a [custom authentication implementation](custom-overrides), but the recommended way to authenticate users is to use the `serverpod_auth_idp` module. The module makes it easy to authenticate with email, social sign-ins and more. +New projects created with `serverpod create` (Serverpod 3.4 and later) already include the auth module, so there is nothing to set up. To enable it, follow [Setup](./getting-started). + +This guide is for existing projects that need to add the `serverpod_auth_idp` module manually, such as when upgrading from an older Serverpod version. It covers the server, client, and app. + +Serverpod comes with built-in user management and authentication. It is possible to build a [custom authentication implementation](custom-overrides), but the recommended way to authenticate users is to use the `serverpod_auth_idp` module. The module makes it easy to authenticate with email, social sign-ins, and more. The list of identity providers is continuously growing and new providers are added as they are developed. If you want to contribute a new provider, please consider [contributing](/contribute) your code. See the [identity providers configuration](#identity-providers-configuration) section for details on all available providers. From c6c1b313b45742823dddce94ce8afc4478daff10 Mon Sep 17 00:00:00 2001 From: Chiziaruhoma Ogbonda Date: Fri, 29 May 2026 11:11:16 +0100 Subject: [PATCH 2/2] docs: Revise getting started guide for email authentication, clarifying setup steps and improving readability --- .../11-authentication/01-getting-started.md | 71 +++++++++---------- 1 file changed, 35 insertions(+), 36 deletions(-) diff --git a/docs/06-concepts/11-authentication/01-getting-started.md b/docs/06-concepts/11-authentication/01-getting-started.md index ef7c6766..974dec19 100644 --- a/docs/06-concepts/11-authentication/01-getting-started.md +++ b/docs/06-concepts/11-authentication/01-getting-started.md @@ -1,44 +1,38 @@ # Setup -New projects created with `serverpod create` already include email authentication, wired up on both the server and the app. This guide shows how to turn it on, run it locally, and test the full sign-in flow. +When you create a project with `serverpod create`, email sign-in is already built in. The server is configured, the database is ready, and your app is connected to it. You only need to turn on the sign-in screen and run the app. -If you are adding the auth module to an older project that does not include this setup, follow [Migrate to the new auth module](./setup) instead. +This guide walks you through that, then shows how to test signing up and signing in. ![Sign-in with Serverpod](/img/authentication/sign-in-widget-device.png) ## Prerequisites -- A project created with `serverpod create` on Serverpod 3.4 or later. These templates include the email auth setup. If you are upgrading an older project, follow [Migrate to the new auth module](./setup) to add it manually. -- Docker running, so the server can start its database. -- The Flutter SDK installed, to run the app. +- A project created with `serverpod create` on Serverpod 3.4 or later. If you are upgrading an older project, follow [Migrate to the new auth module](./setup) first to add authentication. +- Docker installed and running, so the server can start its database. +- The Flutter SDK installed, so you can run the app. -## What the template already includes +## What you get out of the box -When you create a project with `serverpod create`, the default server template configures email authentication for you: +Most of the setup is already done for you. A new project comes with: -- The server (`my_project_server/lib/server.dart`) initializes authentication services with a JWT token manager and the email identity provider. -- The email and JWT refresh endpoints are already created under `my_project_server/lib/src/auth/`. -- The auth dependencies are added to the server, client, and app packages. -- The required secrets (`emailSecretHashPepper`, `jwtHmacSha512PrivateKey`, and `jwtRefreshTokenHashPepper`) are generated in `my_project_server/config/passwords.yaml`. -- An initial database migration that creates the authentication tables is included under `my_project_server/migrations/`. +- The server configured for email sign-in. +- The user and sign-in database tables, ready to apply as a migration. +- Your app connected to the server and tracking who is signed in. -On the app side, `my_project_flutter/lib/main.dart` already creates the client with a `FlutterAuthSessionManager` and calls `client.auth.initialize()` on startup. The only thing left to do is show the sign-in UI. +The only thing left is to show a sign-in screen in your app. -:::info -For local testing, the template logs verification codes to the server console instead of sending real emails, so you can run through the entire flow without connecting a mail service. See [Send real emails](#send-real-emails) when you are ready for production. -::: +## Show the sign-in screen -## Enable the sign-in screen +Your app already includes a sign-in screen. It is just turned off by default. Turn it on with two small edits to your app's `main.dart`. -The Flutter template ships a `SignInScreen` widget in `my_project_flutter/lib/screens/sign_in_screen.dart`. It shows the `SignInWidget` while the user is signed out, and your app's content once they sign in. It is referenced in `main.dart` but commented out by default. - -Open `my_project_flutter/lib/main.dart` and add the import, since `main.dart` does not reference the screen yet: +First, import the screen: ```dart import 'screens/sign_in_screen.dart'; ``` -Then, in `MyHomePage`, comment out the plain `GreetingsScreen` body and uncomment the `SignInScreen` block so it reads: +Then show it as the home screen. Comment out the existing line and uncomment the block below it, so it reads: ```dart body: SignInScreen( @@ -50,11 +44,11 @@ body: SignInScreen( ), ``` -That is the only change needed in the app. +That is the only change your app needs. -## Start the database and apply migrations +## Start the database -From the server directory, start the database and apply the included migration to create the authentication tables: +From the server directory, start the database and apply the migration that creates the sign-in tables: ```bash cd my_project_server @@ -62,11 +56,11 @@ docker compose up --build --detach dart run bin/main.dart --apply-migrations ``` -This applies the migration and starts the server. +This also starts the server. -## Run the app and test the flow +## Run the app -With the server running, start the Flutter app from the app directory: +With the server running, start your app: ```bash cd my_project_flutter @@ -75,19 +69,24 @@ flutter run The app opens on the sign-in screen. To create an account: -1. Choose to create a new account, enter your email, and continue to start registration. -2. Find the verification code in the server console. The template logs it instead of emailing it, with a line like `[EmailIdp] Registration code (you@example.com): 12345678`. -3. Enter the code, then set a password to complete registration. +1. Choose to create a new account, enter your email, and continue. +2. Look in the server console for the verification code. While testing, it is logged instead of emailed: + + ```text + [EmailIdp] Registration code (you@example.com): 12345678 + ``` + +3. Enter the code, then set a password to finish. -Once authenticated, the app shows your content with a sign-out button. +Once you are signed in, the app shows your content with a sign-out button. ## Send real emails -The template logs verification codes so you can test locally. In production, send them through an email service instead. Connect your mail service in the `sendRegistrationVerificationCode` and `sendPasswordResetVerificationCode` callbacks in `my_project_server/lib/server.dart`. See the [Email provider setup](./providers/email/setup) for details on configuring an SMTP service. +While testing, verification codes are printed to the server console, so you do not need an email service to try the flow. In production, you send them through an email service instead. See [Email provider setup](./providers/email/setup) to connect one. ## Next steps -- Customize the sign-in UI or build your own. See [Customizing the UI](./providers/email/customizing-the-ui). -- Configure password requirements, verification codes, and rate limiting. See [Email configuration](./providers/email/configuration). -- Restrict endpoints to signed-in users. See [The basics](./basics#requiring-authentication-on-endpoints). -- Add more sign-in options, such as Google or Apple. See [Identity providers configuration](./setup#identity-providers-configuration). +- Customize the sign-in screen or build your own. See [Customizing the UI](./providers/email/customizing-the-ui). +- Change password rules, code length, and rate limits. See [Email configuration](./providers/email/configuration). +- Require sign-in on your endpoints. See [The basics](./basics#requiring-authentication-on-endpoints). +- Add more sign-in options, like Google or Apple. See [Identity providers configuration](./setup#identity-providers-configuration).