Passwords

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

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 115)

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.

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.setPassword). 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.setUsername(userId, newUsername)

import { Accounts } from 'meteor/accounts-base' (accounts-password/password_server.js, line 375)

Change a user's username. 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 864)

Add an email 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 948)

Remove an email address 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 263)

Marks the user's email address as verified. Logs the user in afterwards.

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.

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

Server

Accounts.findUserByUsername(username)

import { Accounts } from 'meteor/accounts-base' (accounts-password/password_server.js, line 124)

Finds the user 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

Server

Accounts.findUserByEmail(email)

import { Accounts } from 'meteor/accounts-base' (accounts-password/password_server.js, line 140)

Finds the user 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

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 151)

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 214)

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 235)

Reset the password for a user using a token received in email. Logs the user in afterwards.

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.

Server

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

import { Accounts } from 'meteor/accounts-base' (accounts-password/password_server.js, line 475)

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])

import { Accounts } from 'meteor/accounts-base' (accounts-password/password_server.js, line 529)

Send an email 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.

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])

import { Accounts } from 'meteor/accounts-base' (accounts-password/password_server.js, line 595)

Send an email 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.

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])

import { Accounts } from 'meteor/accounts-base' (accounts-password/password_server.js, line 735)

Send an email 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.

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/url_client.js, line 91)

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:

1. token: A password reset token that can be passed to Accounts.resetPassword.
2. 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/url_client.js, line 144)

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:

1. token: A password reset token that can be passed to Accounts.resetPassword to give the newly enrolled account a password.
2. 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/url_client.js, line 117)

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:

1. token: An email verification token that can be passed to Accounts.verifyEmail.
2. 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-password/email_templates.js, line 21)

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.

Override fields of the object by assigning to them:

• from: A String with an RFC5322 From address. By default, the email is sent from [email protected]. If you wish to receive email from users asking for help with their account, be sure to set this to an email address that you can receive email at.
• 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 <[email protected]>";
Accounts.emailTemplates.enrollAccount.subject = function (user) {
    return "Welcome to Awesome Town, " + user.profile.name;
};
Accounts.emailTemplates.enrollAccount.text = function (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 = function () {
   // Overrides value set in Accounts.emailTemplates.from when resetting passwords

   return "AwesomeSite Password Reset <[email protected]>";
};