# Passport-TOTP

[Passport](http://passportjs.org/) strategy for two-factor authentication using
a [TOTP](http://tools.ietf.org/html/rfc6238) 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](http://www.senchalabs.org/connect/)-style middleware,
including [Express](http://expressjs.com/).  TOTP values can be generated by
hardware devices or software applications, including [Google Authenticator](https://code.google.com/p/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.

## Install

    $ npm install passport-totp

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

The `setup` callback accepts a previously authenticated `user` and calls `done`
providing a `key` and `period` used to verify the HOTP value.  Authentication
fails if the value is not verified.

    passport.use(new TotpStrategy(
      function(user, done) {
        TotpKey.findOne({ userId: user.id }, function (err, key) {
          if (err) { return done(err); }
          return done(null, key.key, key.period);
        });
      }
    ));

#### Authenticate Requests

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

For example, as route middleware in an [Express](http://expressjs.com/)
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](https://github.com/jaredhanson/passport-totp/tree/master/examples/two-factor).

## Tests

    $ npm install
    $ make test

[![Build Status](https://secure.travis-ci.org/jaredhanson/passport-totp.png)](http://travis-ci.org/jaredhanson/passport-totp)

## Credits

  - [Jared Hanson](http://github.com/jaredhanson)

## License

[The MIT License](http://opensource.org/licenses/MIT)

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