Setup

To properly configure Sign in with Email, you must connect your Serverpod to an external service that can send the emails. One convenient option is the mailer package, which can send emails through any SMTP service. Most email providers, such as Resend, Sendgrid or Mandrill, support SMTP.

caution

You need to install the auth module before you continue, see Setup.

Server-side configuration

In your main server.dart file, configure the email identity provider using the EmailIdpConfig object and add it to your pod.initializeAuthServices() configuration:

import 'package:serverpod/serverpod.dart';
import 'package:serverpod_auth_idp_server/core.dart';
import 'package:serverpod_auth_idp_server/providers/email.dart';

void run(List<String> args) async {
  final pod = Serverpod(
    args,
    Protocol(),
    Endpoints(),
  );

  pod.initializeAuthServices(
    tokenManagerBuilders: [
      JwtConfigFromPasswords(),
    ],
    identityProviderBuilders: [
      // Configure the Email Identity Provider
      // This is the basic configuration for the Email IDP to work.
      EmailIdpConfig(
        // Secret pepper to hash the password and verification code.
        secretHashPepper: pod.getPassword('emailSecretHashPepper')!,
        // Callback to send the registration verification code to the user.
        sendRegistrationVerificationCode: _sendRegistrationCode,
        // Callback to send the password reset verification code to the user.
        sendPasswordResetVerificationCode: _sendPasswordResetCode,
      ),
    ],
  );

  await pod.start();
}

void _sendRegistrationCode(
  Session session, {
  required String email,
  required UuidValue accountRequestId,
  required String verificationCode,
  required Transaction? transaction,
}) {
  // NOTE: Here you call your mail service to send the verification code to
  // the user. For testing, we will just log the verification code.
  session.log('[EmailIDP] Registration code ($email): $verificationCode');
}

void _sendPasswordResetCode(
  Session session, {
  required String email,
  required UuidValue passwordResetRequestId,
  required String verificationCode,
  required Transaction? transaction,
}) {
  // NOTE: Here you call your mail service to send the verification code to
  // the user. For testing, we will just log the verification code.
  session.log('[EmailIDP] Password reset code ($email): $verificationCode');
}

Then, extend the abstract endpoint to expose it on the server:

import 'package:serverpod_auth_idp_server/providers/email.dart';

class EmailIdpEndpoint extends EmailIdpBaseEndpoint {}

Then, run serverpod generate to generate the client code and create a migration to initialize the database for the provider. More detailed instructions can be found in the general identity providers setup section.

Basic configuration options

• secretHashPepper: Required. A secret pepper used for hashing passwords and verification codes. Must be at least 10 characters long, but the recommended pepper length is 32 bytes.
• sendRegistrationVerificationCode: A callback that will be called to send the registration verification code to the user. Here you should call the email sending service to send the verification code to the user.
• sendPasswordResetVerificationCode: A callback that will be called to send the password reset verification code to the user. Here you should call the email sending service to send the verification code to the user.

For more details on configuration options, such as customizing password requirements, verification code generation, rate limiting, and more, see the configuration section.

tip

If you are using the config/passwords.yaml file or environment variables, you can use the EmailIdpConfigFromPasswords constructor to automatically load the secret pepper. It will expect the emailSecretHashPepper key or the SERVERPOD_PASSWORD_emailSecretHashPepper environment variable to be set with the secret pepper value.

Client-side configuration

If you have configured the SignInWidget as described in the setup section, the Email identity provider will be automatically detected and displayed in the sign-in widget.

You can also use the EmailSignInWidget to include the email authentication flow in your own custom UI.

import 'package:serverpod_auth_idp_flutter/serverpod_auth_idp_flutter.dart';

EmailSignInWidget(
  client: client,
  onAuthenticated: () {
    // Navigate to home screen or update UI
    Navigator.of(context).pushReplacement(
      MaterialPageRoute(builder: (_) => HomePage()),
    );
  },
  onError: (error) {
    // Handle errors
    ScaffoldMessenger.of(context).showSnackBar(
      SnackBar(content: Text('Error: $error')),
    );
  },
)

The widget automatically handles:

• Login with email and password.
• Registration with terms acceptance and email verification.
• Password reset flow with email verification.
• Navigation between screens.

For details on how to display the email authentication UI in your Flutter app, see the customizing the UI section.