Docs Menu

Docs HomeAtlas App Services

Email/Password Authentication

On this page

  • Overview
  • Configuration
  • User Confirmation
  • Send a Confirmation Email
  • Run a Confirmation Function
  • Automatically Confirm Users
  • Password Resets
  • Send a Password Reset Email
  • Run a Password Reset Function
  • Examples
  • Summary

Email/password authentication lets users register and login using an email address. Atlas App Services must confirm Email/Password users before they may log in.

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.

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.

Note

Confirmation emails are not currently customizable beyond the base URL and subject line. In particular, they always come from a mongodb.com email address.

For production apps, we recommend using a confirmation function rather than the built-in confirmation email method. Confirmation functions allow you to build entirely custom email confirmations. See Run a Confirmation Function for more information.

The provider can Run a Confirmation Function when a new user registers App Services passes to this function unique confirmation tokens and user data. The return value is one of two outcomes. Either App Services immediately confirms the user, or requires additional confirmation. Confirmation must come from the client application.

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

  • 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. Use to confirm whether a user has authorization to use the application.

  • Send confirmation messages through a service other than email.

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

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

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

Field
Description
username
The user's email address.
token
A unique value used to confirm the user's identity. Use in the SDK confirmUser function.
tokenId
A unique value used to confirm the user's identity. Uses the SDK confirmUser function.

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

Status
Effect
success
App Services confirms the user's identity, allowing the user to log into their new account.
pending
App Services changes the user's confirmation status to pending. This does not confirm the user's identity or allow login. The client application must call the confirmUser SDK function to confirm.
fail
App Services 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' };
}
}

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

Warning

App Services 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. Securely resetting the password of a user account with no valid contact information can be very difficult.

App Services resets Email/Password user passwords in one of two ways:

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.

Note

Use Deep Links in Mobile Apps

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

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 this function unique confirmation tokens and data about the user. Use these values to define custom logic to reset a user's password. App Services can immediately reset the user's password. Or you can require additional confirmation from the client application.

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.

App Services can automatically run a password reset function. Configure the following settings:

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

Note

Using a password reset function causes the client SDK sendResetPasswordEmail() function to return an error. The password reset function may return a pending status. If so, you may still need to call resetPassword().

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)

There are multiple elements of the custom argument array. Starting with the second parameter, these elements are passed into the password reset function.

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

Field
Description
username
The email address of the user.
password
A new proposed password for the user. If this function returns the successful status, this is the user's new password.
token
A unique value used to update the user's password.
tokenId
A unique value used to confirm the user's identity using the SDK confirmUser function.

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

Status
Effect
success
App Services changes the user's password to the provided password parameter immediately. Only return success if you authenticate the user's identity in the custom function. You might do this with a security question or other secure means.
pending
App Services waits for the client application to reset the user's password with a client SDK resetPassword method. The user's password reset status stays in the pending state until the client application calls its resetPassword method. For more information on calling the resetPassword method, refer to the client SDK examples.
fail
Nothing 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

The a Realm SDK function callResetPasswordFunction() is not authenticated. Its password recovery is intended only for users who cannot otherwise log into their account. As a result, you cannot associate any call to this function with a specific App Services user. Returning a success status 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. For security, you should send the account owner a message via a trusted mode of communication and return pending.

For examples of registration and log in using email/password authentication, see the Realm SDKs:

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

←  Anonymous AuthenticationCustom JWT Authentication →
Share Feedback
© 2022 MongoDB, Inc.

About

  • Careers
  • Investor Relations
  • Legal Notices
  • Privacy Notices
  • Security Information
  • Trust Center
© 2022 MongoDB, Inc.