Navigation

Email/Password Authentication

The Email/Password authentication provider allows users to register accounts and log in using their email address and a password. MongoDB Realm must confirm Email/Password users before it allows them to log in to your application.

Info With Circle IconCreated with Sketch.Note

User email addresses are case-sensitive. For example, a user with the email address TestAccount@example.com could not log in using the testaccount@example.com address.

You can enable and configure the Email/Password authentication provider from the Realm UI by selecting Email/Password from the Authentication page.

Users may choose one of three ways to handle user confirmation:

Users can choose one of two ways to handle password resets:

Realm confirms Email/Password authentication provider users in one of three ways:

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.
Info With Circle IconCreated with Sketch.Note
Use Deep Links in Mobile Apps

Mobile applications can handle email confirmation directly in the app by configuring deep linking in Android or universal links in iOS.

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:

FieldDescription
usernameThe email address of the user.
tokenA unique value that can be used to confirm the user's identity using the SDK confirmUser function.
tokenIdA unique value that can be used to confirm the user's identity using the SDK confirmUser function.

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

StatusEffect
successRealm confirms the user's identity, allowing the user to log into their new account.
pendingRealm changes the user's confirmation status to pending but the client application must call the confirmUser SDK function to fully confirm the user's identity and allow login.
failRealm deletes the pending user. The user can only retry account confirmation by registering an entirely new account. Since the previous account no longer exists, the same username can be reused.

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' };
}
}

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.

Warning IconCreated with Sketch.Warning

Realm does not validate automatically confirmed email addresses. As a result, there are a few reasons you may not be able to contact such users via email:

  • An automatically confirmed user's email address might not actually belong to that user. (e.g. a user could sign up as steve.jobs@apple.com)
  • A user's email address may not even be a valid email address. (e.g. a user could sign up as my.name@gmail or asdavaskljj)

Exercise caution with this option, as securely resetting the password of a user account with no valid contact information can be very difficult.

Realm resets Email/Password authentication provider user passwords in one of two ways:

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.
Info With Circle IconCreated with Sketch.Note
Use Deep Links in Mobile Apps

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

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.
Info With Circle IconCreated with Sketch.Note

If you configure the provider to use a password reset function then the client SDK sendResetPasswordEmail() function will return an error. You may still need to call resetPassword() if the password reset function returns a pending status.

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:

FieldDescription
usernameThe email address of the user.
passwordA new proposed password for the user. If this function returns the successful status, the user's password will be updated to this value.
tokenA unique value that can be used to update the user's password.
tokenIdA unique value that can be used to confirm the user's identity using the SDK confirmUser function.

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

StatusEffect
successRealm changes the user's password to the provided password parameter immediately. Only recommended if your application can authenticate the user in the custom function itself through some secure means, such as a security question.
pendingRealm waits for client application to reset the user's password using the Client SDK resetPassword function. The user's password is not affected unless the client application calls the resetPassword function.
failNothing happens.

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' };
}
}
Warning IconCreated with Sketch.Warning

The Realm SDK function callResetPasswordFunction() is not authenticated because it is intended for password recovery for users who cannot log into their account otherwise. As a result, you cannot associate any call to this function with a specific Realm user. Returning a success status from your custom password reset function permanently changes the password to the new value in the password parameter of the function, so returning success can result in any user resetting the password of any other application user. Because of this, it is recommended to always return a pending status after sending the actual account owner a message via a trusted mode of communication.

For code examples that demonstrate how to register and log in using email/password authentication, see the documentation for the Realm SDKs:

To register or log in an email/password user from the iOS Client SDK, see the iOS SDK guide to email/password authentication.

  • Email/password authentication allows users to create an identity in your application based on a username and a password.
  • To enable Email/password authentication, your application should support a method of email confirmation, and a method of resetting a user's password. There are multiple implementation options for each of these requirements.
Give Feedback