Passport-Local Mongoose is a Mongoose plugin that simplifies building username and password login with Passport.
$ npm install passport-local-mongoose
Passport-Local Mongoose does not require passport
, passport-local
or mongoose
dependencies directly but expects you
to have these dependencies installed.
First you need to plugin Passport-Local Mongoose into your User schema
var mongoose = require('mongoose'),
Schema = mongoose.Schema,
passportLocalMongoose = require('passport-local-mongoose');
var User = new Schema({});
User.plugin(passportLocalMongoose);
module.exports = mongoose.model('User', User);
You're free to define your User how you like. Passport-Local Mongoose will add a username, hash and salt field to store the username, the hashed password and the salt value.
Additionally Passport-Local Mongoose adds these methods to your Schema.
- setPassword(password, cb) asynchronous method to set a user's password hash and salt
- authenticate(password, cb) asynchronous method to authenticate a user instance
- authenticate() Generates a function that is used in Passport's LocalStrategy
- serializeUser() Generates a function that is used by Passport to serialize users into the session
- deserializeUser() Generates a function that is used by Passport to deserialize users into the session
- register(user, password, cb) Convenience method to register a new user instance with a given password. Checks if username is unique. See login example.
- findByUsername() Convenience method to find a user instance by it's unique username.
You should configure Passport/Passport-Local as described in the Passport Guide.
Passport-Local Mongoose supports this setup by implementing a LocalStrategy
and serializeUser/deserializeUser functions.
To setup Passport-Local Mongoose use this code
// requires the model with Passport-Local Mongoose plugged in
var User = require('./models/user');
// use static authenticate method of model in LocalStrategy
passport.use(new LocalStrategy(User.authenticate()));
// use static serialize and deserialize of model for passport session support
passport.serializeUser(User.serializeUser());
passport.deserializeUser(User.deserializeUser());
Make sure that you have mongoose connected and you're done.
When plugging in Passport-Local Mongoose plugin additional options can be provided to configure the hashing algorithm.
User.plugin(passportLocalMongoose, options);
Option keys and defaults
- saltlen: specifies the salt length in bytes. Default: 32
- iterations: specifies the number of iterations used in pbkdf2 hashing algorithm. Default: 25000
- keylen: specifies the length in byte of the generated key. Default: 512
- usernameField: specifies the field name that holds the username. Defaults to 'username'. This option can be used if you want to use a different field to hold the username for example "email".
- saltField: specifies the field name that holds the salt value. Defaults to 'salt'.
- hashField: specifies the field name that holds the password hash value. Defaults to 'hash'.
Attention! Changing these values for example in a production environment will prevent that existing users can authenticate!
Passport-Local Mongoose use the pbkdf2 algorithm of the node crypto library. Pbkdf2 was choosen because platform independent (in contrary to bcrypt). For every user a generated salt value is saved to make rainbow table attacks even harder.
For a complete example implementing a registration, login and logout see the login example.