Skip to content

Latest commit

 

History

History
126 lines (91 loc) · 5.78 KB

README.md

File metadata and controls

126 lines (91 loc) · 5.78 KB
Raw

passport-zero

A passwordless inspired strategy for passport

Build Status codecov npm version

This module allows authentication and authorization without passwords in your Node.js applications. It works by simply sending one-time password (OTPW) tokens via email (default) or other means. The module was inspired by @florianheinemann 's passwordless project. By plugging into Passport, zero authentication can be easily and unobtrusively integrated into any application or framework that supports Connect-style middleware, including Express.

Token-based authentication is...

  • Faster to implement compared to typical user auth systems (you only need one form)
  • Has a great UX for your users as they get started with your app quickly and don't have to remember passwords
  • Can be leveraged for private betas & similar by providing a single way to easily collect prospects
  • More secure for your users avoiding the risks of reused passwords

Getting you started

The following should provide a quick-start in using zero. If you need more details check out the example app. For anything you feel missing on this readme or on the example don't hesitate to open issues with comments and questions.

Install

$ npm install passport-zero

Usage

Configure Strategy

The zero authentication strategy authenticates users via a one-time password token sent via email ot other means:

const { Strategy, email } = require('passport-zero');

passport.use(
  new Strategy({              
    secret,
    deliver: email(smtpConfig)                    
  },
  email => db.users.findByEmail(email)
))
Available Options

This strategy, aside secret and deliver supports further options:

  • secret - Mandatory string, used to sign tokens
  • deliver - mandatory module, used to send tokens. You can use the bundled email helper to easily configure the email delivery.
  • storage - Optional, defaults to an in-memory storage. You can provide your own, especially for persistency reasons. Its API shuld consist in async get, set, and delete methods all returning promises. Check the default implementation for reference.
  • ttl - Optionals, defaults to 7days (in seconds), its used to set the token expiration.
Verify function

As a second parameter the constructor requires an async verify function which receives the credentials (email address in case of the default email deliver) submitted by the user. The function is in charge of verifying that the email is correct returning a promise with a user object, or false in case no user was found.

Authenticate Requests

Use passport.authenticate(), specifying the 'zero' strategy for two actions:

request token

In this situation the passport authenticate middleware will check for the correct parameters and send a token via the delivery system in case of success. By default, in the email deliver, it will look for the value 'email' in the body and the query (body can disabled by setting the option allowPost to false).

app.post('/auth/zero',
  passport.authenticate('zero', { action : 'requestToken' }), 
  (req, res) => res.redirect('/check-your-inbox')
);
accept token

In this situation (the default) the passport authenticate middleware will check for a token. By default, in the email deliver, it will look for the value 'token' in the body and the query (body can disabled by setting the option allowPost to false).

app.post('/auth/zero',
  passport.authenticate('zero'), 
  (req, res) => res.redirect('/profile')
);

Examples

Developers using the popular Express web framework can refer to an example as a starting point for their own web applications. For other examples or more advanced passport related feature, check the passport docs.

Advanced

Email deliver

The zero strategy comes with an email deliver configurator, allowing you to get up and running quickly with an email delivery system.

const { email } = require('passport-zero');

...
deliver: email({
  ...smtpConfig,
  ...options
})
...

Aside from the mandatory smtp configuration it accept some more options:

  • tokenField - Optional, defaults to token. The paramater used to look for the token during the acceptToken process and the parameter used to send the token via email. ie: hostname/?token=....

  • addressField - Optional, defaults to email. Used to define the parameter for the email during the requestToken process.

  • template - Optional function , defaults to an internal template. The function need to have the following signature: (user, token, tokenField, req) => ({to, from, subject, text}).

    • to - Optional, defaults to user.email if not overriden in template
    • from - Optional, defaults to smtpConfig.from if not ovverriden in template
    • subject - Mandatory
    • text - Mandatory

Custom deliver

If you want to implement your own deliver mechanism (sms, ...), the deliver module should have the following API shape:

{
  async send(user, token, req){},
  tokenField,
  addressField,
}