2. Tutorials
  3. hapi — Basic Authentication With Username and Password

hapi — Basic Authentication With Username and Password

Building web apps is often coupled with user handling which is mostly combined with authentication via username and password. Each user should be identifiable with its own credentials and, you know, the common practice throughout the web that makes use of basic authentication. This tutorial will guide you through the setup of your hapi server to add the functionality of basic authentication with username and password.

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

Authentication in Hapi

The concept of authentication in hapi is based on schemes and strategies. Picture yourself that schemes are general types of authentication like basic or digest. In reference, a strategy is the actual named instance or implementation of an authentication scheme. We’ll dive deeper into the general topic of authentication within hapi later within this series and explain more details on a practical example by implementing our own custom strategy.

As of now, it’s important to know that hapi uses a scheme and strategy mechanism for authentication.

Basic Authentication With Hapi

You may have suggested that we won’t implement the functionality for basic authentication all by ourselves. There’s already a plugin called hapi-auth-basic that is actively maintained and does its job very well.

At first, add hapi-auth-basic as a project dependency and install it. You can combine both steps by executing the following snippet within your command line:

npm i -S hapi-auth-basic

Now that you have the plugin for basic auth installed, go ahead and register it to your hapi server instance and afterwards define it as an available authentication mechanism.

const Hapi = require('hapi')  
const BasicAuth = require('hapi-auth-basic')

const server = new Hapi.Server()

async function liftOff () {  
  await server.register({
    plugin: require('hapi-auth-basic')
  }

  server.auth.strategy('simple', 'basic', {
    validate: async (request, username, password) => {
      // TODO
    }
  })
}

liftOff()

We assume you’re familiar with hapi plugins and how to install them. If not, follow our tutorial on extending your hapi server’s functionalities with plugins within this hapi series and get a fundamental understanding.

Register the hapi-auth-basic plugin using server.register(require('hapi-auth-basic')).

Internally, the plugin defines a new scheme named basic to your hapi server by calling server.auth.scheme(). By now, you’re able to make use of this scheme and create a strategy that is based on the recently added basic scheme. Hopefully this abstract context will make sense for you in a second :)

To create an authentication strategy for your hapi server, leverage the server.auth.strategy(name, scheme, options) function that expects three (optionally four) parameters:

  1. name: your strategy name that will be used throughout your app
  2. scheme: the scheme name on which the strategy is based upon (e.g. basic)
  3. options: additional options

Within the code snippet above, you can see that the basic scheme is used to create a new strategy called simple. You could use the same name for strategy and scheme. For this tutorial, it’s a lot easier to keep context when choosing different names.

Hapi Basic Authentication — Options

The following list outlines available options to customize the behavior of hapi-auth-basic:

  • validateFunc: a required function that will check the provided credentials against your user database
  • allowEmptyUsername: boolean value that indicates whether users are allowed to make requests without a username; defaults to false
  • unauthorizedAttributes: object that will be passed to Boom.unauthorized if set. If there’s a custom error defined, this object will be ignored in favor of the custom error data; defaults to undefined

There’s a required option that you need to provide: validateFunc. That’s a function with the signature function(request, username, password), where

  • request: is the hapi request object which requires authentication
  • username: username send by the client
  • password: password send by the client

The return valie for validateFunc is an object, containing the following fields:

  • err: internal error object that replaces the default Boom.unauthorized if defined
  • isValid: boolean that indicates if the username was found and passwords match
  • credentials: user’s credentials, only included if isValid is true

The following section will show you an exemplary validation function.

Validate User Credentials

Routes that require authentication will be checked against the defined authentication strategy using the provided validation function.

For the password comparison within the exemplary validation function, you’re leveraging the bcrypt library and its provided functionality. If you want to use bcrypt for your project as well, install and add it as a project dependency:

npm i -S bcrypt

The following code snippet is just for illustration purposes and uses a hard-coded users object. Actually, you would query your database for a username match and compare the provided passwords.

const Bcrypt = require('bcrypt')

// hardcoded users object … just for illustration purposes
const users = {  
  future: {
    id: '1',
    username: 'future',
    password: '$2a$04$YPy8WdAtWswed8b9MfKixebJkVUhEZxQCrExQaxzhcdR2xMmpSJiG'  // 'studio'
  }
}

// validation function used for hapi-auth-basic
const basicValidation = async function (request, username, password) {  
  const user = users[ username ]

  if (!user) {
    return { isValid: false }
  }

  const isValid = await Bcrypt.compare(password, user.password)

  return { isValid, credentials: { id: user.id, username: user.username } }
}

As you can see, there is no magic involved to validate the user input. First, you get the user data from the users object and if there is data available you need to check if passwords match. Of course, you can extend the functionality within the validation function to your needs and proceed with further security checks.

Notice: Bcrypt.compare(candidate_plain_text_password, hash) compares the candidate password provided in plain text with a given hash. You don’t need to hash your candidate before checking if they match.

Route Configuration to Require Authentication

Hapi doesn’t require authentication for every route by default. You have to secure them individually and you’re free to choose from multiple authentication strategies if you’re using more than one.

Defining authentication for a route requires you to provide a config object for the route. Previously, you would set the method, path and handler for a route. Now the handler moves into the config object. To ultimately set the authentication mechanism for a route, put your desired strategy name as a string value to the auth field.

server.route({  
  method: 'GET',
  path: '/private-route',
  config: {
    auth: 'simple',
    handler: (request, h) => {
      return 'Yeah! This message is only available for authenticated users!'
    }
  }
})

As you can see, the route’s config object has the auth field set to the previously registered authentication strategy name simple. Specify the handler function within the config object aside the auth field.

Full Context — Complete Code Snippet

Throughout this tutorial you’ve seen multiple code snippets that ultimately add up to a complete example that build the context of basic authentication with hapi. The following code block composes all the small code chunks that have been used previously to describe the actual functionality.

const Hapi = require('hapi')  
const Bcrypt = require('bcrypt')

const server = new Hapi.Server()

async function liftOff () {  
  await server.register({
    plugin: require('hapi-auth-basic')
  }


  // hardcoded users object … just for illustration purposes
  const users = {
    future: {
      id: '1',
      username: 'future',
      password: '$2a$04$YPy8WdAtWswed8b9MfKixebJkVUhEZxQCrExQaxzhcdR2xMmpSJiG'  // 'studio'
    }
  }

  // validation function used for hapi-auth-basic
  const basicValidation = async function (request, username, password) {
    const user = users[ username ]

    if (!user) {
      return { isValid: false }
    }

    const isValid = await Bcrypt.compare(password, user.password)

    return { isValid, credentials: { id: user.id, username: user.username } }
  }

  server.auth.strategy('simple', 'basic', basicValidation)

  server.route({
    method: 'GET',
    path: '/private-route',
    config: {
      auth: 'simple',
      handler: (request, h) => {
        return 'Yeah! This message is only available for authenticated users!'
      }
    }
  })

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

liftOff()

Running this example code and pointing your browser window to the route http://localhost:3000/private-route will open a sign in a popup that requires you to provide a username and password. Use the combination future/studio to authenticate successfully.

Outlook

Within this tutorial, you’ve learned how to add the functionality for basic authentication to your hapi server instance by adding the hapi-auth-basic plugin and providing the required validation function. Further, you’ve added a route that requires authentication to access.

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