Email/Password Authentication

Send a Confirmation Email

If you configure the provider to Send a Confirmation Email, Realm sends a confirmation email to the email address provided by new Email/Password users when they register an account. The email contains a link to a confirmation URL that the user must visit within 30 minutes to confirm that they control the email address.

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

• Email Confirmation URL: the base of the URL included in every confirmation email. Realm appends a unique token and tokenId to this URL as query parameters to create a unique link for every confirmation. To confirm the user, extract these query parameters from the user's unique URL and pass the token and tokenId to the Client SDK's confirmUser function.
• Email Confirmation Subject: the subject of the email sent to the user containing the confirmation URL. This value is optional: if omitted, Realm uses a default subject line instead. Custom email confirmation subjects can contain a maximum of 256 characters.

Run a Confirmation Function

If you configure the provider to Run a Confirmation Function, MongoDB Realm runs a Realm Function whenever a new Email/Password user registers an account. Realm passes this function unique confirmation tokens and data about the user which allows you to define custom logic to confirm users. The return value of this function determines whether Realm immediately confirms the user or requires additional confirmation from the client application.

You can use a custom confirmation function to define your own confirmation flows, such as the following examples:

• Send custom confirmation emails from a specific domain with a particular template using an external service.
• Read user permissions from a collection in a MongoDB Atlas instance or an external REST service to confirm whether a user is authorized to use the application or not.
• Send confirmation messages through a service other than email.

Configure the following settings to have Realm automatically run a confirmation function:

• Function: the function run when a user registers a new account with your Realm app. This function must return an object containing a status key mapping to a string with one of the following values: success, pending, or fail.

The custom confirmation function signature has one parameter: an object containing user data and confirmation tokens. The following table describes the fields found in the object passed to the custom user confirmation function:

The following table describes the potential values of the status field in the object returned by the custom user confirmation function:

A user confirmation function is generally structured as follows:

exports = ({ token, tokenId, username }) => {
   // validate the username
   const isValidEmail = myFakeValidator.validate(username);
   // check if the user is privileged for this service
   const isPrivileged = myFakeAuth.hasAccess(username, 'myFakeService')
   // send a message to the user in some way so that the user can confirm themselves
   const msgSendSuccessful = isValidEmail && isPrivileged && myFakeMsgr.send(username, token, tokenId)
   if ( msgSendSuccessful ) {
      return { status: 'pending' };
   } else {
      return { status: 'fail' };
   }
}

Automatically Confirm Users

If you configure the provider to Automatically Confirm Users, Realm immediately confirms new Email/Password users after registration. When selected, Realm does not validate email addresses and does not send any email to the user.

Send a Password Reset Email

If you configure the provider to Send a Password Reset Email, Realm sends a Password Reset URL to a user's email address when a user requests a password reset. The user must visit this URL within 30 minutes to confirm their intent to change their password.

Configure the following settings to have Realm automatically send a password reset email:

• Password Reset URL: the base of the URL included in every password reset email. Realm appends a unique token and tokenId to this URL 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 and pass the token and tokenId to the Client SDK's resetPassword function.
• Reset Password Email Subject: the subject line of the email that Realm sends to users when they request to reset their password. This value is optional: if omitted, Realm uses a default subject line instead. Custom password reset subjects can contain a maximum of 256 characters.

Run a Password Reset Function

If you configure the provider to Run a Password Reset Function, Realm runs a Realm Function that you define whenever the client SDK callResetPasswordFunction() function is called. Realm passes this function unique confirmation tokens and data about the user which allows you to define custom logic to reset a user's password. The value that you return from the function determines whether Realm immediately resets the user's password or requires additional confirmation from the client application.

You can use a custom password reset function to define your own password reset flows, such as the following examples:

• 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" to 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.

Configure the following settings to have Realm automatically run a password reset function:

• Function: the function run when an instance of the client SDK calls the callResetPasswordFunction function. This function must return an object containing a status key mapping to a string with one of the following values: success, pending, or fail.

The custom password reset function signature is variadic: it accepts any number of parameters. The first of these parameters is always an object containing user data and confirmation tokens. All parameters after the first are custom parameters 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"])

Would be translated into the following custom password reset function signature:

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

Each element of the custom argument array is spread into a parameter for the custom password reset function, starting with the second parameter.

The following table describes the fields found in the object passed to the custom password reset function as the first parameter:

The following table describes the potential values of the status field in the object returned by the custom password reset function:

A custom password reset function is generally structured as follows:

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