/hapi-auth-jwt2

:lock: Secure Hapi.js authentication plugin using JSON Web Tokens (JWT) in Headers, Query or Cookies

Primary LanguageJavaScriptISC LicenseISC

Hapi Auth using JSON Web Tokens (JWT)

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

hapi-auth-jwt2-diagram-verify

Build Status codecov.io Code Coverage Code Climate HAPI 13.4.1 Node.js Version npm

Dependency Status devDependency Status bitHound Score Join the chat at https://gitter.im/dwyl/chat

This node.js module (Hapi plugin) lets you use JSON Web Tokens (JWTs) for authentication in your Hapi.js web application.

If you are totally new to JWTs, we wrote an introductory post explaining the concepts & benefits: https://github.com/dwyl/learn-json-web-tokens

If you (or anyone on your team) are unfamiliar with Hapi.js we have a quick guide for that too: https://github.com/dwyl/learn-hapi

Usage

We tried to make this plugin as user (developer) friendly as possible, but if anything is unclear, please submit any questions as issues on GitHub: https://github.com/dwyl/hapi-auth-jwt2/issues

Install from NPM

npm install hapi-auth-jwt2 --save

Example

This basic usage example should help you get started:

var Hapi = require('hapi');

var people = { // our "users database"
    1: {
      id: 1,
      name: 'Jen Jones'
    }
};

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

    // 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: 8000 });
        // include our module here ↓↓
server.register(require('hapi-auth-jwt2'), function (err) {

    if(err){
      console.log(err);
    }

    server.auth.strategy('jwt', 'jwt',
    { key: 'NeverShareYourSecret',          // Never Share your secret key
      validateFunc: validate,            // validate function defined above
      verifyOptions: { algorithms: [ 'HS256' ] } // pick a strong algorithm
    });

    server.auth.default('jwt');

    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(function () {
  console.log('Server running at:', server.info.uri);
});

Quick Demo

Open your terminal and clone this repo:

git clone https://github.com/dwyl/hapi-auth-jwt2.git && cd hapi-auth-jwt2

Run the server with:

npm install && node example/server.js

Now (in a different terminal window) 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

or visit: http://localhost:8000/restricted in your web browser. (both requests will be blocked and return a 401 Unauthorized error)

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

or visit this url in your browser (passing the token in url):

http://localhost:8000/restricted?token=eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpZCI6MSwibmFtZSI6IkFudGhvbnkgVmFsaWQgVXNlciIsImlhdCI6MTQyNTQ3MzUzNX0.KA68l60mjiC8EXaC2odnjFwdIDxE__iDu5RwLdN1F2A

That's it.

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

Documentation

  • key - (required - unless you have a customVerify function) the secret key used to check the signature of the token or a key lookup function with signature function(decoded, callback) where:
    • decoded - the decoded but unverified JWT received from client
    • callback - callback function with the signature function(err, key, extraInfo) where:
      • err - an internal error
      • key - the secret key
      • extraInfo - (optional) any additional information that you would like to use in validateFunc which can be accessed via request.plugins['hapi-auth-jwt2'].extraInfo
  • validateFunc - (required) the function which is run once the Token has been decoded with signature function(decoded, request, callback) where:
    • decoded - (required) is the decoded and verified 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, credentials) where:
      • err - an internal error.
      • valid - true if the JWT was valid, otherwise false.
      • credentials - (optional) alternative credentials to be set instead of decoded.

Optional Parameters

  • verifyOptions - (optional defaults to none) settings to define how tokens are verified by the jsonwebtoken library
    • ignoreExpiration - ignore expired tokens
    • audience - do not enforce token audience
    • issuer - do not require the issuer to be valid
    • algorithms - list of allowed algorithms
  • responseFunc - (optional) function called to decorate the response with authentication headers before the response headers or payload is written where:
    • request - the request object.
    • reply(err, response)- is called if an error occurred
  • urlKey - (optional defaults to 'token') - if you prefer to pass your token via url, simply add a token url parameter to your request or use a custom parameter by setting urlKey. To disable the url parameter set urlKey to false or ''.
  • cookieKey - (optional defaults to 'token') - if you prefer to set your own cookie key or your project has a cookie called 'token' for another purpose, you can set a custom key for your cookie by setting options.cookieKey='yourkeyhere'. To disable cookies set cookieKey to false or ''.
  • headerKey - (optional defaults to 'authorization') - if you want to set a custom key for your header token use the headerKey option. To disable header token set headerKey to false or ''.
  • tokenType - (optional defaults to none) - allow custom token type, e.g. Authorization: <tokenType> 12345678.
  • complete - (optional defaults to false) - set to true to receive the complete token (decoded.header, decoded.payload and decoded.signature) as decoded argument to key lookup and verifyFunc callbacks (not validateFunc)

Understanding the Request Flow

At the simplest level this is the request flow through a Hapi App using hapi-auth-jwt2:

hapi auth request flow

verifyOptions let you define how to Verify the Tokens (Optional)

example:

server.auth.strategy('jwt', 'jwt', true,
{ key: 'NeverShareYourSecret', // Never Share your secret key
  validateFunc: validate,      // validate function defined above
  verifyOptions: {
    ignoreExpiration: true,    // do not reject expired tokens
    algorithms: [ 'HS256' ]    // specify your secure algorithm
  }
});

Read more about this at: jsonwebtoken verify options

Specify Signing Algorithm (Optional but highly recommended)

For security reasons it is recommended that you specify the allowed algorithms used when signing the tokens:

server.auth.strategy('jwt', 'jwt', true,
{ key: 'YourSuperLongKeyHere', // Never Share your secret key
  validateFunc: validate,      // validate function defined above
  verifyOptions: { algorithms: [ 'HS256' ] }  // only allow HS256 algorithm
});

If you prefer not to use any of these verifyOptions simply do not set them when registering the plugin with your app; they are all optional.

This feature was requested in: issues/29

Using Base64 encoded secret keys

Some authentication services (like Auth0) provide secret keys encoded in base64, To find out if your authentication service is one of these services, please try and experiment with the base64 encoded secret options on the validator at http://jwt.io/

If your key is base64 encoded, then for JWT2 to use it you need to convert it to a buffer. Following is an example of how to do this.

server.auth.strategy('jwt', 'jwt', true,
{ key: Buffer('<Your Base64 encoded secret key>', 'base64'), // Never Share your secret key
  validateFunc: validate,      // validate function defined above
  verifyOptions: { algorithms: [ 'HS256' ] }  // only allow HS256 algorithm
});

Authentication Modes

This plugin supports authentication modes on routes.

  • required - requires Authorization header to be sent with every request

  • optional - if no Authorization header is provided, request will pass with request.auth.isAuthenticated set to false and request.auth.credentials set to null

  • try - similar to optional but invalid Authorization header will pass with request.auth.isAuthenticated set to false and failed credentials provided in request.auth.credentials

Additional notes on key lookup functions

  • This option to look up a secret key was added to support "multi-tenant" environments. One use case would be companies that white label API services for their customers and cannot use a shared secret key. If the key lookup function needs to use fields from the token header (e.g. x5t header, set option completeToken to true.

  • The reason why you might want to pass back extraInfo in the callback is because you likely need to do a database call to get the key which also probably returns useful user data. This could save you another call in validateFunc.

URL (URI) Token

Several people requested the ability pass in JSNOWebTokens in the requested URL: dwyl/hapi-auth-jwt2/issues/19

Usage

Setup your hapi.js server as described above (no special setup for using JWT tokens in urls)

https://yoursite.co/path?token=your.jsonwebtoken.here

You will need to generate/supply a valid tokens for this to work.

var JWT   = require('jsonwebtoken');
var obj   = { id:123,"name":"Charlie" }; // object/info you want to sign
var token = JWT.sign(obj, secret);
var url   = "/path?token="+token;

What if I want to disable the ability to pass JWTs in via the URL? (asked by @bitcloud in issue #146) simply set your urlKey to something impossible to guess see: example

Generating Your Secret Key

@skota asked "How to generate secret key?" in: dwyl/hapi-auth-jwt2/issues/48

There are several options for generating secret keys. The easist way is to run node's crypto hash in your terminal:

node -e "console.log(require('crypto').randomBytes(256).toString('base64'));"

and copy the resulting base64 key and use it as your JWT secret. If you are curious how strong that key is watch: https://youtu.be/koJQQWHI-ZA

Want to access the JWT token after validation?

@mcortesi requested the ability to access the (raw) JWT token used for authentication. dwyl/hapi-auth-jwt2/issues/123

You can access the extracted JWT token in your handler or any other function within the request lifecycle with the request.auth.token property.

Note that this is the encoded token, and it's only useful if you want to use to make request to other servers using the user's token.

The decoded version of the token, accessible via request.auth.credentials

Want to send/store your JWT in a Cookie?

@benjaminlees requested the ability to send/receive tokens as cookies: dwyl/hapi-auth-jwt2/issues/55 So we added the ability to optionally send/store your tokens in cookies to simplify building your web app.

To enable cookie support in your application all you need to do is add a few lines to your code:

Cookie Options

Firstly set the options you want to apply to your cookie:

var cookie_options = {
  ttl: 365 * 24 * 60 * 60 * 1000, // expires a year from today
  encoding: 'none',    // we already used JWT to encode
  isSecure: true,      // warm & fuzzy feelings
  isHttpOnly: true,    // prevent client alteration
  clearInvalid: false, // remove invalid cookies
  strictHeader: true   // don't allow violations of RFC 6265
}

Set the Cookie on your reply

Then, in your authorisation handler

reply({text: 'You have been authenticated!'})
.header("Authorization", token)        // where token is the JWT
.state("token", token, cookie_options) // set the cookie with options

For a detailed example please see: https://github.com/nelsonic/hapi-auth-jwt2-cookie-example

Background Reading

Frequently Asked Questions (FAQ)

  1. Do I need to include jsonwebtoken in my project? asked in hapi-auth-jwt2/issues/32 Q: Must I include the jsonwebtoken package in my project [given that hapi-auth-jwt2 plugin already includes it] ? A: Yes, you need to manually install the jsonwebtoken node module from NPM with npm install jsonwebtoken --save if you want to sign JWTs in your app. Even though hapi-auth-jwt2 includes it as a dependency your app does not know where to find it in the node_modules tree for your project. Unless you include it via relative path e.g: var JWT = require('./node_modules/hapi-auth-jwt2/node_modules/jsonwebtoken'); we recommend including it in your package.json explicitly as a dependency for your project.

  2. Can we supply a Custom Verification function instead of using the JWT.verify method? asked by both Marcus Stong & Kevin Stewart in issue #120 and issue #130 respectively. Q: Does this module support custom verification function or disabling verification? A: Yes, it does now! (see: "Advanced Usage" below) the inclusion of a verifyFunc gives you complete control over the verification of the incoming JWT.

Advanced/Alternative Usage => Bring Your Own verifyFunc

While most people using hapi-auth-jwt2 will opt for the simpler use case (using a Validation Function validateFunc - see: Basic Usage example above - which validates the JWT payload after it has been verified...) others may need more control over the verify step.

The internals of hapi-auth-jwt2 use the jsonwebtoken.verify method to verify if the JTW was signed using the JWT_SECRET (secret key).

If you prefer specify your own verification steps instead of having a validateFunc simply define a verifyFunc instead while you are initializing the plugin.

  • verifyFunc - (optional) the function which is run once the Token has been decoded (instead of a validateFunc) with signature function(decoded, request, callback) where:
    • decoded - (required) is the decoded and verified 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, credentials) where:
      • err - an internal error.
      • valid - true if the JWT was valid, otherwise false.
      • credentials - (optional) alternative credentials to be set instead of decoded.

The advantage of this approach is that it allows people to write a custom verification function or to bypass the JWT.verify completely. For more detail, see: use-case discussion in dwyl#120

Note: nobody has requested the ability to use both a validateFunc and verifyFunc. This should not be necessary because with a verifyFunc you can incorporate your own custom-logic.


Compatibility

hapi-auth-jwt2 is compatible with Hapi.js versions 11.x.x 10.x.x 9.x.x and 8.x.x as there was no change to how the Hapi plugin system works for the past two versions. See the release notes for more details:

However in the interest of security/performance we recommend using the latest version of Hapi.

If you have a question, or need help getting started please post an issue/question on GitHub: https://github.com/dwyl/hapi-auth-jwt2/issues or Join the chat at https://gitter.im/dwyl/chat



Production-ready Examples?

Using PostgreSQL?

See: https://github.com/dwyl/hapi-login-example-postgres

Using Redis

Redis is perfect for storing session data that needs to be checked on every authenticated request.

If you are unfamiliar with Redis or anyone on your team needs a refresher, please checkout: https://github.com/dwyl/learn-redis

The code is at: https://github.com/dwyl/hapi-auth-jwt2-example and with tests. please ask additional questions if unclear!

Having a more real-world example was seconded by @manonthemat see: hapi-auth-jwt2/issues/9

Real World Example ?

If you would like to see a "real world example" of this plugin in use in a production web app (API) please see: https://github.com/dwyl/time/tree/master/api/lib

If you have any questions on this please post an issue/question on GitHub: https://github.com/dwyl/hapi-auth-jwt2/issues (we are here to help get you started on your journey to hapiness!)


Contributing contributions welcome

If you spot an area for improvement, please raise an issue: https://github.com/dwyl/hapi-auth-jwt2/issues Someone in the dwyl team is always online so we will usually answer within a few hours.

Running the tests requires environment variables

The "real world example" expects to have two environment variables: JWT_SECRET and REDISCLOUD_URL.

Ask @nelsonic for a valid Redis Cloud url (...we cannot publish the real one on GitHub...)

export JWT_SECRET='ItsNoSecretBecauseYouToldEverybody'
export REDISCLOUD_URL='redis://rediscloud:OhEJjWvSgna@pub-redis-1046.eu-west-1-2.1.ec2.garantiadata.com:10689'

tl;dr

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: npm search for hapi+jwt

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.

Why hapi-auth-jwt2 ?

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

Useful Links

Hapi.js Auth

We borrowed code from the following: