Docs Menu

Docs HomeAtlas Device SDK

Manage Email/Password Users - .NET SDK

On this page

  • Overview
  • Register a New User Account
  • Confirm a New User's Email Address
  • Resend a Confirmation Email
  • Retry a User Confirmation Function
  • Reset a User's Password
  • Send a Password Reset Email
  • Run a Password Reset Function

If you have enabled the email/password provider in your App, you can register a new account, confirm an email address, and reset a user's password in the client code.

To register a new user, pass a user-provided email and password to the RegisterUserAsync() method:

await app.EmailPasswordAuth.RegisterUserAsync(userEmail, "sekrit");

To confirm a newly-created user, pass a confirmation token and tokenId to the ConfirmUserAsync() mehtod.

Note

Use Deep Links in Mobile Apps

Mobile applications can handle email confirmation directly in the app by configuring deep linking in Android, universal links in iOS, and/or URI handlers for the Universal Windows Platform (UWP).

await app.EmailPasswordAuth.ConfirmUserAsync("<token>", "<token-id>");

To resend a confirmation email, call the ResendConfirmationEmailAsync() method with the user's email address.

await app.EmailPasswordAuth.ResendConfirmationEmailAsync("<userEmail>");

To resend a confirmation email using a custom function, call the RetryCustomConfirmationAsync() method with the user's email address.

await app.EmailPasswordAuth.RetryCustomConfirmationAsync("<userEmail>");

For more information, refer to Run a Confirmation Function in the App Services documentation.

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.

Select your preferred password reset method by going to:

  1. Your Atlas App Services App

  2. Authentication

  3. Authentication Providers

  4. Email/Password - and press the EDIT button

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

To begin the password reset process, call SendPasswordResetEmailAsync() with the user's email. App Services sends an email to the user that contains a unique URL. The user must visit this URL within 30 minutes to confirm the reset.

await app.EmailPasswordAuth.SendResetPasswordEmailAsync(userEmail);

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 ResetPasswordAsync():

await app.EmailPasswordAuth.ResetPasswordAsync(
myNewPassword, "<token>", "<token-id>");

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.

Note

To access the token and tokenId values sent in the password reset email, you can use an Android deep link or iOS universal link.

When you configure your app to run a password reset function, you define the function that should run when you call CallResetPasswordFunctionAsync() from the SDK. 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. You could also 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 Exception by the SDK. The SDK CallResetPasswordFunctionAsync() 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 CallResetPasswordFunctionAsync(), so your client app must implement its own logic to handle a pending status.

await app.EmailPasswordAuth.CallResetPasswordFunctionAsync(
userEmail, myNewPassword);

Your server-side function might send an email using a custom email provider. You could also use SMS or some other service to confirm the user's identity.

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 ResetPasswordAsync() to complete the password reset flow.

await app.EmailPasswordAuth.ResetPasswordAsync(
myNewPassword, "<token>", "<token-id>");

Note

To access the token and tokenId values sent from a custom password reset function, you can use an Android deep link or iOS universal link.

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 CallResetPasswordFunctionAsync(), 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.

await app.EmailPasswordAuth.CallResetPasswordFunctionAsync(
userEmail, myNewPassword,
"<security-question-1-answer>",
"<security-question-2-answer>");
←  User Metadata - .NET SDKMulti-User Applications - .NET SDK →