hapi-auth-jwt2
Advanced tools
The 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/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/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 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', true,
{ key: 'NeverShareYourSecret', // Never Share your secret key
validateFunc: validate, // validate function defined above
verifyOptions: { algorithms: [ 'HS256' ] } // pick a strong algorithm
});
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.
key - (required) 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 clientcallback - callback function with the signature function(err, key, extraInfo) where:
err - an internal errorkey - the secret keyextraInfo - (optional) any additional information that you would like to use in
validateFunc which can be accessed via request.plugins['hapi-auth-jwt2'].extraInfovalidateFunc - (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.authorizationrequest - (required) is the original request received from the clientcallback - (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.verifyOptions - (optional) settings to define how tokens are verified by jsonwebtoken library
ignoreExpiration - ignore expired tokensaudience - do not enforce token audienceissuer - do not require the issuer to be validalgorithms - list of allowed algorithmsurlKey - (optional) 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 urlKeycookieKey - (optional) if you prefer to pass your token via a cookie, simply set the cookie token=your.jsonwebtoken.here or use a custom key by setting cookieKeyexample:
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
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
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 true and request.auth.credentials set to empty object
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
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.
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.
Several people requested the ability pass in JSNOWebTokens via request URL: https://github.com/dwyl/hapi-auth-jwt2/issues/19
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 generage 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;
@skota asked "How to generate secret key?" in: https://github.com/dwyl/hapi-auth-jwt2/issues/48
There are several options for generating secret keys. The easist way is to simply copy paste a strong random string of alpha-numeric characters from https://www.grc.com/passwords.htm (if you want a longer key simply refresh the page and copy-paste multiple random strings)
@benjaminlees
requested the ability to send tokens as cookies:
https://github.com/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:
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
}
replyThen, 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
npm install jsonwebtoken --save if you want to sign JWTs in your app.var JWT = require('./node_modules/hapi-auth-jwt2/node_modules/jsonwebtoken');If you have a question, please post an issue/question on GitHub: https://github.com/dwyl/hapi-auth-jwt2/issues
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!)
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
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"
We borrowed code from the following:
FAQs
Hapi.js Authentication Plugin/Scheme using JSON Web Tokens (JWT)
The npm package hapi-auth-jwt2 receives a total of 31,145 weekly downloads. As such, hapi-auth-jwt2 popularity was classified as popular.
We found that hapi-auth-jwt2 demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 0 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
Bybit's $1.46B hack by North Korea's Lazarus Group pushes 2025 crypto losses to $1.6B in just two months, already surpassing all of 2024's $1.49B total.
Security News
OpenSSF has published OSPS Baseline, an initiative designed to establish a minimum set of security-related best practices for open source software projects.
Security News
Michigan TypeScript founder Dimitri Mitropoulos implements WebAssembly runtime in TypeScript types, enabling Doom to run after processing 177 terabytes of type definitions.