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..974dec19 --- /dev/null +++ b/docs/06-concepts/11-authentication/01-getting-started.md @@ -0,0 +1,92 @@ +# Setup + +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. + +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. 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 you get out of the box + +Most of the setup is already done for you. A new project comes with: + +- 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. + +The only thing left is to show a sign-in screen in your app. + +## Show 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`. + +First, import the screen: + +```dart +import 'screens/sign_in_screen.dart'; +``` + +Then show it as the home screen. Comment out the existing line and uncomment the block below it, so it reads: + +```dart +body: SignInScreen( + child: GreetingsScreen( + onSignOut: () async { + await client.auth.signOutDevice(); + }, + ), +), +``` + +That is the only change your app needs. + +## Start the database + +From the server directory, start the database and apply the migration that creates the sign-in tables: + +```bash +cd my_project_server +docker compose up --build --detach +dart run bin/main.dart --apply-migrations +``` + +This also starts the server. + +## Run the app + +With the server running, start your app: + +```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. +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 you are signed in, the app shows your content with a sign-out button. + +## Send real emails + +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 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). 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.