Lockit - an Express authentication solution

What does every app need? Users!

What does every app therefore need to have? An authentication solution:

  • signup new users
  • allow existing users to login
  • help users who forgot their password
  • etc.

What’s the most annoying part to write when building a new app? The user authentication solution.

Focus on building your app instead of reinventing the wheel and use lockit.


Lockit is inspired by Ruby’s devise. It consists of multiple single purpose modules that you could also use on their own. The main module lockit is just a wrapper around those

When you have problems please try to open an issue in the according repository.

How to use

Install the module and an adapter for your database via npm

npm install lockit lockit-couchdb-adapter

Create a config.js in your app/ folder with your database settings

// database settings for CouchDB
exports.db = '';

// or if you want to use MongoDB
// exports.db = 'mongodb://';
// exports.dbCollection = 'users';

Use both files in app.js.

var config = require('./config.js');
var lockit = require('lockit');

Activate the module by calling the main lockit() function

// ... express stuff

// use middleware before router so your own routes have access to
// req.session.email and req.session.username

// sessions have to be enabled!
lockit(app, config);

// ... more express stuff

Include bootstrap css in your views/layout.jade

link(rel='stylesheet', href='/css/bootstrap.min.css')

Start your app like always with node app.js, open the browser and navigate to localhost:3000/signup. I’ve built some example apps that you can download and run locally.

You’ll notice that nothing happens after you’ve signed up although you should see a message that an email has been sent to you. If you take a look at your database however, you should be able to see your just created user. So the user is created but the email is simply not sent.

That’s because the email service is not set up yet. By default all email communication is stubbed (no emails are sent). You need to have your own email service in order to send emails when a user signs up or requests a new password. Under the hood lockit uses nodemailer to send emails. You can therefore use the same configuration in your config.js file.

// default settings
exports.emailType = 'Stub';
exports.emailSettings = {
  service: 'none',
  auth: {
    user: 'none',
    pass: 'none'

// change them to something similar like
// exports.emailType = 'SMTP';
// exports.emailSettings = {
//   service: 'Gmail',
//   auth: {
//     user: 'gmail.user@gmail.com',
//     pass: 'userpass'
//   }
// };

Now you are good to go. You can also change all the other stuff like email template, welcome text, title and subject of the emails, etc. Take a look at the lockit#configuration part at GitHub to see all possibilities.


  1. How is this different to passport?

Passport offers different strategies (local, OpenID, OAuth) for authentication. It assumes that you already have users in your db and only handles login, logout and route restriction. It does not send any emails on signup or when a user forgot a password. You can think of Lockit as a layer before Passport. I haven’t tried it yet but it should work to use Lockit for signup, forgot password, delete account and on top of that Passport with the local strategy.

  1. Why didn’t you use Persona?

Well, I’ve tried Persona and like it a lot for simple web based solutions. However authentication solutions should work on all devices and for all platforms. One big problem is that Persona does not work with PhoneGap and other environments that break when opening popups. See the related issue #2034.

  1. What about a SaaS solution like userapp?

User information is the most valuable, critical and sensible data. Users trust you to handle them with care. Therefore I don’t like giving them away.

  1. And how about OpenID or OAuth?

Whenever I come across an app that has access only via Facebook / Twitter / Google / etc. I scream, close the tab and never come back.


Please give lockit a try. Leave comments, feedback and issues on GitHub or here in the comments.

I’m not a security expert although I’ve read a lot about this topic while developing lockit. So use it with care and probably do not use it for production yet. I’m sure there is room for improvements.

comments powered by Disqus