DO NOT USE: Work in Progress

TO DO:

• [X] Update documentation to reflect required configuration options
• [X] Review json responses to each endpoint (error and success)
  Verified API documentation accurately reflects error and response messages
• [ ] Provide example email screenshot
• [ ] Refactor to send JWT via cookie (in addition to being able to send on header)
• [X] Add new routes and corresponding requirements/responses
  Added /changepassword, /forgotpassword
• [ ] Provide example implementation (use AngularJS or React for frontend example)
• [ ] Add tests for helper utilities (mailer, tokenApi)

Synopsis

The multipass-auth middleware works in your existing Express app and adds routes to a base path you specify and utilizes jwts(JSON web tokens) to perform the authorization functionality. This is designed to work with single-page applications where your express app is only servicing the index page. You can use Angular, React, JQuery, etc to POST and verify login credentials on the routes this middleware provides.

Installation

To get started, install the below dependencies if you're starting fresh.
express >= v.4.14.0
body-parser >= v.1.15.2
mongoose >= v.4.7.2

npm install multipass-auth express body-parser mongoose --save

Otherwise you can just install multipass-auth and require it in your existing Express.js app.
Your Express app will need to be configured with the body-parser middleware as well as Mongoose for your MongoDB ORM

Usage

Example implementation:

// options.js
  modules.export = {
    loginRoute: '/logmein',
    registerRoute: '/signup',
    tokenSecret: '$0m3L0ngT0k3n$tr!ng',
    tokenExpiration: '24h',
    payload: {
      iss: 'YourSweetApp'
    }
  }

// app.js
const express = require('express')
const bodyParser = require('body-parser')
const mongoose = require('mongoose')
const options = require('./options') // importing configs here

// Require multipass and pass your configuration
// Any parameters not set will use the built-in defaults
const multipassAuth = require('multipass-auth')
multipassAuth.init(options)

// Initialize your express app
const app = express()

// Setup your mongoDB connection via mongoose
mongoose.connect('your_mongodb_connection_here')
mongoose.connection.on('connected', function () {
  console.log('Mongoose default connection opened')
})

// Setup your middleware
app.use(bodyParser.urlencoded({extended: false}))
app.use(bodyParser.json())

// Attach multipass-auth to your middleware stack
app.use('/auth', multipassAuth.router)

// Index route
app.get('/', (req, res) => {
  res.send('Index response')
})
// Start your server
app.listen(3000, console.log('Listening on localhost:3000'))

Default Configuration

Below is the default configuration object that multipass-auth uses if you don't provide any config options to multipassAuth.init()
Any null field is a required field with the following exception:

• If you set a valid service value, you do NOT need to set port, host, or secure.
  Note: The valid mail services are provided by the nodemailer project. You can find the list of valid services here.
  https://nodemailer.com/smtp/well-known/

// multipass default config.js
const config = {
  appUrl: null,
  tokenSecret: null
  loginRoute: '/login',
  registerRoute: '/register',
  verifyRoute: '/verify',
  changePasswordRoute: '/changepassword',
  forgotPasswordRoute: '/forgotpassword',
  forgotPasswordErrorRoute: null,
  forgotPasswordSuccessRoute: null,
  tokenExpiration: '24h',
  payload: {
    iss: 'multipass'
  },
  mailer: {
    service: null,
    port: null,
    host: null,
    secure: null,
    auth: {
      username: null,
      password: null
    }
  },
  message: {
    from: null,
    subject: 'Forgot password',
    html: null
  }
}

Now for an example minimum config you could pass:

// minimum_required_config.js
const config = {
  appUrl: "https://mynewapp.com",
  tokenSecret: 'yoursupersecrethere',
  forgotPasswordErrorRoute: '/route/to/handle',
  forgotPasswordSuccessRoute: '/success/forgotpassword',
  mailer:{
    port: 465,
    host: 'smtp.myprovider.com',
    secure: true,
    auth:{
      username: 'yourusername',
      password: 'yourpassword'
    }
  },
  message:{
    from: 'AdminGuy',
    html: '<p>You are receiving this email because you forgot your password for SweetNewApp. Please follow the instructions below </p>'
  }
}

Options

Required properties:

All required properties have a default null value. Multipass-Auth checks for null values and will throw an error if any configuration options are null

Property: appUrl
Description: Provide the root url of your applications. For example, http://sweetnewapp.com or http://localhost:3000. This will be used to construct the link in the forgotpassword email.

So if you set appUrl to http://myapp.com and verifyRoute to /verifyMe, the forgotpassword reset link will look like this (the token string was shortend for example purposes):
http://myapp.com/verifyMe?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJtdWx0aXBhc3MiLCJlbW

Property: tokenSecret
Description: The secret string used to sign the json web tokens (jwt).

Property: forgotPasswordErrorRoute
Description: This route will be used after a user clicks the forgot password link in their email and the token verification fails. You will want to display an error page for this route.

Property: forgotPasswordSuccessRoute
Description: This route will be used after a user clicks the forgot password link in their email and the token verification succeeds. You will want to display a password change form on this route with an action to post to the /changepassword endpoint.

Property: mailer
Description: This object contains the properties necessary for configuring nodemailer, which is what powers the forgotpassword email process.

• Property: mailer.service
  Description: Can be set to the name of a well-known service so you don’t have to input the port, host, and secure options. See Well-known Services

• Property: mailer.port
  Description: The port to connect to (defaults to 587 if secure is false or 465 if true)

• Property: mailer.host
  Description: The hostname or IP address to connect to (defaults to ‘localhost’)

• Property: mailer.secure
  Description: If true the connection will use TLS when connecting to server. If false (the default) then TLS is used if server supports the STARTTLS extension. In most cases set this value to true if you are connecting to port 465. For port 587 or 25 keep it false

• Property: mailer.auth
  Description: This is the authentication object expecting the following properties:

  • Property: mailer.auth.username
    Description: Username for provided SMTP service settings
  • Property: mailer.auth.password
    Description: Password for provided SMTP service settings

Optional properties

Property: loginRoute
Default value: /login

Property: registerRoute
Default value: /register

Property: verifyRoute
Default value: /verify

Property: changePasswordRoute
Default value: /changepassword

Property: forgotPasswordRoute
Default value: /forgotpassword

Property: tokenExpiration
Default value: 24h
Description: Other examples for time values are "2 days", "7d", and "1h"
Additional information here: https://github.com/zeit/ms

Property: payload
Default value: {iss: 'multipass'}

Property: message
Default value: Object
Description: This object contains the following configurable properties:

• Property: subject
  Default value: "Forgot password"

API

Route Documentation:

Detailed API documentation is available on SwaggerHub - https://swaggerhub.com/apis/byKirby/multipass-auth/1.0.0

Basics:

| Route | Method | Parameters |
|-------|--------|----------- | |/login| POST| {email: '[email protected]', password: 'abcd1234} | |/register| POST| {email: '[email protected]', password: 'abcd1234} |
|/forgotpassword| POST | {email: '[email protected]'} | |/changepassword| POST | {token: 'this_will_be_a_really_long_string', currentPassword: 'abcd1234,newPassword: 'brandNew'}| |/verify | POST| Token can be provided in header: x-access-token: 'long_token_string' Or Token can be provided in a url query http://mysite.com/?token=token_string |

Responses

All endpoints are configured to respond with at least the following properties:

// Example of hitting the /login endpoint with incorrect credentials
{ 
"result": "failure" // will be failure or success
"message": "Invalid credentials" //status message depending on the endpoint
}

Example implementation

Coming soon(ish)...

Token properties (only visible when decoded by the verify procedure)

email: User's email address
exp: Token expiration (Default configuration is '24h')
iat: Issued at time
iss: Issuer (Default configuration is 'multipass')