npm package: @honzahommer/passport-totp
Description: TOTP authentication strategy for Passport.
Author: Jared Hanson
Latest version: 0.0.4

# Passport-TOTP

[![npm Package](https://img.shields.io/npm/v/@honzahommer/passport-totp.svg)](https://www.npmjs.org/package/@honzahommer/passport-totp)
[![License](https://img.shields.io/npm/l/@honzahommer/passport-totp.svg)](https://github.com/honzahommer/passport-totp/blob/master/LICENSE)
[![build status](https://img.shields.io/travis/honzahommer/passport-totp/master.svg)](http://travis-ci.org/honzahommer/passport-totp)
[![downloads per month](http://img.shields.io/npm/dm/@honzahommer/passport-totp.svg)](https://www.npmjs.org/package/@honzahommer/passport-totp)
[![Greenkeeper badge](https://badges.greenkeeper.io/honzahommer/passport-totp.svg)](https://greenkeeper.io/)

> [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 @honzahommer/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/honzahommer/passport-totp/tree/master/examples/two-factor).

    $ git clone https://github.com/honzahommer/passport-totp.git
    $ cd passport-totp/examples/two-factor
    $ npm install
    $ npm start

## Tests

    $ npm install
    $ make test

## Credits

  - [Jared Hanson](http://github.com/jaredhanson)
  - [Honza Hommer](http://github.com/honzahommer)
  - [Clark Wang](http://github.com/clarkorz)
  - [Tomasz Sobczak](http://github.com/codename-)

## License

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

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