Email/Password Authentication

New User Account Status

A user account can be in one of 2 states: Pending and Confirmed.

When the confirmation process is started, Atlas App Services creates a user account and sets the status to Pending Confirmation. In this state, the user cannot login. Because the email address is now associated with a user account, any attempt to re-register the same email will fail.

With the account in the pending state, the user must confirm their account before logging in. When the user confirms their account, Atlas App Services sets the status to Confirmed and the user can log in.

If you are automatically confirming users, the account is created with the status set to Confirmed and the user can log on immediately after registering.

You can view a list of pending user accounts in the UI or via the App Services APIs:

Send a Confirmation Email

With this confirmation method, users must respond to an email upon registration. The email contains a link to a confirmation URL. The user must visit this link within 30 minutes to confirm that they control the email address.

Configure the following settings to have App Services automatically send a confirmation email:

• Email Confirmation URL: the base of the URL included in every confirmation email. App Services appends a unique token and tokenId to this URL. These serve as query parameters to create a unique link for every confirmation. To confirm the user, first extract these query parameters from the user's unique URL. Then, pass the token and tokenId to the Client SDK's confirmUser function.

  Mobile applications can handle email confirmation directly in the app. To do this, configure deep linking in Android or universal links in iOS.

• Email Confirmation Subject: the subject line for the email that App Services sends. This value is optional if omitted, App Services uses a default subject line instead. Custom email confirmation subjects can contain a maximum of 256 characters.

Run a Confirmation Function

You can Run a Confirmation Function when a new user registers. App Services passes a confirmation token, a token ID, and the user's email to the function that you create. Your function then performs the logic you need to confirm the user, and then returns one of the following result objects, which are explained in more detail below:

• { status: 'success' }

• { status: 'fail' }

• { status: 'pending' }

Within the function, you define custom logic to confirm users. For example, your function might:

• Send custom confirmation emails from a specific domain. Send these with a particular template using an external service.

• Read user permissions from a collection in MongoDB Atlas or an external REST service.

• Send confirmation messages through a service other than email, such as SMS.

The custom confirmation function signature has one parameter. It is an object that contains user data and confirmation tokens. These fields are:

The custom user confirmation function returns an object with a status field. The following table describes the potential values of this field:

The following is an example of a user confirmation function that:

1. Checks that the email provided is a valid email.

2. Confirms that the given email address has access to a particular service.

3. Sends an SMS message to the user.

4. If the message is sent successfully, informs Atlas App Services to create a new account with a Pending status.

exports = ({ token, tokenId, username }) => {
   // Validate the username
   const isValidEmail = myCustomValidatorService.validate(username);
   // Check if the user has access to this service
   const isPrivileged =
      myCustomAuthorizationService.hasAccess(username)
   // Send a message to the user so that they can confirm themselves
   const msgSendSuccessful = isValidEmail && isPrivileged
      && mySmsService.send(username, token, tokenId)
   if ( msgSendSuccessful ) {
      return { status: 'pending' };
   } else {
      return { status: 'fail' };
   }
}

Unless the custom function automatically confirms the user, you must provide a means for the user to complete the confirmation process after the function fires. After completing any additional confirmation steps, call the SDK's Confirm User method to finalize the user account creation on Atlas App Services.

Automatically Confirm Users

You can configure the provider to Automatically Confirm Users. When selected, App Services immediately confirms new Email/Password users after registration.

Send a Password Reset Email

You can configure the provider to Send a Password Reset Email. When a user requests a password reset, App Services sends a Password Reset URL to a user's email address. The user must visit this URL within 30 minutes.

When you configure password reset emails, you can configure the following settings:

• Password Reset URL: the base of the URL included in every password reset email. App Services appends a unique token and tokenId to this URL. These serve as query parameters to create a unique link for every password reset. To reset the user's password, extract these query parameters from the user's unique URL. Pass the token and tokenId to the Client SDK's resetPassword function.

• Reset Password Email Subject: the subject line for the email that App Services sends. This value is optional: if omitted, App Services uses a default subject line instead. Custom password reset subjects can contain a maximum of 256 characters.

Mobile applications can handle password resets directly in the app. Configure deep linking in Android or universal links in iOS.

Run a Password Reset Function

You can configure the provider to Run a Password Reset Function. You define a Function for App Services to run when you callResetPasswordFunction() in the SDK. App Services passes the user's email, the desired new password, a confirmation token, and a token ID to the function that you create. Your function then performs the logic you need to confirm the user's identity prior to resetting the password.

App Services can immediately reset the user's password. Or you can require additional confirmation from the client application.

The App Services function must return an object containing a status key. The key maps to a string with one of the following values, which are explained in more detail below:

• { status: 'success' }

• { status: 'fail' }

• { status: 'pending' }

You can use a custom password reset function to define your own password reset flows:

• Send custom password reset emails from a specific domain with a particular template using an external service.

• Interface with a MongoDB Atlas collection to implement a password reset "cooldown period". This can prevent too many password reset attempts on a single account in a particular time range.

• Send custom password reset messages through a service other than email.

The custom password reset function signature is variadic: it accepts any number of parameters. The first is always an object containing user data and confirmation tokens. All following parameters are custom parameters. They are passed into the Client SDK as an argument collection. For instance, the Client SDK call:

callResetPasswordFunction("myUsername", "newPassword", ["Security Question Answer 1", "Security Question Answer 2", "securityCode:0510"])

Becomes this customized signature for the password reset function:

resetFunc({username, password, token, tokenId}, securityAnswer1, securityAnswer2, securitySMSCode)

In the custom password reset function, an object must be passed as the first parameter. The following table describes the fields found in this object:

The custom password reset function must return an object that contains a status field. The value of this status field may be one of:

A custom password reset function may include elements similar to this example:

exports = ({ token, tokenId, username, password }) => {
   // check if the username corresponds to a real user
   const isUser = myCustomValidator.validate(username);
   // check if the user has requested a password reset too often recently
   const isNotCoolingDown = myCustomCooldownService.canReset(username, 'myCustomService')
   // send a message to the user in some way so that the user can confirm themselves
   const msgSendSuccessful = isUser && isNotCoolingDown && myCustomMsgr.send(username, token, tokenId)
   if ( msgSendSuccessful ) {
      return { status: 'pending' };
   } else {
      return { status: 'fail' };
   }
}