hapi-auth-jwt2

Hapi Auth with JSON Web Tokens (JWT)

The simplest authentication scheme/plugin for Hapi.js apps using JSON Web Tokens.

Usage

Install from NPM

npm install hapi-auth-jwt2 --save

Example

basic usage example to get started:

var Hapi = require('hapi');
var JWT  = require('jsonwebtoken');  // used to sign our content
var port = process.env.PORT || 8000; // allow port to be set

var secret = 'NeverShareYourSecret'; // Never Share!

var people = { // our "users databse"
    1: {
      id: 1,
      name: 'Anthony Valid User'
    }
};

// use the token as the 'authorization' header in requests
var token = JWT.sign(people[1], secret); // synchronous

// bring your own validation function
var validate = function (decoded, request, callback) {

    console.log(decoded);

    // do your checks to see if the person is valid
    if (!people[decoded.id]) {
      return callback(null, false);
    }
    else {
      return callback(null, true);
    }
};

var server = new Hapi.Server();
server.connection({ port: port });
        // include our module here ↓↓
server.register(require('hapi-auth-jwt2'), function (err) {

    if(err){
      console.log(err);
    }
    // see: http://hapijs.com/api#serverauthschemename-scheme
    server.auth.strategy('jwt', 'jwt', true,
    { key: secret,  validateFunc: validate });

    server.route([
      {
        method: "GET", path: "/", config: { auth: false },
        handler: function(request, reply) {
          reply({text: 'Token not required'});
        }
      },
      {
        method: 'GET', path: '/restricted', config: { auth: 'jwt' },
        handler: function(request, reply) {
          reply({text: 'You used a Token!'})
          .header("Authorization", request.headers.authorization);
        }
      }
    ]);
});

server.start();

Run the server with: node example/server.js

Now use curl to access the two routes:

No Token Required

curl -v http://localhost:8000/

Token Required

Try to access the /restricted content without supplying a Token (expect to see a 401 error):

curl -v http://localhost:8000/restricted

Now access the url using the following format: curl -H "Authorization: <TOKEN>" http://localhost:8000/restricted

A here's a valid token you can use (copy-paste this command):

curl -v -H "Authorization: eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpZCI6MSwibmFtZSI6IkFudGhvbnkgVmFsaWQgVXNlciIsImlhdCI6MTQyNTQ3MzUzNX0.KA68l60mjiC8EXaC2odnjFwdIDxE__iDu5RwLdN1F2A" \
http://localhost:8000/restricted

That's it.

Write your own validateFunc with what ever checks you want to perform on the decoded token before allowing the visitor to proceed.

Documentation

• validateFunc - (required) a the function which is run once the Token has been decoded signature function(decoded, request, callback) where:
  • decoded - (required) is the decoded JWT received from the client in request.headers.authorization
  • request - (required) is the original request received from the client
  • callback - (required) a callback function with the signature function(err, isValid) where:
    • err - an internal error.
    • valid - true if the JWT was valid, otherwise false.

---

Motivation

While making Time we want to ensure our app (and API) is as simple as possible to use.
This lead us to using JSON Web Tokens for Stateless Authentication.

We did a extensive research into existing modules that might solve our problem; there are many on NPM:

but they were invariably too complicated, poorly documented and had useless (non-real-world) "examples"!

Also, none of the existing modules exposed the request object to the validateFunc which we thought might be handy.

So we decided to write our own module addressing all these issues.

Don't take our word for it, do your own homework and decide which module you prefer.

Guiding Principal

"perfection is attained not when there is nothing more to add,
but when there is nothing more to remove" ~ Antoine de Saint-Exupéry

Why hapi-auth-jwt2 ?

The name we wanted was taken. Think of our module as the "new and simplified version"

Useful Links

For more background on JWT see our post: https://github.com/docdis/learn-json-web-tokens

Hapi.js Auth

We borrowed code from the following:

• http://hapijs.com/tutorials/auth
• https://github.com/hapijs/hapi-auth-basic
• https://github.com/hapijs/hapi-auth-cookie
• https://github.com/hapijs/hapi-auth-hawk
• https://github.com/ryanfitz/hapi-auth-jwt (good starting point)