Email/Password Users - Flutter SDK
On this page
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.
Before You Begin
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.
Register a User
Create a new EmailPasswordAuthProvider instance with your
App
instance as the argument.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.
Log in a User
Create an email/password credential by calling Credentials.emailPassword() with the user's email and password.
Pass the generated credential to
app.logIn
.
final emailPwCredentials = Credentials.emailPassword("lisa@example.com", "myStr0ngPassw0rd"); await app.logIn(emailPwCredentials);
Confirm a New User's Email Address
Once you register a new email/password user, you must confirm the email address unless you configure App Services to automatically confirm users.
Custom Confirmation Function
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.
Send a Confirmation Email
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.
Retry User Confirmation
The SDK provides methods to resend user confirmation emails or retry custom confirmation.
Retry a User Confirmation Function
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");
Resend a User Confirmation Email
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");
Reset a User's Password
Resetting a user's password is a multi-step process.
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.
After confirming the user's identity, you can complete the password reset request.
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.
Call a Reset Function
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.
Server-Side Pending Case
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);
Server-Side Success Case
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);
Send Password Reset Email
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.