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.
Before You Begin
- Create an Atlas App Services app.
- 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");
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
.
Credentials 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 Atlas 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);
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. Email/password URLs expire after 30 minutes, so users who do not visit within that period need new emails to confirm their accounts.
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
To reset a user password with App Services, you can either:
- Run a password reset function
- Send a password reset email
To select which of these methods to use in your app, configure the App Services authentication password reset behavior.
Call a Reset Function
If you have defined a backend function to reset the user's password, you pass the user's email address, the new password, and optional Map of custom arguments to EmailPasswordAuthProvider.callResetPasswordFunction().
// 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 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 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 reset the password on the client, your UI should prompt the user to enter a new
password and the token
and tokenId
values. You pass these values to
EmailPasswordAuthProvider.completeResetPassword().
EmailPasswordAuthProvider authProvider = EmailPasswordAuthProvider(app); await authProvider.completeResetPassword( "n3wSt0ngP4ssw0rd!", token, tokenId);
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.