multipass-auth
v6.1.0
Published
An Express middleware that delivers an API for email/password authentication and registration
Downloads
24
Maintainers
Readme
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 setport
,host
, orsecure
.
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 ServicesProperty:
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 falseProperty:
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
- Property:
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 addressexp:
Token expiration (Default configuration is '24h'
)iat:
Issued at timeiss:
Issuer (Default configuration is 'multipass'
)