The simplest authentication scheme/plugin for Hapi.js apps using JSON Web Tokens.
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/docdis/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/nelsonic/learn-hapi
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
npm install hapi-auth-jwt2 --save
This basic usage example should 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', true,
{ key: 'NeverShareYourSecret', // Never Share your secret key
validateFunc: validate // validate function defined above
});
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:
curl -v http://localhost:8000/
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.
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
- app.js registering the hapi-auth-jw2 plugin: app.js#L13
- telling app.js where to find our validateFunction: app.js#L21
- validateFunction (how we check the JWT is still valid): api/lib/auth_jwt_validate.js looks up the person's session in our ElasticSearch Database if the session record is found (valid) and not ended we allow the person to see the restricted content.
- Signing your JWTs: in your app you need a method to sign the JWTs (and put them in a database if that's how you are verifying your sessions) ours is: api/lib/auth_jwt_sign.js
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!)
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/docdis/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
validateFunc
- (required) a the function which is run once the Token has been decoded signaturefunction(decoded, request, callback)
where:decoded
- (required) is the decoded JWT received from the client in request.headers.authorizationrequest
- (required) is the original request received from the clientcallback
- (required) a callback function with the signaturefunction(err, isValid, credentials)
where:err
- an internal error.valid
-true
if the JWT was valid, otherwisefalse
.credentials
- (optional) alternative credentials to be set instead ofdecoded
.
While registering the hapi-auth-jwt2 plugin you can define the following verifyOptions:
ignoreExpiration
- ignore expired tokensaudience
- do not enforce token audienceissuer
- do not require the issuer to be validalgorithms
- list of allowed algorithms
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
});
Read more about this at: jsonwebtoken verify options
For security reasons you might want to specify the allowed algorithms you used when signing the tokens:
server.auth.strategy('jwt', 'jwt', true,
{ key: 'NeverShareYourSecret', // 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
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 withrequest.auth.isAuthenticated
set totrue
andrequest.auth.credentials
set to empty object -
try
- similar tooptional
but invalid Authorization header will pass withrequest.auth.isAuthenticated
set to false and failed credentials provided inrequest.auth.credentials
- 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 withnpm 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.
If you have a question, please post an issue/question on GitHub: https://github.com/dwyl/hapi-auth-jwt2/issues
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.
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'
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.
"perfection is attained not when there is nothing more to add,
but when there is nothing more to remove" ~ Antoine de Saint-Exupéry
The name we wanted was taken.
Think of our module as the "new, simplified and actively maintained version"
For more background on JWT see our post: https://github.com/docdis/learn-json-web-tokens
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
(Ryan has made a good starting point - we tried to submit a pull request
to improve it but got ignored ... an authentication plugin that ignores security updates in dependencies is a no-go for us; security matters!)