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/dwyl/learn-hapi
Other language documents:
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:
const Hapi = require('@hapi/hapi');
const people = { // our "users database"
1: {
id: 1,
name: 'Jen Jones'
}
};
// bring your own validation function
const validate = async function (decoded, request, h) {
// do your checks to see if the person is valid
if (!people[decoded.id]) {
return { isValid: false };
}
else {
return { isValid: true };
}
};
const init = async () => {
const server = new Hapi.server({ port: 8000 });
// include our module here ↓↓, for example, require('hapi-auth-jwt2')
await server.register(require('../lib'));
server.auth.strategy('jwt', 'jwt',
{ key: 'NeverShareYourSecret', // Never Share your secret key
validate // validate function defined above
});
server.auth.default('jwt');
server.route([
{
method: "GET", path: "/", config: { auth: false },
handler: function(request, h) {
return {text: 'Token not required'};
}
},
{
method: 'GET', path: '/restricted', config: { auth: 'jwt' },
handler: function(request, h) {
const response = h.response({text: 'You used a Token!'});
response.header("Authorization", request.headers.authorization);
return response;
}
}
]);
await server.start();
return server;
}
init().then(server => {
console.log('Server running at:', server.info.uri);
})
.catch(err => {
console.log(err);
});
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:
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
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):
That's it.
Now write your own validate with what ever checks you want to perform
on the decoded token before allowing the visitor to proceed.
key - (required - unless you have a customVerify function) the secret key (or array of potential keys)
used to check the signature of the token or a key lookup function with
signature async function(decoded) where:
decoded - the decoded but unverified JWT received from client{ key, extraInfo } where:
key - the secret key (or array of keys to try)extraInfo - (optional) any additional information that you would like to use in validate which can be accessed
via request.plugins['hapi-auth-jwt2'].extraInfovalidate - (required) the function which is run once the Token has been decoded with
signature async function(decoded, request, h) where:
decoded - (required) is the decoded and verified JWT received in the requestrequest - (required) is the original request received from the clienth - (required) the response toolkit.{ isValid, credentials, response } where:
isValid - true if the JWT was valid, otherwise false.credentials - (optional) alternative credentials to be set instead of decoded.response - (optional) If provided will be used immediately as a takeover response.errorMessage - (optional defaults to 'Invalid credentials') - the error message raised to Boom if the token is invalid (passed to errorFunc as errorContext.message)verifyOptions - (optional defaults to none) settings to define how tokens are verified by the
jsonwebtoken library
ignoreExpiration - ignore expired tokensaudience - do not enforce token audienceissuer - do not require the issuer to be validalgorithms - list of allowed algorithmsresponseFunc - (optional) function called to decorate the response with authentication headers before the response headers or payload is written where:
request - the request object.h- the response toolkit.errorFunc - (optional defaults to raising the error requested) function called when an error has been raised. It provides an extension point to allow the host the ability to customise the error messages returned. Passed in object follows the following schema:
errorContext - the error object.
errorContext.errorType - required the Boom method to call (eg. unauthorized)errorContext.message - required the message passed into the Boom method callerrorContext.schema - the schema passed into the Boom method callerrorContext.attributes - the attributes passed into the Boom method callerrorContext.error - the exception thrown (optional, if available)errorContext.token - the JWT provided, in string form (optional, if available)errorContext with all above non-optional fields defined.request - the request object.h- the response toolkit.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') - The lowercase name of an HTTP header to read the token from. To disable reading the token from a header, set this to false or ''.payloadKey - (optional defaults to 'token') - The lowercase name of an HTTP POST body to read the token from. To disable reading the token from a payload, set this to false or ''. Please note, this will not prevent authentication falling through to the payload method unless attemptToExtractTokenInPayload is falsetokenType - (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 verify callbacks (not validate)headless - (optional defaults to none) - set to an object containing the header part of the JWT token that should be added to a headless JWT token received. Token's with headers can still be used with this option activated. e.g { alg: 'HS256', typ: 'JWT' }attemptToExtractTokenInPayload - (optional defaults to false) - set to true to let the authenticate method fall through to the payload method for token extractioncustomExtractionFunc - (optional) function called to perform a custom extraction of the JWT where:
request - the request object.request object as request.auth.token,
in case you need it later on in the request lifecycle.
This feature was requested by @mcortesi in
hapi-auth-jwt2/issues/123At the simplest level this is the request flow through a Hapi App
using hapi-auth-jwt2:
example:
server.auth.strategy('jwt', 'jwt', true,
{ key: 'NeverShareYourSecret', // Never Share your secret key
validate: 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
validate: 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
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 https://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.from('<Your Base64 encoded secret key>', 'base64'), // Never Share your secret key
validate: validate, // validate function defined above
verifyOptions: { algorithms: [ 'HS256' ] } // only allow HS256 algorithm
});
This plugin supports authentication modes on routes.
required - requires JWT to be sent with every request
optional - if no JWT 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 JWT 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. 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 validate.
The key or value returned by the key lookup function can also be an array of keys to try. Keys will be tried until one of them successfully verifies the signature. The request will only be unauthorized if ALL of the keys fail to verify. This is useful if you want to support multiple valid keys (like continuing to accept a deprecated key while a client switches to a new key).
server.auth.strategy('jwt', 'jwt', true,
{ key: [ 'PrimareSecretKey', 'DeprecatedKeyStillAcceptableForNow' ],
validate: validate,
verifyOptions: { algorithms: [ 'HS256' ] }
});
Several people requested the ability pass in JSNOWebTokens in the requested URL: 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 generate/supply a valid tokens for this to work.
const JWT = require('jsonwebtoken');
const obj = { id:123,"name":"Charlie" }; // object/info you want to sign
const token = JWT.sign(obj, secret);
const url = "/path?token="+token;
What if I want to disable the ability to pass JWTs in via the URL? Set your
urlKeytofalseor ''. (added by @bitcloud: issue #146)
@skota asked "How to generate secret key?" in: dwyl/hapi-auth-jwt2/issues/48
There are several options for generating secret keys.
The easiest 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.
@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
@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:
Firstly set the options you want to apply to your cookie:
const 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
jsonwebtoken in my project?Q: Must I include the jsonwebtoken package in my project
[given that hapi-auth-jwt2 plugin already includes it] ? asked in
hapi-auth-jwt2/issues/32
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:
const 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.
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 verify
gives you complete control over the verification of the incoming JWT.
hapi-auth-jwt2 with glueSeveral people asked us if this plugin is compatible with
Hapi's "Server Composer" glue
The answer is Yes! For an example of how to do this, see @avanslaars code example: https://github.com/dwyl/hapi-auth-jwt2/issues/151#issuecomment-218321212
Asked by @SanderElias in hapi-auth-jwt2/issues/126
We store our JWT-based sessions in a Redis datastore and lookup the session (jti) for the given JWT during the validate (validation function) see:
https://github.com/dwyl/hapi-auth-jwt2-example/blob/791b0d3906d4deb256daf23fcf8f5021905abe9e/index.js#L25
This means we can invalidate the session in Redis and then reject a request that uses an "old" or invalid JWT. see:
https://github.com/dwyl/hapi-auth-jwt2-example/blob/791b0d3906d4deb256daf23fcf8f5021905abe9e/index.js#L25
@abeninskibede asked how to set all routes to use JWT Auth in hapi-auth-jwt2/issues/149
We tend to enable hapi-auth-jwt2 for all routes by setting the default strategy to 'jwt' (so its required for all endpoints) because most of the endpoints in our app require the person/user to be authenticated e.g:
server.auth.strategy('jwt', 'jwt', {
...
});
server.auth.default('jwt'); // so JWT auth is required for all routes
When you want a particular route to not require JWT auth you simply set config: { auth: false } e.g:
server.route({
method: 'GET',
path: '/login',
handler: login_handler, // display login/registration form/page
options: { auth: false } // don't require people to be logged in to see the login page! (duh!)
});
@traducer & @goncalvesr2 both requested how to redirect after failed Auth in hapi-auth-jwt2/issues/161 and hapi-auth-jwt2/issues/148 respectively
The hapi-error lets
you easily redirect to any url you define if the Auth check fails
(i.e. statusCode 401)
see:
https://github.com/dwyl/hapi-error#redirectredirecting-to-another-endpoint
(code examples there.)
For example:
If the request.auth.credentials object initially added to your / endpoint initial was:
{
userId: 1,
permission: 'ADMIN'
}
And you want to change the user's permission to SUPER_ADMIN.
Retrieve the initial session object added as a token to /
const session = request.auth.credentials;
Change the object
session.permission = 'SUPER_ADMIN';
Sign as a JWT token again
const token = JWT.sign(session, process.env.JWT_SECRET);
Reply as usual whilst re-adding the token to your original endpoint /
reply().state('token', token, { path: '/' }).redirect('/wherever');
An issue can arise when supporting users with JavaScript disabled when JWTs are too large to pass on query strings.
With JS disabled, tokens cannot be added to headers by using redirects from OAuth providers in to the consuming service.
Cloud providers will place limitations on URI lengths
OAuth services may not always sit on a sibling subdomain of the protected service negating the use of a secure cookie
The only way to pass a token in this case is to use either an HTML form with the token in a hidden field and a button with instructions for users to press the button if they have JS disabled and some JS that will submit the form automatically if it is enabled
To configure hapi-auth-jwt to support this scenario, you will need to adapt the following sample configuration
server.auth.strategy('jwt', 'jwt', {
key: 'NeverShareYourSecret',
// defining our own validate function lets us do something
// useful/custom with the decodedToken before reply(ing)
validate: (decoded, request) => true,
verifyOptions: { algorithms: [ 'HS256' ] }, // only allow HS256 algorithm
attemptToExtractTokenInPayload: true,
// using yar as a session cache to store tokens, see: https://github.com/hapijs/yar
customExtractionFunc: request => {
if (request.auth && request.auth.token) {
request.yar.set('token', request.auth.token)
return request.auth.token;
}
const token = request.yar.get('token');
if (token) {
return token;
}
}
});
The configuration above will still run the normal token extraction attempts for headers, cookies, query string parameters and custom extraction. However, if there is no token successfully extracted, it will attempt to extract one from POST request bodies
As the authentication phase of a HAPI request will apply scope protection before POST bodies are parsed, you will need to also define the route on which you will handle JWTs with no scope applied or the POST requests with JWT payloads will fail when you globally apply scope as part of your application
server.route([
{
method: 'POST',
path: '/',
handler: (request, response) => response.redirect('/home'),
config: {
auth: {
strategies: ['jwt'],
payload: 'required'
}
}
}
]);
This route will, when a JWT is posted failover from the authentication phase to the payload authentication phase, extract a JWT, store it in the YAR session cache and redirect the user to the /home path using a standard 302 response. When the handler for /home is JWT protected, the customExtractionFunc defined in the auth strategy will read the JWT from the users session cache and use it for authentication
verifyWhile most people using hapi-auth-jwt2 will opt for the simpler use case
(using a Validation Function validate - 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
JWT was signed using the JWT_SECRET (secret key).
If you prefer specifying your own verification logic instead of having a validate, simply define a verify instead when initializing the plugin.
verify - (optional) the function which is run once the Token has been decoded
(instead of a validate) with signature async function(decoded, request) where:
decoded - (required) is the decoded but unverified JWT received in the request.request - (required) is the original request received from the client{ isValid, credentials } where:
isValid - 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
https://github.com/dwyl/hapi-auth-jwt2/issues/120
Note: nobody has requested the ability to use both a
validateandverify. This should not be necessary because with averifyyou can incorporate your own custom-logic.
hapi-auth-jwt2 version 10.x.x is an optional upgrade
that includes a breaking change.
Several users of the plugin requested that the artifacts
returned on successful authentication be an Object instead of a String.
Sadly this is a breaking change, hence the new major release.
hapi-auth-jwt2 version 9.x.x is compatible with Hapi.js 19.x.x
which only supports Node.js 12+.
While hapi-auth-jwt2 version 9.0.0
does not have any code changes from v8.8.1
(so there should not be any need to update your code that uses this plugin),
we felt it was prudent to make it clear to people that Hapi.js
(the core framework) has
dropped support for Node.js 10
and people should treat this package
as no longer supporting the older versions of Node.
hapi-auth-jwt2 version 8.x.x
is compatible with Hapi.js version 17.x.x - 19.x.x
hapi-auth-jwt2 version 7.x.x is compatible with 16.x.x
15.x.x 14.x.x 13.x.x 12.x.x 11.x.x 10.x.x 9.x.x and 8.x.x
Hapi 17.x.x is a major rewrite that's why version 8.x.x
of the plugin is not backward compatible!
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
See: https://github.com/dwyl/hapi-login-example-postgres
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 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/main/api/lib
app.js registering the hapi-auth-jwt2 plugin: app.js#L13
telling app.js where to find our validate Function: app.js#L21
validate Function (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!)
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.
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 validate 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.
The name we wanted was taken. Think of our module as the "new, simplified and actively maintained version"
For more background on jsonwebtokens (JWTs) see our detailed overview: https://github.com/dwyl/learn-json-web-tokens
Securing Hapi Client Side Sessions: https://blog.liftsecurity.io/2014/11/26/securing-hapi-client-side-sessions
We borrowed code from the following:
(Ryan made a good start - however, when we tried to submit a pull request to improve (security) it was ignored for weeks ... an authentication plugin that ignores security updates in dependencies is a no-go for us; security matters!) If you spot any issue in hapi-auth-jwt2 please create an issue: https://github.com/dwyl/hapi-auth-jwt2/issues so we can get it resolved ASAP!
Aparently, .some people like it...:
FAQs
Hapi.js Authentication Plugin/Scheme using JSON Web Tokens (JWT)
The npm package hapi-auth-jwt2 receives a total of 28,039 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.
Research
Security News
Attackers used a malicious npm package typosquatting a popular ESLint plugin to steal sensitive data, execute commands, and exploit developer systems.
Security News
The Ultralytics' PyPI Package was compromised four times in one weekend through GitHub Actions cache poisoning and failure to rotate previously compromised API tokens.
Security News
Research
Socket researchers found a malicious Maven package impersonating the legitimate ‘XZ for Java’ library, introducing a backdoor for remote code execution.