2. Tutorials
  3. hapi - How to Fix „unknown authentication strategy“

hapi - How to Fix „unknown authentication strategy“

For web based applications, there are various authentication mechanisms available. To let your hapi server support a selected one, pick a plugin from the hapi ecosystem, provide the required configuration and you’re ready to go.

At some point, most of us hapi developers trap into an unknown authentication strategy <name> in <route-path> error and didn’t realize why this occurs.

Actually, the fix is kind of straight forward. Read on to get the details!

hapi Series Overview

  1. Get Your Server Up and Running
  2. v17 Upgrade Guide (Your Move to async/await)
  3. Become a Better Developer in 2018
  4. Become a Better Developer in 2017
  1. What You’ll Build
  2. Prepare Your Project: Stack & Structure
  3. Environment Variables and Storing Secrets
  4. Set Up MongoDB and Connect With Mongoose
  5. Sending Emails in Node.js
  6. Load the User’s Profile Picture From Gravatar Using Virtuals in Mongoose
  7. Implement a User Profile Editing Screen
  8. Generate a Username in Mongoose Middleware
  9. Displaying Seasons and Episodes for TV Shows with Mongoose Relationship Population
  10. Implementing Pagination for Movies
  11. Implement a Watchlist
  12. Create a Full Text Search with MongoDB
  1. Create a REST API with JSON Endpoints
  2. Update Mongoose Models for JSON Responses
  3. API Pagination for TV Shows
  4. Customize API Endpoints with Query Parameters
  5. Always Throw and Handle API Validation Errors
  6. Advanced API Validation With Custom Errors
  7. Create an API Documentation with Swagger
  8. Customize Your Swagger API Documentation URL
  9. Describe Endpoint Details in Your Swagger API Documentation
  10. 10 Tips on API Testing With Postman
  11. JWT Authentication in Swagger API Documentation
  12. API Versioning with Request Headers
  1. IP-Based Rate Limits (Part 1 of 7)
  2. Rate Limits for Routes (Part 2 of 7)
  3. Dynamic Rate Limits (Part 3 of 7)
  4. Render a “Rate Limit Exceeded” View (Part 4 of 7)
  5. Show “Rate Limit Exceeded” Error on Login (Part 5 of 7)
  6. Disable Rate Limiting (Part 6 of 7)
  7. Rate Limiter Refactoring & Cleanup (Part 7 of 7)
  1. API Login With Username and Password to Generate a JWT
  2. JWT Authentication and Private API Endpoints
  3. Refresh Tokens With JWT Authentication
  4. Create a JWT Utility
  5. JWT Refresh Token for Multiple Devices
  6. Check Refresh Token in Authentication Strategy
  7. Rate Limit Your Refresh Token API Endpoint
  8. How to Revoke a JWT
  9. Invalidate JWTs With Blacklists
  10. JWT Logout (Part 1/2)
  11. JWT “Immediate” Logout (Part 2/2)
  12. A Better Place to Invalidate Tokens
  13. How to Switch the JWT Signing Algorithm
  14. Roll Your Own Refresh Token Authentication Scheme
  15. JWT Claims 101
  16. Use JWT With Asymmetric Signatures (RS256 & Co.)
  17. Encrypt the JWT Payload (The Simple Way)
  18. Increase JWT Security Beyond the Signature
  19. Unsigned JSON Web Tokens (Unsecured JWS)
  20. JWK and JWKS Overview
  21. Provide a JWKS API Endpoint
  22. Create a JWK from a Shared Secret
  23. JWT Verification via JWKS API Endpoint
  24. What is JOSE in JWT
  25. Encrypt a JWT (the JWE Way)
  26. Authenticate Encrypted JWTs (JWE)
  27. Encrypted and Signed JWT (Nested JWT)
  28. Bringing Back JWT Decoding and Authentication
  29. Bringing Back JWT Claims in the JWT Payload
  1. How to Run Separate Frontend and Backend Servers Within a Single Project
  2. How to Use Server Labels
  3. How to Correctly Stop Your Server and Close Existing Connections
  1. Basic Authentication With Username and Password
  2. Authentication and Remember Me Using Cookies
  3. How to Set a Default Authentication Strategy
  4. Define Multiple Authentication Strategies for a Route
  5. Restrict User Access With Scopes
  6. Show „Insufficient Scope“ View for Routes With Restricted Access
  7. Access Restriction With Dynamic and Advanced Scopes
  8. hapi - How to Fix „unknown authentication strategy“
  9. Authenticate with GitHub And Remember the Login
  10. Authenticate with GitLab And Remember the User
  11. How to Combine Bell With Another Authentication Strategy
  12. Custom OAuth Bell Strategy to Connect With any Server
  13. Redirect to Previous Page After Login
  14. How to Implement a Complete Sign Up Flow With Email and Password
  15. How to Implement a Complete Login Flow
  16. Implement a Password-Reset Flow
  1. Views in hapi 9 (and above)
  2. How to Render and Reply Views
  3. How to Reply and Render Pug Views (Using Pug 2.0)
  4. How to Create a Dynamic Handlebars Layout Template
  5. Create and Use Handlebars Partial Views
  6. Create and Use Custom Handlebars Helpers
  7. Specify a Different Handlebars Layout for a Specific View
  8. How to Create Jade-Like Layout Blocks in Handlebars
  9. Use Vue.js Mustache Tags in Handlebars Templates
  10. How to Use Multiple Handlebars Layouts
  1. Extend Your Server Functionality With Plugins
  2. Create Your Own Custom Plugin
  3. How to Register Plugins for a Selected Server Instance
  4. hapi Plugin for Client Geo Location (by Future Studio 🚀)
  5. Increase Development Speed With Errors in the Browser or as JSON Response
  1. Route Handling and Drive Traffic to Your Server
  2. How to Serve Static Files (Images, JS, CSS, etc.)
  3. How to Use Query Parameters
  4. Optional Path Parameters
  5. Multi-Segment/Wildcard Path Parameters
  6. Ignore Trailing Slashes on Route Paths
  7. How to Fix “Unsupported Media Type”
  1. How to Access and Handle Request Payload
  2. Access Request Headers
  3. How to Manage Cookies and HTTP States Across Requests
  4. Detect and Get the Client IP Address
  5. How to Upload Files
  6. Quick Access to Logged In User in Route Handlers
  7. How to Fix “handler method did not return a value, a promise, or throw an error”
  8. How to Fix “X must return an error, a takeover response, or a continue signal”
  1. How to Reply a JSON Response
  2. How to Set Response Status Code
  3. How to Handle 404 Responses for Missing Routes
  1. Query Parameter Validation With Joi
  2. Path Parameter Validation With Joi
  3. Request Payload Validation With Joi
  4. Validate Query and Path Parameters, Payload and Headers All at Once on Your Routes
  5. Validate Request Headers With Joi
  6. Reply Custom View for Failed Validations
  7. Handle Failed Validations and Show Errors Details at Inputs
  8. How to Fix AssertionError, Cannot validate HEAD or GET requests
  1. Add CSRF Protection on Forms and API Endpoints
  1. Report Errors to Sentry
  2. Don’t Report Errors to Sentry in Development Mode
  3. Logging Fundamentals
  4. Log to Console With Good
  5. Log to File With Good
  1. Getting Started With Testing Using Lab and Code
  2. Run Tests with Assertions using Code
  3. Test Route Handlers by Injecting Requests
  4. Inject Request Payload, Headers and Parameters While Testing Route Handlers
  1. Zero-Downtime Deployments Using PM2

The Problem

Independent of your app’s authentication strategy, the following error stack trace probably feels familiar:

$ node server.js

/Users/marcuspoehls/Dev/JS/nodejs-tutorials-hapi/node_modules/hapi/node_modules/hoek/lib/index.js:736
    throw new Error(msgs.join(' ') || 'Unknown error');
    ^

Error: Unknown authentication strategy session in /  
    at Object.exports.assert (/Users/marcuspoehls/Dev/JS/nodejs-tutorials-hapi/node_modules/hapi/node_modules/hoek/lib/index.js:736:11)
    …

In essence, the defined authentication strategy called session is not available for the route with path /. Now you might think that you’re creating the session strategy in your project and hapi still can’t find it. So what’s the issue?

The Solution(s)

The actual problem is that the session strategy is created too late. A route that requires the session strategy is registered before session is known to the server.

Now that you know the problem (a strategy not created when the route with related authentication scheme should be registered), you can put your solution in place. Depending on your application setup, there are different approaches on how to implement the solution.

Create a Dedicated Authentication Plugin

Composing your application with individual plugins is the recommended way in hapi. If you’re already splitting the different parts of your apps into separate plugins, there’s a straightforward way to fix the problem: create a dedicated authentication plugin.

Create the Plugin

The following snippet illustrates the authentication plugin by using the hapi-auth-cookie dependency to create the session strategy.

Let’s name the following snippet authentication.js, so we can easily refer to it:

authentication.js

const Hoek = require('hoek')

async function register (server, options) {  
  // register dependency to hapi-auth-cookie
  // and make sure it’s available to this plugin
  await server.register({
    plugin: require('hapi-auth-cookie')
  })

  // configure the "session" strategy
  server.auth.strategy('session', 'cookie', {
    password: 'ThisIsASecretPasswordForTheAuthCookie',
    redirectTo: '/',
    isSecure: process.env.NODE_ENV === 'production'
  })
}

exports.plugin = {  
  register,
  name: 'authentication',
  version: '1.0.0',
  once: true
}

The code snippet above uses the hapi-auth-cookie module as a dependency. Also, this specific authentication plugin (see the plugin’s name attribute) registers its dependencies itself. Please make sure you don’t register the hapi-auth-cookie twice to your hapi server, then you’ll get an error.

Notice the once: true within the plugin’s attributes. This configuration tells hapi to register this plugin only once on the same server.

What about server.dependency?

Did you think about using server.dependency([ 'hapi-auth-cookie' ]) to declare the dependency between authentication and hapi-auth-cookie (or further plugins)?

Sadly, hapi doesn’t make sure that plugins are registered in order and therefore you need to make sure the hapi-auth-cookie plugin is definitely registered before authentication should be plugged into your server.

Now that you’ve set the dependency within your authentication plugin, go ahead and create the session strategy based on the cookie scheme. You need to do that within the callback function of server.register().

With the call of next(), hapi knows that your plugin is registered and the next one can be processed.

Use Authentication Plugin in Your App

In your plugins that require authentication and specifically the session strategy, register the authentication plugin (from the code block above) as a dependency.

The authentication plugin is your custom one (from the code block above, which we named authentication.js). Of course, you can name it whatever you want :)

Let’s name the following snippet your-plugin.js to get a reference within this tutorial.

your-plugin.js

async function register (server, options) {  
  await server.register([
    {
      register: require('./path/to/authentication')
    }
    {
      register: require('vision') // if you want view rendering support
    },
  ])

  // your plugin logic goes here
  // like "server.route(yourRoutes)"

  // tell hapi it’s safe to process the next plugin :)
}

Within your application plugins that rely on the authentication plugin as a dependency, make sure you install it. The once: true attribute of authentication makes sure hapi only registers the plugin once for the same server.

Having the dependencies installed, do your individual configuration, add routes, extend the request lifecycle, etc.

Register Plugins to Your Server

The dedicated authentication plugin is a requirement for other plugins. Individual plugins should make sure their dependencies are installed by doing it themselves.

That’s why you only need to register your “main” plugins and they individually handle their dependencies themselves.

const Hapi = require('hapi')  
const server = new Hapi.Server()

// register plugins to server instance
async function liftOff () {  
  server.register([
    {
      plugin: require('./path/to/your-plugin')
    },
    {
      plugin: require('./path/to/another-plugin')
    },
    {
      plugin: require('./path/to/the-fancy-funky-plugin')
    }
  ])

  try {
    await server.start()
    console.log('Server running at: ' + server.info.uri)
  } catch (err) {
    console.log(err)
    process.exit(1)
  }
}

liftOff()

Not Using Plugins: Ensure a Server Composition Flow

If you don’t compose your hapi app with individual plugins, make sure that you register the used plugins (e.g., vision, inert, etc.) first. Then create the authentication strategies, set the view configuration or do everything else you want to use in your routes.

Having the plugins registered, views configured or authentication in place, register all your routes to the hapi server instance. Adding the routes to the hapi server with (all batteries included) should go well.

Outlook

In this tutorial you’ve learned how to fix the actual problem for the „unknown authentication strategy“ error. This error occurs, because the given strategy is not available to the server yet while a route should be added and requires the strategy.

Solve this problem by creating a dedicated authentication plugin that can be defined as a dependency for your individual application plugins. If you don’t use plugins to compose your app, make sure your application flow follows the correct path of registering dependencies first, configure the authentication strategies and than add routes.

Want to learn more on how to access and handle the request payload in hapi? The linked tutorial is for you!

We’re happy to hear your thoughts and comments. Please don’t hesitate to use the comments below or find us on Twitter @futurestud_io. Let us know what you think!

Enjoy coding & make it rock!

Marcus Pöhls

Marcus is a fullstack JS developer. He’s passionate about the hapi framework for Node.js and loves to build web apps and APIs. Creator of Futureflix and the “learn hapi” learning path.

Explore the Library

Find interesting tutorials and solutions for your problems.

Android

Node.js

Server

Miscellaneous