hapi-login-payload

Login via POST payload values submitted by a standard html form - progressive enhancement.

Lead Maintainer: Nelson

Why?

Login should be simple.

What?

Most login forms send data to a server using the POST method; some apps send data the "traditional" way while others send via "ajax"... In Hapi this data is available in the request.payload.
This tiny plugin simplifies setting up a "simple" /login route which you can POST to using a form in your hapi.js based app/api.

How?

We have tried to make this as simple as possible, but if you have any questions,
please ask and/or

1. Install from NPM

First install the hapi-register plugin (and Joi) from npm and save as a dependency:

npm install hapi-login-payload joi --save

### 2. Specify the fields required for login

In general most login forms will require an email address and a password:

var Joi = require('joi');
var custom_fields = {
  email     : Joi.string().email().required(), // Required
  password  : Joi.string().required().min(6)   // minimum length 6 characters
}

Note: If you want/need to define any additional/cusotm fields, simply add them to your fields object.
(as always, if you have any questions, ask!)

3. Define

• validateFunc - (required) a user lookup and password validation function with the signature function(request, email, password, callback) where:
  • request - is the hapi request object of the request which is being authenticated.
  • email - the email address received from the client.
  • password - the password received from the client.
  • callback - a callback function with the signature function(err, isValid, credentials) where:
    • err - an internal error.
    • isValid - true if both the username was found and the password matched, otherwise false.
    • credentials - a credentials object passed back to the application in request.auth.credentials. Typically, credentials are only included when isValid is true, but there are cases when the application needs to know who tried to authenticate even when it fails (e.g. with authentication mode 'try').

var Bcrypt = require('bcrypt');

var user = {
    email: '[email protected]',
    password: '$2a$10$iqJSHD.BGr0E2IxQwYgJmeP3NvhPrXAeLSaGCj6IR/XU5QtjVu5Tm',   // 'secret'
    name: 'John Doe ',
    id: '2133d32a'
};

var validate = function (request, email, password, callback) {

    if (!user) {
        return callback(null, false);
    }

    Bcrypt.compare(password, user.password, function (err, isValid) {

        callback(err, isValid, { id: user.id, name: user.name });
    });
};

server.register(require('hapi-auth-payload'), function (err) {

    server.auth.strategy('simple', 'basic', { validateFunc: validate });
    server.route({ method: 'GET', path: '/', config: { auth: 'simple' } });
});

Frequently Asked Questions

Q: What are the advantages of authenticating using the payload rather than request header? see: #1
A: it makes writing apps simpler. instead of having perform the 4 steps listed in the Notes section (below)
this plugin lets apps use a simple - progressive enhancement - approach: a basic html form.

Notes:

We were using hapi-auth-basic for our projects, while there's nothing "wrong" with that plugin,
we feel there is one too many steps involved. Specifically: hapi-auth-basic requires the username
and password be sent in the request.header as a Base64-encoded string.

There are four steps involved in preparing the auth request to hapi-auth-basic:

1. Get values for username and password from the form.
2. Encode the values as Base64:

var header = "Basic " + (new Buffer(email + ':' + password, 'utf8')).toString('base64');

3. Attach the auth header to the request you are about to send to the Server
4. Send the POST request to the server.

We thought this was too many steps and not very beginner-friendly.
So we removed the first 3 steps and use a simple html form with a POST action.

if you know (or can think of) a simpler way of doing this, please tell us!