Email/Password Authentication

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

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:

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

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

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.

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

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:

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

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