hapi — How to Set a Default Authentication Strategy

During the last two weeks, you’ve learned how to add the functionality of basic authentication with username and password to your hapi server and also remember your users with the help of cookies once they authenticated successfully so that they don’t need to provide their credentials on every visit.

Hapi handles both authentication methods as individual strategies and you can specify each one for routes to be applied. This guide will show you how to define a default authentication strategy in case you’ve multiple registered.

Before diving into the details, have a look at the series outline and find posts that match your interests and needs.

hapi Series Overview


At first, you have to prepare your hapi server. Let’s set up a basic hapi server that listens on localhost:3000 for incoming requests. Further, you’ll register the hapi-basic-auth plugin as an authentication strategy. This tutorial aims to provide you the fundamentals on how to set a default authentication strategy and it’s sufficient to just use a single one. No need to bloat this guide with irrelevant information.

const Hapi = require('hapi')

// create new server instance
const server = new Hapi.Server()

async function liftOff() {  
    plugin: require('hapi-auth-basic')

  // TODO: add authentication strategy
  // TODO: define default auth strategy

  // TODO: add routes

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


As you can see, the hapi-auth-basic plugin is registered to your server instance and if everything went fine, the server can be kicked off its socks to wait for connections (even though there’s no route available). Having the plugin registered successfully, you can go ahead and add the required authentication strategy.

Unfamiliar With Authentication in Hapi?

If you’re unfamiliar with the term “strategy” in the context of hapi authentication, please visit any of the mentioned guides related to basic and cookie based authentication. There, you’ll find the fundamentals required to get an overview on how hapi supports authentication to applications.

Register Authentication Strategy and Set as Default

The following code snippet illustrates the registration of a new default authentication strategy based on the previously registered basic auth plugin. Actually, the most import part is the third parameter within the server.auth.strategy(args) call. The third parameter is optional and depicts the strategy’s mode. It indicates whether the new strategy is default (true or 'required') or not (false, 'try', 'optional', just skip the parameter).

// Create auth strategy and set it as default
// all routes will automatically require and follow the default strategy
server.auth.strategy('simple', 'basic', true, { validateFunc: basicValidationFn })  

We’ll get into the details of strategy modes within a later tutorial. For now it’s important to know that you can set a default auth strategy at the same time of creating it.

Set Default Strategy Separately From Registration

Adding an authentication strategy doesn’t force you to decide and set it default or not. You can just leave the parameter empty to indicate it’s not the default strategy.

// Create auth strategy, without setting it as default
server.auth.strategy('simple', 'basic', { validateFunc: basicValidation })  

This way, you can register different authentication strategies and afterwards choose and set the default one. To define a default strategy, use server.auth.default('strategy-name') or create an authentication object like you would do on your route configuration. Let’s have a look at both options in the sections below.

Set Default by Strategy Name

You can set a default strategy straight forward by leveraging hapi’s server.auth.default('name') functionality. You need to provide a strategy name that’s actually registered to your server instance and available to be applied for the routes that will be added afterwards.

// set default auth strategy separately
// all routes added afterwards will follow the default, required auth strategy

Notice: setting a default authentication strategy requires you to previously create it with server.auth.strategy('simple', …).

Set Default by Object

Hapi provides a second way to configure a default authentication strategy, namely an object as you would provide for the auth configuration on a route. You’ve the options mode, strategy and payload (which explicitly defines payload authentication and requires a strategy with support for payload authentication, like Hawk).

The following code block outlines the config object to set simple as the default strategy.

var config = {  
  mode: true,
  strategy: 'simple',
  payload: false


What if I Set Two Default Strategies?

In short: hapi replaces the previously defined default strategy. If you didn’t have a default strategy defined before, it will become the default one.


In this example, the authentication strategy called cookie becomes the default one.

If you provide a strategy name that isn’t available and wasn’t created before, hapi will throw an error during server start.

What if My Routes Don’t Use the Default Strategy?

Actually, there’s a little detail you need to know about default strategies: if you set them via server.auth.default('name'), hapi will apply it only to routes added afterwards and those routes that don’t have an authentication configuration available.

In case you define a strategy as default at the same time of creating it (server.auth.strategy('name', 'scheme', true, options)), hapi applies it to every route already registered and those that will be added afterwards.


This guide walked you through the configuration of a default authentication strategy on your hapi server. Further, you’ve learned both ways of defining a default strategy: by name and configuration object. Please keep in mind that not all routes may use your default strategy, depending on the way and moment you’re setting the default auth.

We appreciate feedback and love to help you if there’s a question in your mind. Let us know in the comments or on twitter @futurestud_io.

Make it rock & enjoy coding!

Additional Resources

Explore the Library

Find interesting tutorials and solutions for your problems.