{"id":16826,"library":"hapi-micro-auth","title":"Hapi Micro Auth Plugin","description":"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.","status":"abandoned","version":"4.0.1","language":"javascript","source_language":"en","source_url":"https://github.com/firstandthird/hapi-micro-auth","tags":["javascript","hapi","auth","authentication","micro-auth"],"install":[{"cmd":"npm install hapi-micro-auth","lang":"bash","label":"npm"},{"cmd":"yarn add hapi-micro-auth","lang":"bash","label":"yarn"},{"cmd":"pnpm add hapi-micro-auth","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Peer dependency as it's a Hapi plugin.","package":"@hapi/hapi","optional":false},{"reason":"Core runtime dependency for authentication logic.","package":"micro-auth","optional":false}],"imports":[{"note":"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.","wrong":"const hapiMicroAuth = require('hapi-micro-auth');","symbol":"hapiMicroAuth","correct":"import hapiMicroAuth from 'hapi-micro-auth';"},{"note":"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.","wrong":"import { getMe } from 'hapi-micro-auth';","symbol":"getMe","correct":"server.microauth.getMe(token);"},{"note":"Hapi plugin registration typically requires an object with `plugin` and `options` keys. The `await` keyword is crucial for asynchronous registration.","wrong":"server.register(hapiMicroAuth, { /* ... */ });","symbol":"plugin registration","correct":"await server.register({\n  plugin: hapiMicroAuth,\n  options: { /* ... */ }\n});"}],"quickstart":{"code":"import Hapi from '@hapi/hapi';\nimport hapiMicroAuth from 'hapi-micro-auth';\n\nconst init = async () => {\n  const server = Hapi.server({\n    port: 3000,\n    host: 'localhost'\n  });\n\n  await server.register({\n    plugin: hapiMicroAuth,\n    options: {\n      host: process.env.MICRO_AUTH_HOST ?? 'http://localhost:8081/auth', // URL to micro-auth service\n      routes: true, // Enable default auth routes (e.g., /login, /logout)\n      strategy: {\n        name: 'microauth',\n        mode: 'required' // 'required', 'optional', 'try'\n      },\n      cookie: {\n        name: 'auth_session',\n        isSecure: process.env.NODE_ENV === 'production',\n        ttl: 12960000000 // 150 days\n      }\n    }\n  });\n\n  server.route({\n    method: 'GET',\n    path: '/me',\n    handler: async (request, h) => {\n      try {\n        // Assuming 'microauth' is the strategy name from plugin options\n        const user = request.auth.credentials;\n        if (!user) {\n          return h.response('Not authenticated').code(401);\n        }\n        // Example of using a plugin method\n        const fullUser = await server.microauth.getMe(user.token);\n        return fullUser;\n      } catch (error) {\n        console.error('Error fetching user:', error);\n        return h.response('Internal Server Error').code(500);\n      }\n    },\n    options: {\n      auth: 'microauth' // Apply the authentication strategy\n    }\n  });\n\n  await server.start();\n  console.log(`Server running on ${server.info.uri}`);\n};\n\nprocess.on('unhandledRejection', (err) => {\n  console.log(err);\n  process.exit(1);\n});\n\ninit();","lang":"javascript","description":"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."},"warnings":[{"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.","message":"Version 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.","severity":"breaking","affected_versions":">=4.0.0"},{"fix":"Update any hardcoded references to the `/api/users/list` endpoint to `/api/users` or adjust the `routes.login` configuration in the plugin options.","message":"The 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.","severity":"breaking","affected_versions":">=3.7.1"},{"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').","message":"The `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.","severity":"gotcha","affected_versions":">=3.6.0"},{"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.","message":"The `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.","severity":"gotcha","affected_versions":">=3.0.0"}],"env_vars":null,"last_verified":"2026-04-22T00:00:00.000Z","next_check":"2026-07-21T00:00:00.000Z","problems":[{"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.","cause":"The plugin's options are invalid, or a required dependency (like `micro-auth` itself or a specific Hapi version) is missing or incompatible.","error":"Error: Plugin 'hapi-micro-auth' failed to register"},{"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.","cause":"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.","error":"TypeError: Cannot read properties of undefined (reading 'getMe')"},{"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.","cause":"Misconfiguration of `host`, `hostRedirect`, `redirectTo`, or cookie options (`name`, `isSecure`, `isSameSite`) resulting in incorrect communication with the micro-auth service or improper cookie handling.","error":"Authentication fails or redirects incorrectly (e.g., infinite redirect loops)"}],"ecosystem":"npm","meta_description":null}