Hapi-auth-jwt2 is a robust authentication scheme and plugin designed for Hapi.js applications, enabling secure user authentication through JSON Web Tokens (JWTs). The current stable version is 11.0.0. The project demonstrates an active release cadence, with recent version bumps addressing dependency updates, enhancing error handling, and implementing minor breaking changes to align with evolving ecosystem standards like ESLint. Its key differentiators include deep integration within the Hapi framework as a first-party plugin, a flexible `validate` function for custom user authentication logic, and support for advanced features such as 'try mode' and compatibility with multiple authentication strategies. The plugin prioritizes developer-friendliness, offering clear usage examples and comprehensive guidance on both Hapi.js and JWT fundamentals.
npm install hapi-auth-jwt2Verified import paths — ran on the pinned version, not inferred.
This quickstart demonstrates setting up a Hapi server with `hapi-auth-jwt2`. It includes a mock user database, a custom `validate` function to verify decoded JWTs, and registers the plugin. The example configures a 'jwt' authentication strategy, sets it as the default, and defines two routes: a public one and a restricted one. A `/login` route is also provided to issue a sample JWT, making the example fully runnable for testing authentication flow.
Ensure your Node.js environment and any custom build tools correctly resolve CommonJS modules. If you were directly importing internal plugin files, update their extensions to `.cjs`.
Update your `validate` function implementation and any consuming logic that accesses `request.auth.credentials` to expect and correctly process an object structure rather than a string. Consult the `hapi-auth-jwt2` documentation for the precise object format.
Execute `npm install jsonwebtoken --save` in your project's root directory to add it as a direct dependency.
Upgrade your Node.js runtime environment to version 18.0.0 or newer to ensure compatibility.
Upgrade `hapi-auth-jwt2` to at least version 5.1.0 to ensure proper interoperability with other Hapi authentication strategies. If upgrading is not feasible, carefully review and test the order and configuration of all authentication strategies.
Upgrade `hapi-auth-jwt2` to at least version 5.0.3 to benefit from the built-in crash prevention. Additionally, ensure your custom `validate` function includes its own defensive programming and error handling for `decoded` token integrity.
Ensure that `await server.register(require('hapi-auth-jwt2'));` is called and successfully awaited before any subsequent calls to `server.auth.strategy('jwt', 'jwt', { ... });` or route definitions that use the 'jwt' strategy.For restricted routes, ensure a valid JWT is included in the request headers as `Authorization: Bearer <your_token_here>`. Confirm that `server.auth.default('jwt');` is correctly configured or that `config.auth: 'jwt'` is explicitly set for the specific route.Verify the JWT string for correct formatting and check its expiration time. Crucially, ensure that the `key` (secret) and `verifyOptions` (e.g., `algorithms`) provided in your `server.auth.strategy` configuration precisely match the parameters used when the token was originally signed. If unsure, generate a new token.
Update your Hapi.js and `hapi-auth-jwt2` packages to their latest compatible versions. Reconfigure your `validate` function to be an `async` function that returns an object like `{ isValid: boolean, credentials?: object }`, instead of using a callback-based signature.