kandado

Kandado is a simple token-based authentication middleware using jsonwebtoken made for ExpressJS. The name is a filipino word for 'lock'.

---

Install

$ npm install kandado --save

Setup

// Require module
const kandado = require('kandado')
 
// Initialize by setting the 'secret key'
let auth = kandado('aSecretKeyThatOnlyYouWhoKnows')

See jsonwebtoken for more information about secret key.

Usage

auth.required

// require express, body-parser, kandado, and other dependencies...
 
let app = express()
let auth = kandado('aSecretKeyThatOnlyYouWhoKnows')
 
// A public route, anyone can access
app.get('/', (req, res) => {
    res.send('Welcome to the API!')
})
 
// A private route, a valid token will be required either from GET or POST
app.get('/account', auth.required, (req, res) => {
    res.json({
        message: 'You are now authenticated!',
        userSessionData: req.authData
    })
})

The auth.required is a middleware that checks the HTTP GET or POST for the token variable. If its undefined, it will require a token thus redirects to requireToken middleware. Else, it will validate the given token.

If the given token is invalid, the route will redirect to the failedAuth middleware. Else, it will proceed to the route function and the decrypted data from the token is accessible at req.authData.

---

auth.generateToken(data[, tokenOptions])

// Authenticate a user and generate a valid token
app.post('/login', (req, res) => {
    // validate your user however you want
    if(username === true && password === true) {
        // if the user is authorized generate a valid token
        auth.generateToken({userSessionData}).then(token => {
            // return token to the client-side
            res.json({ 'access_token': token })
        })
    } else {
        res.send('User is not authorized.')
    }
})

The auth.generateToken() function accepts two parameters which is data or the payload to be encrypted and an optional tokenOptions to configure the generating of the token. See jsonwebtoken's jwt.sign() function for the complete options available.

This will return a promise with the token as the resolved value which is ideally to be sent back to the client.

Fallback Middlewares

requireToken

function (req, res, next) {
    res.json({ 'error': 'token_required' })
}

This middleware gets called when there is no token provided to the protected (auth.required) route. It returns a json {'error': 'token_required'}

failedAuth

function (req, res, next) {
    res.json({ 'error': 'token_invalid' })
}

This middleware gets called when the token is invalid or has already expired. It returns a json {'error': 'token_invalid'}

---

Protip: If you're going to override the fallback middlewares, detailed information of the error is accessible at req.authError.

---

Options

tokenExpiration

Default: '24h'

Set expiration of a generated token.

---

See jsonwebtoken's jwt.sign() function for the complete options available; and auth.generateToken() on how to apply them.

---

Protip: If you want to override the tokenExpiration option or the requireToken and failedAuth fallback middlewares, you can use the built-in config setter and getter.

Example:

/* tokenExpiration - see jsonwebtoken or zeit/ms for valid values
 * https://github.com/zeit/ms
 */
auth.set('tokenExpiration', '24h')
 
// requireToken
auth.set('requireToken', (req, res) => {
    res.json({
        'message': 'This is a modified requireToken middleware.',
        'moreErrorData': req.authError
    })
})
 
// failedAuth
auth.set('failedAuth', (req, res) => {
    res.json({
        'message': 'This is a modified failedAuth middleware.',
        'moreErrorData': req.authError
    })
})
 
// Random data you might need to keep and get
auth.set('kandado', 'is awesome!')
auth.get('kandado') //returns 'is awesome!'

---

Reference

• ExpressJS - https://github.com/expressjs/express
• jsonwebtoken - https://github.com/auth0/node-jsonwebtoken
• kandado-test (Sample Implementation) - https://github.com/jhon-andrew/kandado/tree/kandado-test