Registry / auth-security / hapi-micro-auth

hapi-micro-auth

library4.0.1jsnpmunverified

hapi-micro-auth is a Hapi plugin designed to integrate with the micro-auth authentication service, exposing its functionalities as an authentication provider within a Hapi server. It handles session management, user retrieval, and authentication routes by proxying requests to a configured micro-auth instance. The current stable version is 4.0.1. The project appears to have an inactive release cadence, with its last major update (4.0.0) in late 2020. Key differentiators include its tight coupling with the firstandthird/micro-auth service, providing a specific solution for projects already leveraging that authentication backend. It offers methods to interact with user data, session updates, and metadata management via `server.microauth` methods.

auth-security

npm install hapi-micro-auth

github ↗package ↗

INSTALL

IMPORT

SIG · HAPI-MICRO-AUTH

hapi-micro-auth

auth-securityjavascriptv4.0.1

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

hapiMicroAuth

✓ import hapiMicroAuth from 'hapi-micro-auth';

✗ const hapiMicroAuth = require('hapi-micro-auth');

While the README shows `require('../')`, it's standard practice to import the package name. This package likely supports both CJS and ESM, but CJS `require` was shown in the documentation due to its age. For modern Node.js, ESM is preferred.

getMe

✓ server.microauth.getMe(token);

✗ import { getMe } from 'hapi-micro-auth';

Plugin methods like `getMe`, `getUser`, and `list` are exposed directly on the Hapi server instance under the `server.microauth` namespace after plugin registration, not as direct imports from the package.

plugin registration

✓ await server.register({ plugin: hapiMicroAuth, options: { /* ... */ } });

✗ server.register(hapiMicroAuth, { /* ... */ });

Hapi plugin registration typically requires an object with `plugin` and `options` keys. The `await` keyword is crucial for asynchronous registration.

This quickstart demonstrates how to set up a Hapi server, register the hapi-micro-auth plugin with essential configurations, and define a protected route that uses the 'microauth' strategy to retrieve user credentials.

import Hapi from '@hapi/hapi'; import hapiMicroAuth from 'hapi-micro-auth'; const init = async () => { const server = Hapi.server({ port: 3000, host: 'localhost' }); await server.register({ plugin: hapiMicroAuth, options: { host: process.env.MICRO_AUTH_HOST ?? 'http://localhost:8081/auth', // URL to micro-auth service routes: true, // Enable default auth routes (e.g., /login, /logout) strategy: { name: 'microauth', mode: 'required' // 'required', 'optional', 'try' }, cookie: { name: 'auth_session', isSecure: process.env.NODE_ENV === 'production', ttl: 12960000000 // 150 days } } }); server.route({ method: 'GET', path: '/me', handler: async (request, h) => { try { // Assuming 'microauth' is the strategy name from plugin options const user = request.auth.credentials; if (!user) { return h.response('Not authenticated').code(401); } // Example of using a plugin method const fullUser = await server.microauth.getMe(user.token); return fullUser; } catch (error) { console.error('Error fetching user:', error); return h.response('Internal Server Error').code(500); } }, options: { auth: 'microauth' // Apply the authentication strategy } }); await server.start(); console.log(`Server running on ${server.info.uri}`); }; process.on('unhandledRejection', (err) => { console.log(err); process.exit(1); }); init();

Debug

Known issues

breakingVersion 4.0.0 introduced dependency updates and configuration changes. While specific breaking changes are not explicitly detailed in the changelog, a major version bump indicates potential incompatibilities with previous Hapi or micro-auth versions.

fix

Review the dependency updates for Hapi and micro-auth specified in the `package.json` for v4.0.0 and ensure your project's versions are compatible. Test thoroughly after upgrading.

affects: >=4.0.0

breakingThe default login route was changed from `/api/users/list` to `/api/users` in version 3.7.1. Applications relying on the previous endpoint will need to update their routing logic.

fix

Update any hardcoded references to the `/api/users/list` endpoint to `/api/users` or adjust the `routes.login` configuration in the plugin options.

affects: >=3.7.1

gotchaThe `SameSite` cookie attribute was updated in version 3.6.0. This might affect how cookies are handled by browsers, especially in cross-site contexts, potentially leading to authentication issues if not configured correctly.

fix

Review the `sessionDateCookie.isSameSite` and `cookie.isSameSite` (if applicable) options within your plugin configuration. Ensure it aligns with your application's deployment strategy and browser `SameSite` policies (e.g., 'Lax', 'Strict', 'None').

affects: >=3.6.0

gotchaThe `getMe` method calls the `/me` API endpoint of micro-auth, returning information suitable for the authenticated user, whereas `getUser` retrieves more general user information. Using `getMe` for public display of user data might expose sensitive details.

fix

Always use `getUser(token)` when fetching user data intended for public display or general application use cases where sensitive user details should be omitted. Use `getMe(token)` only when full user profile data is explicitly required for the authenticated user.

affects: >=3.0.0

Errors

Common errors & fixes

Error: Plugin 'hapi-micro-auth' failed to register

The plugin's options are invalid, or a required dependency (like `micro-auth` itself or a specific Hapi version) is missing or incompatible.

fix

Verify that your `options` object for `hapi-micro-auth` aligns with the documented configuration, especially `host`. Ensure `@hapi/hapi` and `micro-auth` are installed and their versions are compatible with `hapi-micro-auth` v4.x.

TypeError: Cannot read properties of undefined (reading 'getMe')

The `hapi-micro-auth` plugin was not successfully registered with the Hapi server, or the `server.microauth` namespace is not available when attempting to access its methods.

fix

Ensure `await server.register({ plugin: hapiMicroAuth, options: { /* ... */ } });` is called and completes successfully before any routes or handlers try to access `server.microauth` methods. Check server startup logs for registration errors.

Authentication fails or redirects incorrectly (e.g., infinite redirect loops)

Misconfiguration of `host`, `hostRedirect`, `redirectTo`, or cookie options (`name`, `isSecure`, `isSameSite`) resulting in incorrect communication with the micro-auth service or improper cookie handling.

fix

Double-check the `host` option points to the correct `micro-auth` endpoint. If `hostRedirect` is used, ensure it's also correct. Verify `redirectTo` for proper login/logout flows. Pay close attention to `cookie.isSecure` in production and `cookie.isSameSite` for browser compatibility, especially if your Hapi server and micro-auth service are on different domains.

Upgrade

Version history

4.0.1latest on npm

Audit

Dependencies

@hapi/hapirequiredPeer dependency as it's a Hapi plugin.

micro-authrequiredCore runtime dependency for authentication logic.

Agent activity

15 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/firstandthird/hapi-micro-auth ↗

packagehttps://www.npmjs.com/package/hapi-micro-auth ↗