2. Tutorials
  3. hapi — How to Set a Default Authentication Strategy

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

  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

Preparation

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() {  
  server.register({
    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) {
    console.error(err)
    process.exit(1)
  }
}

liftOff()

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
server.auth.default('simple')

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
}

server.auth.default(config)

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.

server.auth.default('simple')  
server.auth.default('cookie')

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.

Outlook

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

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