In this tutorial, we will develop a Node.js application from scratch and use the popular authentication middleware Passport to take care of our authentication concerns.

Passport's documentation describes it as a "simple, unobtrusive authentication middleware for Node" and rightly so.

By providing itself as middleware, Passport does an excellent job at separating the other concerns of a web application from its authentication needs. It allows Passport to be easily configured into any Express-based web application, just like we configure other Express middleware such as logging, body-parsing, cookie-parsing, and session-handling.

This tutorial assumes a basic understanding of Node.js and the Express framework to keep the focus on authentication, although we do create a sample Express app from scratch. We'll secure the app by adding routes to it and authenticating some of those routes.

Authentication Strategies

Passport provides us with 500+ authentication mechanisms to choose from. You can authenticate against a local or remote database instance or use the single sign-on using OAuth providers for Facebook, Twitter, Google, etc. to authenticate with your social media accounts.

But don't worry: you don't need to include any strategy that your application does not need. All these strategies are independent of each other and packaged as separate node modules which are not included by default when you install Passport's middleware: npm install passport.

In this tutorial, we will use the Local Authentication Strategy of Passport and authenticate the users against a locally configured MongoDB instance, storing the user details in the database. This strategy lets you authenticate users in your Node.js applications using a username and password.

For using the Local Authentication Strategy, we need to install the passport-local module:

npm install passport-local

But wait: Before you fire up your terminal and start executing these commands, let's start by building an Express app from scratch and adding some routes to it (for login, registration, and home). Then we'll try to add our authentication middleware to it. Note that we will be using Express 4 for the purpose of this tutorial, but with some minor differences Passport works equally well with Express 3.

Setting Up the Application

If you haven't already, then go ahead and install Express by executing the snippet in your terminal:

npm install express --save

You can also install the express-generator with the following code snippet:

npm install -g express-generator

Executing express passport-mongo on the terminal will generate a boilerplate application in your specified directory. The generated application structure should look like this:

Let's remove some of the default functionality that we won't be using. You can go ahead and delete the users.js route and remove its references from the app.js file.

Adding Project Dependencies

Open up package.json and add the dependencies for the passport and passport-local modules.

"passport": "~0.6.0",
"passport-local": "~1.0.0"

Since we will be saving the user details in MongoDB, we will use Mongoose as our object data modelling tool. Another way to install and save the dependency to package.json is by executing the code snippet:

npm install mongoose --save 

The package.json file should look like this:

Now, install all the dependencies and run the boilerplate application by executing:

npm install && npm start

The above command will install all of the dependencies and start the node server. You can check the basic Express app at http://localhost:3000/, but there's nothing much to see.

Very soon, we are going to change that by creating a full-fledged Express app that:

1. shows a registration page for a new user
2. shows the login of a registered user
3. authenticates the registered user with Passport

Creating a Mongoose Model

Since we will be saving the user details in Mongo, let's create a User Model in Mongoose and save that in models/user.js in our app.

var mongoose = require('mongoose');

module.exports = mongoose.model('User',{
        username: String,
        password: String,
	email: String,
	firstName: String,
	lastName: String
});

Basically, we are creating a Mongoose model, using which we can perform CRUD operations on the underlying database.

Configuring Mongo

If you do not have Mongo installed locally, then I recommend that you use cloud database services such as MongoDB Cloud. Creating a working MongoDB instance is not only free but is just a matter of a few clicks.

After you create a database on one of these services, it will give you a database URI likemongodb://<dbuser>:<dbpassword>@novus.modulusmongo.net:27017/<dbName> which can be used to perform CRUD operations on the database. It's a good idea to keep the database configuration in a separate file that you can pull up as and when needed. As such, we create a db.js file in the root directory which looks like:

module.exports = {
  'url' : 'mongodb://<dbuser>:<dbpassword>@novus.modulusmongo.net:27017/<dbName>'
}

If you're like me, you are using a local Mongo instance. So it's time to start the mongod daemon, and the db.js should look like this:

module.exports = {
  'url' : 'mongodb://localhost/passport'
}

Now we use this configuration in app.js and connect to it using Mongoose APIs:

let dbConfig = require('./db.js');
let mongoose = require('mongoose');
mongoose.connect(dbConfig.url);

Configuring Passport

Passport just provides the mechanism to handle authentication, leaving the onus of implementing session-handling ourselves, and for that we will be using express-session. Open up app.js and paste the code below before configuring the routes:

// Configuring Passport
var passport = require('passport');
var expressSession = require('express-session');
app.use(expressSession({
  secret: 'mySecretKey',
  resave: true,
  saveUninitialized: true
}));
app.use(passport.initialize());
app.use(passport.session());

This is needed as we want our user sessions to be persistent in nature. Before running the app, we need to install express-session and add it to our dependency list in package.json. To do that, type npm install --save express-session.

Serializing and Deserializing User Instances

Passport also needs to serialize and deserialize user instances from a session store in order to support login sessions, so that every subsequent request will not contain the user credentials. It provides two methods, serializeUser and deserializeUser, for this purpose. The serializeUser function is used to persist a user's data into the session after successful authentication, while a deserializeUser is used to retrieve a user's data from the session.

Create a new folder called passport, and create a file init.js with the following code snippets:

var User = require('../models/user');

module.exports = function(passport){

    // Passport needs to be able to serialize and deserialize users to support persistent login sessions
    passport.serializeUser(function(user, done) {
        console.log('serializing user: ', user);
        done(null, user._id);
    });

    passport.deserializeUser(function(id, done) {
        User.findById(id, function(err, user) {
            console.log('deserializing user:',user);
            done(err, user);
        });
    });
}

Using Passport Strategies

We will now define Passport's strategies for handling login and signup. Each of them would be an instance of the Local Authentication Strategy of Passport and would be created using the passport.use() function. We use connect-flash to help us with error handling by providing flash messages which can be displayed to the user on error. This can be installed by running npm i connect-flash.

Login Strategy

Create a login.js file in the passport folder. The login strategy looks like this:

// passport/login.js
var LocalStrategy   = require('passport-local').Strategy;
var User = require('../models/user');

passport.use('login', new LocalStrategy({
    passReqToCallback : true
  },
  function(req, username, password, done) {
    // check in mongo if a user with username exists or not
    User.findOne({ 'username' :  username },
      function(err, user) {
        // In case of any error, return using the done method
        if (err)
          return done(err);
        // Username does not exist, log error & redirect back
        if (!user){
          console.log('User Not Found with username '+username);
          return done(null, false,
                req.flash('message', 'User Not found.'));
        }
        // User exists but wrong password, log the error
        if (!isValidPassword(user, password)){
          console.log('Invalid Password');
          return done(null, false,
              req.flash('message', 'Invalid Password'));
        }
        // User and password both match, return user from
        // done method which will be treated like success
        return done(null, user);
      }
    );
}));

The first parameter to passport.use() is the name of the strategy which will be used to identify this strategy when applied later. The second parameter is the type of strategy that you want to create; here we use the username-password or the LocalStrategy. Note that by default the LocalStrategy expects to find the user credentials in the username and password parameters, but it allows us to use any other named parameters as well. The passReqToCallback config variable allows us to access the request object in the callback, thereby enabling us to use any parameter associated with the request.

Next, we use the Mongoose API to find the User in our underlying collection of Users to check if the user is a valid user or not. The last parameter in our callback, done, denotes a useful method with which we could signal success or failure to the Passport module. To specify failure, either the first parameter should contain the error or the second parameter should evaluate to false. To signify success, the first parameter should be null and the second parameter should evaluate to a truthy value, in which case it will be made available on the request object.

Since passwords are inherently weak in nature, we should always encrypt them before saving them to the database. So we'll use bcryptjs to help us with the encryption and decryption of passwords.

In the login.js file, we install bcryptjs by executing the command npm install bcryptjs and adding the following code snippets to the login.js file just below the passport.use() function.

var bCrypt = require('bcrypt-nodejs');

module.exports = function(passport){

    passport.use('login', ...)
    );

    var isValidPassword = function(user, password){
        return bCrypt.compareSync(password, user.password);
    }
}

If you're feeling uneasy with the code snippets and prefer to see the complete code in action, feel free to browse the code here.

Registration Strategy

Now, we create a signup.js file in the passport folder and define the next strategy, which will handle registration of a new user and create an entry in our underlying Mongo database:

var LocalStrategy   = require('passport-local').Strategy;
var User = require('../models/user');
var bCrypt = require('bcryptjs');

module.exports = function(passport){
passport.use('signup', new LocalStrategy({
    passReqToCallback : true
  },
  function(req, username, password, done) {
    findOrCreateUser = function(){
      // find a user in Mongo with provided username
      User.findOne({'username':username},function(err, user) {
        // In case of any error return
        if (err){
          console.log('Error in SignUp: '+err);
          return done(err);
        }
        // already exists
        if (user) {
          console.log('User already exists');
          return done(null, false,
             req.flash('message','User Already Exists'));
        } else {
          // if there is no user with that email
          // create the user
          var newUser = new User();
          // set the user's local credentials
          newUser.username = username;
          newUser.password = createHash(password);
          newUser.email = req.param('email');
          newUser.firstName = req.param('firstName');
          newUser.lastName = req.param('lastName');

          // save the user
          newUser.save(function(err) {
            if (err){
              console.log('Error in Saving user: '+err);
              throw err;
            }
            console.log('User Registration succesful');
            return done(null, newUser);
          });
        }
      });
    };

    // Delay the execution of findOrCreateUser and execute
    // the method in the next tick of the event loop
    process.nextTick(findOrCreateUser);
  }));

  // Generates hash using bCrypt
  var createHash = function(password){
  return bCrypt.hashSync(password, bCrypt.genSaltSync(10), null);
}};

Here, we again use the Mongoose API to find out if any user with the given username already exists. If not, then create a new user and save the user information in Mongo. Else return the error using the done callback and flash messages. Note that we use bcryptjs to create a hash of the password before saving it.

Creating Routes

If we were to see a bird's-eye view of our application, it would look like this:

We now define our routes for the application in the following module, which takes the instance of Passport created in app.js above. Save this module in routes/index.js.

module.exports = function(passport){

  /* GET login page. */
  router.get('/', function(req, res) {
    // Display the Login page with any flash message, if any
    res.render('index', { message: req.flash('message') });
  });

  /* Handle Login POST */
  router.post('/login', passport.authenticate('login', {
	successRedirect: '/home',
	failureRedirect: '/',
	failureFlash : true
  }));

  /* GET Registration Page */
  router.get('/signup', function(req, res){
	res.render('register',{message: req.flash('message')});
  });

  /* Handle Registration POST */
  router.post('/signup', passport.authenticate('signup', {
	successRedirect: '/home',
	failureRedirect: '/signup',
	failureFlash : true
  }));

  return router;
}

The most important part of the above code snippet is the use of passport.authenticate() to delegate authentication to the login and signup strategies when an HTTP POST is made to the /login and /signup routes respectively. Note that it is not mandatory to name the strategies on the route path, and they can be named anything.

Creating Jade Views

In the views folder of our application, we should see .jade files. Jade is a templating engine, primarily used for server-side templating in Node.js. It's a powerful way of writing markup and rendering pages dynamically using Express. It gives a lot more flexibility compared to using a static HTML file. To learn more about Jade and how it works, you can check out the documentation.

Next, we create the following four views for our application: 

1. layout.jade contains the basic layout and styling information.
2. index.jade contains the login page providing the login form and giving the option to create a new account.
3. register.jade contains the registration form.
4. home.jade says hello and shows the logged-in user's details.

doctype html
html
  head
    title= title
    link(rel='stylesheet', href='/stylesheets/style.css')
    link(rel='stylesheet', href='http://maxcdn.bootstrapcdn.com/bootstrap/3.2.0/css/bootstrap.min.css')
  body
    block content

In the index.jade file, we will include the following code snippets:

extends layout

block content
  div.container
	div.row
	  div.col-sm-6.col-md-4.col-md-offset-4
		h1.text-center.login-title Sign in to our Passport app
		  div.account-wall
			img(class='profile-img', src='https://lh5.googleusercontent.com/-b0-k99FZlyE/AAAAAAAAAAI/AAAAAAAAAAA/eu7opA4byxI/photo.jpg?sz=120')
			form(class='form-signin', action='/login', method='POST')
			  input(type='text', name='username' class='form-control', placeholder='Email',required, autofocus)
			  input(type='password', name='password' class='form-control', placeholder='Password', required)
			  button(class='btn btn-lg btn-primary btn-block', type='submit') Sign in
			  span.clearfix
		  a(href='/signup', class='text-center new-account') Create an account
		  #message
		  if message
			h1.text-center.error-message #{message}

In the register.jade file, we'll include the following code snippets:

extends layout

block content
    div.container
		div.row
			div.col-sm-6.col-md-4.col-md-offset-4
				h1.text-center.login-title Registration Details
					div.signup-wall
						form(class='form-signin', action='/signup', method='POST')
							input(type='text', name='username', class='form-control', placeholder='Username',required, autofocus)
							input(type='password', name='password', class='form-control nomargin', placeholder='Password', required)
							input(type='email', name='email', class='form-control', placeholder='Email',required)
							input(type='text', name='firstName', class='form-control', placeholder='First Name',required)
							input(type='text', name='lastName', class='form-control', placeholder='Last Name',required)
							button(class='btn btn-lg btn-primary btn-block', type='submit') Register
							span.clearfix
					#message
						if message
							h1.text-center.error-message #{message}

In the home.jade file, we'll include the following code snippets:

extends layout

block content
    div.container
		div.row
			div.col-sm-6.col-md-4.col-md-offset-4
				#user
					h1.text-center.login-title Welcome #{user.firstName}. Check your details below:
						div.signup-wall
							ul.user-details
								li Username ---> #{user.username}
								li Email    ---> #{user.email}
								li First Name ---> #{user.firstName}
								li Last Name ---> #{user.lastName}
						a(href='/signout', class='text-center new-account') Sign Out

Now the registration page looks like this:

The Login page looks like this:

And the details page looks like this:

Implementing Logout Functionality

Passport, being middleware, makes it possible to add certain properties and methods on request and response objects. Passport has a very handy request.logout() method which invalidates the user session apart from other properties.

So it's easy to define a logout route:

   /* Handle Logout */
    router.get('/signout',  function(req, res, next) {
        req.logout(function(err) {
        if (err) { return next(err); }
        res.redirect('/')
        })
    });

Protecting Routes

Passport also gives the ability to protect access to a route which is deemed unfit for an anonymous user. This means that if a user tries to access http://localhost:3000/home without authenticating in the application, they will be redirected to the home page.

/* GET Home Page */
router.get('/home', isAuthenticated, function(req, res){
  res.render('home', { user: req.user });
});

// As with any middleware it is quintessential to call next()
// if the user is authenticated
var isAuthenticated = function (req, res, next) {
  if (req.isAuthenticated())
	return next();
  res.redirect('/');
}

Conclusion

Passport is not the only player in this arena when it comes to authenticating Node.js applications, but the modularity, flexibility, community support, and the fact that it's just middleware make Passport a great choice.

For a detailed comparison of Passport and Everyauth, here is an interesting and informative perspective from the developer of Passport himself.

You can find the full source code for the example in our GitHub repo.

If you want to see what else you can do with Node.js, check out the range of Node.js items on Envato Market, from a responsive AJAX contact form to a URL shortener, or even a database CRUD generator.

This post has been updated with contributions from Mary Okosun. Mary is a software developer based in Lagos, Nigeria, with expertise in Node.js, JavaScript, MySQL, and NoSQL technologies.