Passwords | Meteor API Docs

The accounts-password package contains a full system for password-based authentication. In addition to the basic username and password-based sign-in process, it also supports email-based sign-in including address verification and password recovery emails.

The Meteor server stores passwords using the bcrypt algorithm. This helps protect against embarrassing password leaks if the server’s database is compromised.

To add password support to your application, run this command in your terminal:

meteor add accounts-password

In addition to configuring the email package’s MAIL_URL, it is critical that you set proper values (specifically the from address) in Accounts.emailTemplates to ensure proper delivery of e-mails!

You can construct your own user interface using the functions below, or use the accounts-ui package to include a turn-key user interface for password-based sign-in.

Anywhere

Accounts.createUser(options, [callback])

import { Accounts } from 'meteor/accounts-base'

(accounts-password/password_client.js, line 105)

Create a new user.

Arguments

callback Function: Client only, optional callback. Called with no arguments on success, or with a single Error argument on failure.

Options

username String: A unique name for this user.
email String: The user's email address.
password String: The user's password. This is not sent in plain text over the wire.
profile Object: The user's profile, typically including the name field.

Or a promise based version of Accounts.createUser:

Anywhere

Accounts.createUserAsync(options)

import { Accounts } from 'meteor/accounts-base'

(accounts-password/password_client.js, line 135)

Create a new user and returns a promise of its result.

Options

username String: A unique name for this user.
email String: The user's email address.
password String: The user's password. This is not sent in plain text over the wire.
profile Object: The user's profile, typically including the name field.

On the client, this function logs in as the newly created user on successful completion. On the server, it returns the newly created user id.

On the client, you must pass password and at least one of username or email — enough information for the user to be able to log in again later. If there are existing users with a username or email only differing in case, createUser will fail. The callback’s error.reason will be 'Username already exists.' or 'Email already exists.' In the latter case, the user can then either login or reset their password.

On the server, you do not need to specify password, but the user will not be able to log in until it has a password (eg, set with Accounts.setPasswordAsync). To create an account without a password on the server and still let the user pick their own password, call createUser with the email option and then call Accounts.sendEnrollmentEmail. This will send the user an email with a link to set their initial password.

By default the profile option is added directly to the new user document. To override this behavior, use Accounts.onCreateUser.

This function is only used for creating users with passwords. The external service login flows do not use this function.

Instead of modifying documents in the Meteor.users collection directly, use these convenience functions which correctly check for case insensitive duplicates before updates.

Server

Accounts.createUserVerifyingEmail(options)

import { Accounts } from 'meteor/accounts-base'

(accounts-password/password_server.js, line 1026)

Creates an user asynchronously and sends an email if options.email is informed. Then if the sendVerificationEmail option from the Accounts package is enabled, you'll send a verification email if options.password is informed, otherwise you'll send an enrollment email.

Options

username String: A unique name for this user.
email String: The user's email address.
password String: The user's password. This is not sent in plain text over the wire.
profile Object: The user's profile, typically including the name field.

Server

Accounts.setUsername(userId, newUsername)

import { Accounts } from 'meteor/accounts-base'

(accounts-password/password_server.js, line 230)

Change a user's username asynchronously. Use this instead of updating the database directly. The operation will fail if there is an existing user with a username only differing in case.

Arguments

userId String: The ID of the user to update.
newUsername String: A new username for the user.

Server

Accounts.addEmail(userId, newEmail, [verified])

import { Accounts } from 'meteor/accounts-base'

(accounts-password/password_server.js, line 844)

Add an email asynchronously address for a user. Use this instead of directly updating the database. The operation will fail if there is a different user with an email only differing in case. If the specified user has an existing email only differing in case however, we replace it.

Arguments

userId String: The ID of the user to update.
newEmail String: A new email address for the user.
verified Boolean: Optional - whether the new email address should be marked as verified. Defaults to false.

By default, an email address is added with { verified: false }. Use Accounts.sendVerificationEmail to send an email with a link the user can use to verify their email address.

Server

Accounts.removeEmail(userId, email)

import { Accounts } from 'meteor/accounts-base'

(accounts-password/password_server.js, line 940)

Remove an email address asynchronously for a user. Use this instead of updating the database directly.

Arguments

userId String: The ID of the user to update.
email String: The email address to remove.

Client

Accounts.verifyEmail(token, [callback])

import { Accounts } from 'meteor/accounts-base'

(accounts-password/password_client.js, line 266)

Marks the user's email address as verified. Logs the user in afterwards if the user doesn't have 2FA enabled.

Arguments

token String: The token retrieved from the verification URL.
callback Function: Optional callback. Called with no arguments on success, or with a single Error argument on failure.

If the user trying to verify the email has 2FA enabled, this error will be thrown:

“Email verified, but user not logged in because 2FA is enabled [2fa-enabled]”: No longer signing in the user automatically if the user has 2FA enabled.

This function accepts tokens passed into the callback registered with Accounts.onEmailVerificationLink.

Server

Accounts.findUserByUsername(username, [options])

import { Accounts } from 'meteor/accounts-base'

(accounts-password/password_server.js, line 122)

Finds the user asynchronously with the specified username. First tries to match username case sensitively; if that fails, it tries case insensitively; but if more than one user matches the case insensitive search, it returns null.

Arguments

username String: The username to look for

Options

fields Mongo Field Specifier: Dictionary of fields to return or exclude.

Server

Accounts.findUserByEmail(email, [options])

import { Accounts } from 'meteor/accounts-base'

(accounts-password/password_server.js, line 138)

Finds the user asynchronously with the specified email. First tries to match email case sensitively; if that fails, it tries case insensitively; but if more than one user matches the case insensitive search, it returns null.

Arguments

email String: The email address to look for

Options

fields Mongo Field Specifier: Dictionary of fields to return or exclude.

Use the below functions to initiate password changes or resets from the server or the client.

Client

Accounts.changePassword(oldPassword, newPassword, [callback])

import { Accounts } from 'meteor/accounts-base'

(accounts-password/password_client.js, line 163)

Change the current user's password. Must be logged in.

Arguments

oldPassword String: The user's current password. This is not sent in plain text over the wire.
newPassword String: A new password for the user. This is not sent in plain text over the wire.
callback Function: Optional callback. Called with no arguments on success, or with a single Error argument on failure.

Client

Accounts.forgotPassword(options, [callback])

import { Accounts } from 'meteor/accounts-base'

(accounts-password/password_client.js, line 207)

Request a forgot password email.

Arguments

callback Function: Optional callback. Called with no arguments on success, or with a single Error argument on failure.

Options

email String: The email address to send a password reset link.

This triggers a call to Accounts.sendResetPasswordEmail on the server. When the user visits the link in this email, the callback registered with Accounts.onResetPasswordLink will be called.

If you are using the accounts-ui package, this is handled automatically. Otherwise, it is your responsibility to prompt the user for the new password and call resetPassword.

Client

Accounts.resetPassword(token, newPassword, [callback])

import { Accounts } from 'meteor/accounts-base'

(accounts-password/password_client.js, line 234)

Reset the password for a user using a token received in email. Logs the user in afterwards if the user doesn't have 2FA enabled.

Arguments

token String: The token retrieved from the reset password URL.
newPassword String: A new password for the user. This is not sent in plain text over the wire.
callback Function: Optional callback. Called with no arguments on success, or with a single Error argument on failure.

This function accepts tokens passed into the callbacks registered with AccountsClient#onResetPasswordLink and Accounts.onEnrollmentLink.

If the user trying to reset the password has 2FA enabled, this error will be thrown:

“Changed password, but user not logged in because 2FA is enabled [2fa-enabled]”: No longer signing in the user automatically if the user has 2FA enabled.

Server

Accounts.setPasswordAsync(userId, newPassword, [options])

import { Accounts } from 'meteor/accounts-base'

(accounts-password/password_server.js, line 328)

Forcibly change the password for a user.

Arguments

userId String: The id of the user to update.
newPassword String: A new password for the user.

Options

logout Object: Logout all current connections with this userId (default: true)

Server

Accounts.sendResetPasswordEmail(userId, [email], [extraTokenData], [extraParams])

import { Accounts } from 'meteor/accounts-base'

(accounts-password/password_server.js, line 529)

Send an email asynchronously with a link the user can use to reset their password.

Arguments

userId String: The id of the user to send email to.
email String: Optional. Which address of the user's to send the email to. This address must be in the user's emails list. Defaults to the first email in the list.
extraTokenData Object: Optional additional data to be added into the token record.
extraParams Object: Optional additional params to be added to the reset url.

When the user visits the link in this email, the callback registered with AccountsClient#onResetPasswordLink will be called.

To customize the contents of the email, see Accounts.emailTemplates.

Server

Accounts.sendEnrollmentEmail(userId, [email], [extraTokenData], [extraParams])

import { Accounts } from 'meteor/accounts-base'

(accounts-password/password_server.js, line 561)

Send an email asynchronously with a link the user can use to set their initial password.

Arguments

userId String: The id of the user to send email to.
email String: Optional. Which address of the user's to send the email to. This address must be in the user's emails list. Defaults to the first email in the list.
extraTokenData Object: Optional additional data to be added into the token record.
extraParams Object: Optional additional params to be added to the enrollment url.

When the user visits the link in this email, the callback registered with Accounts.onEnrollmentLink will be called.

To customize the contents of the email, see Accounts.emailTemplates.

Server

Accounts.sendVerificationEmail(userId, [email], [extraTokenData], [extraParams])

import { Accounts } from 'meteor/accounts-base'

(accounts-password/password_server.js, line 740)

Send an email asynchronously with a link the user can use verify their email address.

Arguments

userId String: The id of the user to send email to.
email String: Optional. Which address of the user's to send the email to. This address must be in the user's emails list. Defaults to the first unverified email in the list.
extraTokenData Object: Optional additional data to be added into the token record.
extraParams Object: Optional additional params to be added to the verification url.

When the user visits the link in this email, the callback registered with Accounts.onEmailVerificationLink will be called.

To customize the contents of the email, see Accounts.emailTemplates.

Client

Accounts.onResetPasswordLink

import { Accounts } from 'meteor/accounts-base'

(accounts-base/accounts_client.js, line 686)

Register a function to call when a reset password link is clicked in an email sent by Accounts.sendResetPasswordEmail. This function should be called in top-level code, not inside Meteor.startup().

Arguments

callback Function

The function to call. It is given two arguments:

token: A password reset token that can be passed to Accounts.resetPassword.
done: A function to call when the password reset UI flow is complete. The normal login process is suspended until this function is called, so that the password for user A can be reset even if user B was logged in.

Client

Accounts.onEnrollmentLink

import { Accounts } from 'meteor/accounts-base'

(accounts-base/accounts_client.js, line 739)

Register a function to call when an account enrollment link is clicked in an email sent by Accounts.sendEnrollmentEmail. This function should be called in top-level code, not inside Meteor.startup().

Arguments

callback Function

The function to call. It is given two arguments:

token: A password reset token that can be passed to Accounts.resetPassword to give the newly enrolled account a password.
done: A function to call when the enrollment UI flow is complete. The normal login process is suspended until this function is called, so that user A can be enrolled even if user B was logged in.

Client

Accounts.onEmailVerificationLink

import { Accounts } from 'meteor/accounts-base'

(accounts-base/accounts_client.js, line 712)

Register a function to call when an email verification link is clicked in an email sent by Accounts.sendVerificationEmail. This function should be called in top-level code, not inside Meteor.startup().

Arguments

callback Function

The function to call. It is given two arguments:

token: An email verification token that can be passed to Accounts.verifyEmail.
done: A function to call when the email verification UI flow is complete. The normal login process is suspended until this function is called, so that the user can be notified that they are verifying their email before being logged in.

Server

Accounts.emailTemplates

import { Accounts } from 'meteor/accounts-base'

(accounts-passwordless/email_templates.js, line 6)

Options to customize emails sent from the Accounts system.

This is an Object with several fields that are used to generate text/html for the emails sent by sendResetPasswordEmail, sendEnrollmentEmail, and sendVerificationEmail.

Set the fields of the object by assigning to them:

from: (required) A String with an RFC5322 From address. By default, the email is sent from no-reply@example.com. If you want e-mails to send correctly, this should be changed to your own domain as most e-mail providers will reject mail sent from example.com.
siteName: The public name of your application. Defaults to the DNS name of the application (eg: awesome.meteor.com).
headers: An Object for custom email headers as described in Email.send.
resetPassword: An Object with the fields:
- from: A Function used to override the from address defined by the emailTemplates.from field.
- subject: A Function that takes a user object and returns a String for the subject line of a reset password email.
- text: An optional Function that takes a user object and a url, and returns the body text for a reset password email.
- html: An optional Function that takes a user object and a url, and returns the body html for a reset password email.
enrollAccount: Same as resetPassword, but for initial password setup for new accounts.
verifyEmail: Same as resetPassword, but for verifying the users email address.

Example:

Accounts.emailTemplates.siteName = 'AwesomeSite';
Accounts.emailTemplates.from = 'AwesomeSite Admin <accounts@example.com>';

Accounts.emailTemplates.enrollAccount.subject = (user) => {
  return `Welcome to Awesome Town, ${user.profile.name}`;
};

Accounts.emailTemplates.enrollAccount.text = (user, url) => {
  return 'You have been selected to participate in building a better future!'
    + ' To activate your account, simply click the link below:\n\n'
    + url;
};

Accounts.emailTemplates.resetPassword.from = () => {
  // Overrides the value set in `Accounts.emailTemplates.from` when resetting
  // passwords.
  return 'AwesomeSite Password Reset <no-reply@example.com>';
};
Accounts.emailTemplates.verifyEmail = {
   subject() {
      return "Activate your account now!";
   },
   text(user, url) {
      return `Hey ${user}! Verify your e-mail by following this link: ${url}`;
   }
};

Enable 2FA for this package

You can add 2FA to your login flow by using the package accounts-2fa. You can find an example showing how this would look like here.

Previous Accounts (multi-server) Next Templates

Edit on GitHub