passport-otp-strategy/README.md

TOTP authentication strategy for Passport.

# Passport-OTP
<!-- ALL-CONTRIBUTORS-BADGE:START - Do not remove or modify this section -->
[![All Contributors](https://img.shields.io/badge/all_contributors-2-orange.svg?style=flat-square)](#contributors-)
<!-- ALL-CONTRIBUTORS-BADGE:END -->

[![npm](https://img.shields.io/npm/v/passport-otp-strategy.svg)](https://www.npmjs.com/package/passport-otp-strategy)
[![Build Status](https://secure.travis-ci.org/ejhayes/passport-otp.png)](http://travis-ci.org/ejhayes/passport-otp)

This is a fork of the [Passport-TOTP](https://github.com/jaredhanson/passport-totp) library and uses `otplib` instead of `notp`.

[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/)
and [Authy](https://authy.com/).

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-otp-strategy

## 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` used to verify the token value.  Authentication
fails if the value is not verified.

    passport.use(new OtpStrategy(
      {
        codeField: 'code',
        authenticator: {}
      }
      function(user, done) {
        TotpKey.findOne({ userId: user.id }, function (err, key) {
          if (err) { return done(err); }
          return done(null, key.key);
        });
      }
    ));

You can find a full listing of `authenticator` options [here](https://www.npmjs.com/package/otplib#available-options). Note that the `crypto` library will be used by default. If you want to change that, you can specify it in `authenticator.crypto` (more on that [here](https://www.npmjs.com/package/otplib#using-specific-otp-implementations)).

#### Authenticate Requests

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

For example, as route middleware in an [Express](http://expressjs.com/)
application:

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

## Examples

For a complete, working example, refer to the [two-factor example](https://github.com/ejhayes/passport-otp/tree/master/examples/two-factor). Please keep in mind that this example is not production ready as-is.

## Tests

    $ npm install
    $ make test

## Credits

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

## License

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

## Contributing

PRs are welcome!

## Contributors ✨

Thanks goes to these wonderful people ([emoji key](https://allcontributors.org/docs/en/emoji-key)):

<!-- ALL-CONTRIBUTORS-LIST:START - Do not remove or modify this section -->
<!-- prettier-ignore-start -->
<!-- markdownlint-disable -->
<table>
  <tr>
    <td align="center"><a href="https://github.com/ejhayes"><img src="https://avatars.githubusercontent.com/u/310233?v=4?s=100" width="100px;" alt=""/><br /><sub><b>Eric Hayes</b></sub></a><br /><a href="https://github.com/ejhayes/passport-otp/commits?author=ejhayes" title="Documentation">📖</a> <a href="#infra-ejhayes" title="Infrastructure (Hosting, Build-Tools, etc)">🚇</a> <a href="https://github.com/ejhayes/passport-otp/commits?author=ejhayes" title="Tests">⚠️</a> <a href="https://github.com/ejhayes/passport-otp/commits?author=ejhayes" title="Code">💻</a></td>
    <td align="center"><a href="http://craftycode.co.za/"><img src="https://avatars.githubusercontent.com/u/768925?v=4?s=100" width="100px;" alt=""/><br /><sub><b>Pieter Jordaan</b></sub></a><br /><a href="https://github.com/ejhayes/passport-otp/commits?author=Climax777" title="Code">💻</a></td>
  </tr>
</table>

<!-- markdownlint-restore -->
<!-- prettier-ignore-end -->

<!-- ALL-CONTRIBUTORS-LIST:END -->

This project follows the [all-contributors](https://github.com/all-contributors/all-contributors) specification. Contributions of any kind welcome!