Docs Menu
Docs Home
/ /
Atlas Device SDKs
/ /

Email/Password Users - Flutter SDK

On this page

  • Before You Begin
  • Register a User
  • Log in a User
  • Confirm a New User's Email Address
  • Custom Confirmation Function
  • Send a Confirmation Email
  • Retry User Confirmation
  • Retry a User Confirmation Function
  • Resend a User Confirmation Email
  • Reset a User's Password
  • Call a Reset Function
  • Send Password Reset Email

With Atlas App Services's email/password authentication provider, you can register a new account, confirm an email address, and reset a user's password from client code.

Warning

Version 0.5.0 Breaking Change

The Realm Flutter SDK version 0.5.0 includes a breaking change to email/password authentication. The change fixes a bug where the unicode null character \u0000 was appended to the end of passwords in previous versions of the SDK.

As a result, once you upgrade your application to use version >0.5.0, users must either reset their password or create a new account. Previous passwords will no longer work after updating to >0.5.0.

  1. Create an App Services App.

  2. Before you begin writing client code, you should understand the different email/password authentication flows that App Services provides, and configure the backend implementation for your application. App Services has a variety of ways to confirm email/password user identities and reset user passwords. Learn more about, enable, and configure App Services email/password authentication.

  1. Create a new EmailPasswordAuthProvider instance with your App instance as the argument.

  2. Invoke EmailPasswordAuthProvider.registerUser(), passing the user's email and password as arguments.

EmailPasswordAuthProvider authProvider = EmailPasswordAuthProvider(app);
await authProvider.registerUser("lisa@example.com", "myStr0ngPassw0rd");

Note

Registering a user does not also log that user in. You must log the user in separately.

  1. Create an email/password credential by calling Credentials.emailPassword() with the user's email and password.

  2. Pass the generated credential to app.logIn.

final emailPwCredentials =
Credentials.emailPassword("lisa@example.com", "myStr0ngPassw0rd");
await app.logIn(emailPwCredentials);

Once you register a new email/password user, you must confirm the email address unless you configure App Services to automatically confirm users.

If you configure App Services to use a custom function for email address confirmation, handle user confirmation with the logic of your custom function's flow. The App Services backend invokes the custom function when the user registers.

You only need to send a confirmation email if you configure App Services to handle user confirmation with an email.

To confirm a newly-created user, pass a confirmation token and tokenId to EmailPasswordAuthProvider.confirmUser(). These are included in the email sent to the user's email address when they register.

EmailPasswordAuthProvider authProvider = EmailPasswordAuthProvider(app);
await authProvider.confirmUser(token, tokenId);

Note

Use Deep Links in Flutter Apps

Mobile applications can handle email confirmation directly in the app by configuring deep linking.

The SDK provides methods to resend user confirmation emails or retry custom confirmation.

Use this user confirmation method if you've configured the App Services backend to retry a custom user confirmation function.

To retry a confirmation function, pass the email used in sign up to EmailPasswordAuthProvider.retryCustomConfirmationFunction().

EmailPasswordAuthProvider authProvider = EmailPasswordAuthProvider(app);
await authProvider.retryCustomConfirmationFunction("lisa@example.com");

Use this user confirmation method if you've configured the App Services backend to resend a confirmation email. The confirmation tokens in each URL expire after 30 minutes. If a user does not follow the link and confirm within that period, they must request a new confirmation email.

To resend a confirmation email, pass the email used in sign up to EmailPasswordAuthProvider.resendUserConfirmation().

EmailPasswordAuthProvider authProvider = EmailPasswordAuthProvider(app);
await authProvider.resendUserConfirmation("lisa@example.com");

Resetting a user's password is a multi-step process.

  1. In your client app, you provide a UI for the user to reset their password. Your App Services App can then send an email or run a custom function to confirm the user's identity.

  2. After confirming the user's identity, you can complete the password reset request.

  3. After the password reset is complete, the user can log in using the new password.

To select which of these methods to use in your app, configure the App Services authentication password reset behavior.

When you configure your app to run a password reset function, you define the function that should run when you call EmailPasswordAuthProvider.callResetPasswordFunction(). This function can take a username, a password, and any number of additional arguments. You can use these arguments to specify details like security question answers or other challenges that the user should pass to successfully complete a password reset.

You might prefer to use a custom password reset function when you want to define your own password reset flows. For example, you might send a custom password reset email from a specific domain. Or you might use a service other than email to confirm the user's identity.

On the App Services side, you define the custom password reset function that runs when you call this method. That function can return one of three possible statuses:

  • fail

  • pending

  • success

A fail status is treated as an error by the SDK. The SDK callResetPasswordFunction() does not take return values, so it does not return a pending or success status to the client.

Your App Services password reset function may return pending if you want the user to take some additional step to confirm their identity. However, that return value is not passed to the SDK's callResetPasswordFunction(), so your client app must implement its own logic to handle a pending status.

Your server-side function might send an email using a custom email provider. Or you may use SMS to confirm the user's identity via text message.

You have access to a token and tokenId in the App Services password reset function context. If you pass this information from your App Services password reset function, you can pass these values back to your app using platform-specific deep linking or universal links. Then, your client application can call EmailPasswordAuthProvider.completeResetPassword to complete the password reset flow.

// The password reset function takes any number of
// arguments.
final args = [];
EmailPasswordAuthProvider authProvider = EmailPasswordAuthProvider(app);
await authProvider.callResetPasswordFunction(
"lisa@example.com", "n3wSt0ngP4ssw0rd!",
functionArgs: args);
// ... Later...
// Token and tokenId are parameters you can access
// in the App Services function context. You could send
// this to the user via email, SMS, or some other method.
final token = "someToken";
final tokenId = "someTokenId";
await authProvider.completeResetPassword(
"n3wSt0ngP4ssw0rd!", token, tokenId);

If your App Services password reset function does additional validation within the function, or if you have validated the user's identity prior to attempting to reset the password, you may configure the App Services function to return success. However, that return value is not passed to the SDK's callResetPasswordFunction(), so your client app must implement its own logic to handle a success status.

Calling the function in this example performs the entire password reset process.

// The password reset function takes any number of
// arguments. You might ask the user to provide answers to
// security questions, for example, to verify the user
// should be able to complete the password reset.
final args = [
"Snowball II",
"Springfield Elementary School",
"Bouvier"
];
EmailPasswordAuthProvider authProvider = EmailPasswordAuthProvider(app);
await authProvider.callResetPasswordFunction(
"lisa@example.com", "n3wSt0ngP4ssw0rd!",
functionArgs: args);

To send password reset emails to confirm the user's identity, you must configure your App to send a password reset email.

To send a password reset email, pass the email used in sign up to EmailPasswordAuthProvider.resetPassword().

EmailPasswordAuthProvider authProvider = EmailPasswordAuthProvider(app);
await authProvider.resetPassword("lisa@example.com");

Password reset emails contain a URL encoded with two values, token and tokenId. To complete the password reset flow, you can reset the user's password on the client or by calling a custom function on the backend. To use the SDK to complete the password reset, pass these values to EmailPasswordAuthProvider.completeResetPassword().

If the user does not visit the URL from the password reset email within 30 minutes, the token and tokenId expire. You must begin the password reset process again.

EmailPasswordAuthProvider authProvider = EmailPasswordAuthProvider(app);
await authProvider.completeResetPassword(
"n3wSt0ngP4ssw0rd!", token, tokenId);

Note

To access the token and tokenId values sent in the password reset email, you can use a custom password reset email containing a deep link.

← Authenticate Users - Flutter SDK