Passwords

Documentation of Meteor's password-based accounts API.

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

The Meteor server stores passwords using thebcrypt algorithm. This helpsprotect against embarrassing password leaks if the server’s database iscompromised.

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 thefunctions below, or use the accounts-ui package toinclude 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 122)

Create a new user.

Arguments

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

Options

• usernameString

• A unique name for this user.

• emailString

• The user's email address.

• passwordString

• The user's password. This is not sent in plain text over the wire.

• profileObject

• The user's profile, typically including the name field.

On the client, this function logs in as the newly created user onsuccessful completion. On the server, it returns the newly created userid.

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. Tooverride this behavior, use Accounts.onCreateUser.

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

Instead of modifying documents in the Meteor.users collectiondirectly, use these convenience functions which correctly check for caseinsensitive duplicates before updates.

Server

Accounts.setUsername(userId, newUsername)

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

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

Arguments

• userIdString

• The ID of the user to update.

• newUsernameString

• A new username for the user.

Server

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

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

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

Arguments

• userIdString

• The ID of the user to update.

• newEmailString

• A new email address for the user.

• verifiedBoolean

• Optional - whether the new email address shouldbe marked as verified. Defaults to false.

By default, an email address is added with { verified: false }. UseAccounts.sendVerificationEmail to send anemail 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 1029)

Remove an email address for a user. Use this instead of updatingthe database directly.

Arguments

• userIdString

• The ID of the user to update.

• emailString

• The email address to remove.

Client

Accounts.verifyEmail(token, [callback])

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

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

Arguments

• tokenString

• The token retrieved from the verification URL.

• callbackFunction

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

Server

Accounts.findUserByUsername(username)

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

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

Arguments

• usernameString
• The username to look for

Server

Accounts.findUserByEmail(email)

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

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

Arguments

• emailString
• The email address to look for

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

Client

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

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

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

Arguments

• oldPasswordString

• The user's current password. This is not sent in plain text over the wire.

• newPasswordString

• A new password for the user. This is not sent in plain text over the wire.

• callbackFunction

• 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 221)

Request a forgot password email.

Arguments

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

Options

• emailString
• The email address to send a password reset link.

This triggers a callto Accounts.sendResetPasswordEmailon the server. When the user visits the link in this email, the callbackregistered with Accounts.onResetPasswordLinkwill be called.

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

Client

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

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

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

Arguments

• tokenString

• The token retrieved from the reset password URL.

• newPasswordString

• A new password for the user. This is not sent in plain text over the wire.

• callbackFunction

• 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 withAccountsClient#onResetPasswordLink andAccounts.onEnrollmentLink.

Server

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

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

Forcibly change the password for a user.

Arguments

• userIdString

• The id of the user to update.

• newPasswordString

• A new password for the user.

Options

• logoutObject
• Logout all current connections with this userId (default: true)

Server

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

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

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

Arguments

• userIdString

• The id of the user to send email to.

• emailString

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

• extraTokenDataObject

• Optional additional data to be added into the token record.

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

To customize the contents of the email, seeAccounts.emailTemplates.

Server

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

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

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

Arguments

• userIdString

• The id of the user to send email to.

• emailString

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

• extraTokenDataObject

• Optional additional data to be added into the token record.

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

To customize the contents of the email, seeAccounts.emailTemplates.

Server

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

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

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

Arguments

• userIdString

• The id of the user to send email to.

• emailString

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

• extraTokenDataObject

• Optional additional data to be added into the token record.

When the user visits the link in this email, the callback registered withAccounts.onEmailVerificationLink willbe called.

To customize the contents of the email, seeAccounts.emailTemplates.

Client

Accounts.onResetPasswordLink

import { Accounts } from 'meteor/accounts-base' (accounts-base/accounts_client.js, line 651)

Register a function to call when a reset password link is clickedin an email sent byAccounts.sendResetPasswordEmail.This function should be called in top-level code, not insideMeteor.startup().

Arguments

• callbackFunction

• The function to call. It is given two arguments:

  • token: A password reset token that can be passed toAccounts.resetPassword.
  • done: A function to call when the password reset UI flow is complete. The normallogin process is suspended until this function is called, so that thepassword 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 704)

Register a function to call when an account enrollment link isclicked in an email sent byAccounts.sendEnrollmentEmail.This function should be called in top-level code, not insideMeteor.startup().

Arguments

• callbackFunction

• The function to call. It is given two arguments:

  • token: A password reset token that can be passed toAccounts.resetPassword to give the newlyenrolled 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 thatuser 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 677)

Register a function to call when an email verification link isclicked in an email sent byAccounts.sendVerificationEmail.This function should be called in top-level code, not insideMeteor.startup().

Arguments

• callbackFunction

• The function to call. It is given two arguments:

  • token: An email verification token that can be passed toAccounts.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, sothat the user can be notified that they are verifying their email beforebeing logged in.

Server

Accounts.emailTemplates

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

Options to customize emails sent from the Accounts system.

This is an Object with several fields that are used to generate text/htmlfor 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 definedby the emailTemplates.from field.
  • subject: A Function that takes a user object and returnsa String for the subject line of a reset password email.
  • text: An optional Function that takes a user object and a url, andreturns the body text for a reset password email.
  • html: An optional Function that takes a user object and aurl, 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}`;
   }
};