Passport-TOTP

Passport strategy for two-factor authentication using a TOTP value.

This module lets you authenticate using a TOTP value in your Node.js applications. By plugging into Passport, TOTP two-factor authentication can be easily and unobtrusively integrated into any application or framework that supports Connect-style middleware, including Express.
TOTP values can be generated by hardware devices or software applications, including Google Authenticator.

Note that in contrast to most Passport strategies, TOTP authentication requires that a user already be authenticated using an initial factor. Requirements regarding when to require a second factor are a matter of application-level policy, and outside the scope of both Passport and this strategy.

Fork Notes

This is a fork of the original passport-totp package, which hadn't been updated since 2015. The API has been tweaked and is NOT directly backwards compatible as the argument signature of the setup callback function has changed.

Install

$ npm install passport-totp-auth

Usage

Configure Strategy

The TOTP authentication strategy authenticates a user using a TOTP value generated by a hardware device or software application (known as a token). The strategy requires a setup callback that is sent the Passport request, options, and a done callback function that will be passed the secret key. Ensure the key is decoded first if it is stored as Base32, Base64, etc.

  // Assuming that keysModel is a database model storing OTP secret keys.
  passport.use(new TotpStrategy(function(rep, opts, done) {

    keysModel.findOne({ userId: rep.user.id }, function (err, key) {
      if (err) { return done(err); }
      let secret = GoogleAuthenticator.decodeSecret(key.value);
      return done(null, secret, key.period);
    });

  }));

Authenticate Requests

Use passport.authenticate(), specifying the 'totp' strategy, to authenticate requests.

For example, as route middleware in an Express application:

app.post('/verify-otp', 
  passport.authenticate('totp', { failureRedirect: '/verify-otp' }),
  function(req, res) {
    req.session.authFactors = [ 'totp' ];
    res.redirect('/');
  });

Examples

For a complete, working example, refer to the two-factor example.

Tests

The original tests are currently disabled as they depended on ancient versions of mocha and chai which had dependencies with multiple critical security issues. The tests will be back when I can refactor/rewrite them to use modern testing libraries.

Credits

• Jared Hanson - Original author of this, and Passport itself.
• Ilya Verbitskiy - Wrote a passport-2fa-totp package, which was similar to this, but had its own version of passport-local embedded as a hard-coded primary authentication strategy. I initially borrowed the google-authenticator.js file from this project, then ended up rewriting the register() function. Both the original library and my rewritten version implement portions of the KeyUriFormat specification.

License

The MIT License

Copyright (c) 2013 Jared Hanson <http://jaredhanson.net/>