Email/Password Authentication
On this page
Overview
The Email/Password authentication provider allows users to register accounts and log in using their email address and a password. Atlas App Services must confirm Email/Password users before it allows them to log in to your application.
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.
Configuration
User Confirmation
App Services confirms Email/Password authentication provider users in one of three ways:
Send a Confirmation Email
If you configure the provider to Send a Confirmation Email, App Services 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 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
andtokenId
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'sconfirmUser
function. - Email Confirmation Subject: the subject of the email sent to the user containing the confirmation URL. 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.
Mobile applications can handle email confirmation directly in the app by configuring deep linking in Android or universal links in iOS.
Run a Confirmation Function
If you configure the provider to Run a Confirmation Function, Atlas App Services runs an App Services Function whenever a new Email/Password user registers an account. App Services 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 App Services 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 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 mapping to a string with one of the following values:success
,pending
, orfail
.
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:
Field | Description |
---|---|
username | The email address of the user. |
token | A unique value that can be used to confirm the user's identity
using the SDK confirmUser function. |
tokenId | A 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:
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
but the client application must call the confirmUser SDK function to
fully confirm the user's identity and allow login. |
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' }; } }
Automatically Confirm Users
If you configure the provider to Automatically Confirm Users, App Services immediately confirms new Email/Password users after registration. When selected, App Services does not validate email addresses and does not send any email to the user.
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
orasdavaskljj
)
Exercise caution with this option, as securely resetting the password of a user account with no valid contact information can be very difficult.
Password Resets
App Services resets Email/Password authentication provider user passwords in one of two ways:
Send a Password Reset Email
If you configure the provider to Send a Password Reset Email, App Services 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 App Services automatically send a password reset email:
- Password Reset URL: the base of the URL included in every
password reset email. App Services appends a unique
token
andtokenId
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'sresetPassword
function. - Reset Password Email Subject: the subject line of the email that App Services sends to users when they request to reset their password. 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 by configuring deep linking in Android or universal links in iOS.
Run a Password Reset Function
If you configure the provider to Run a Password Reset
Function, App Services runs a App Services Function that you define
whenever the client SDK callResetPasswordFunction()
function is
called. App Services 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
App Services 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 App Services 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 astatus
key mapping to a string with one of the following values:success
,pending
, orfail
.
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:
Field | Description |
---|---|
username | The email address of the user. |
password | A new proposed password for the user. If this function returns the
successful status, the user's password will be updated to this
value. |
token | A unique value that can be used to update the user's password. |
tokenId | A 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:
Status | Effect |
---|---|
success | App Services 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. |
pending | App Services 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. |
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' }; } }
The a 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 App Services 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.
Examples
For code examples that demonstrate how to register and log in using email/password authentication, see the documentation for the Realm SDKs:
Summary
- 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.