Want to take your software engineering career to the next level? Join the mailing list for career tips & advice Click here


Cookie authentication plugin

Subscribe to updates I use hapi-auth-cookie

Statistics on hapi-auth-cookie

Number of watchers on Github 203
Number of open issues 20
Average time to close an issue 11 days
Main language JavaScript
Average time to merge a PR 7 days
Open pull requests 16+
Closed pull requests 15+
Last commit over 2 years ago
Repo Created over 6 years ago
Repo Last Updated over 2 years ago
Size 184 KB
Organization / Authorhapijs
Page Updated
Do you use hapi-auth-cookie? Leave a review!
View open issues (20)
View hapi-auth-cookie activity
View on github
Fresh, new opensource launches 🚀🚀🚀
Software engineers: It's time to get promoted. Starting NOW! Subscribe to my mailing list and I will equip you with tools, tips and actionable advice to grow in your career.
Evaluating hapi-auth-cookie for your project? Score Explanation
Commits Score (?)
Issues & PR Score (?)


hapi Cookie authentication plugin

Build Status

Lead Maintainer: Julian Lannigan

Cookie authentication provides simple cookie-based session management. The user has to be authenticated via other means, typically a web form, and upon successful authentication the browser receives a reply with a session cookie. The cookie uses Iron to encrypt and sign the session content.

Subsequent requests containing the session cookie are authenticated and validated via the provided validateFunc in case the cookie's encrypted content requires validation on each request.

It is important to remember a couple of things:

  1. Each cookie operates as a bearer token and anyone in possession of the cookie content can use it to impersonate its true owner.
  2. Cookies have a practical maximum length. All of the data you store in a cookie is sent to the browser. If your cookie is too long, browsers may not set it. Read more here and here. If you need to store more data, store a small amount of identifying data in the cookie and use that as a key to a server-side cache system.

The 'cookie' scheme takes the following options:

  • cookie - the cookie name. Defaults to 'sid'.
  • password - used for Iron cookie encoding. Should be at least 32 characters long.
  • ttl - sets the cookie expires time in milliseconds. Defaults to single browser session (ends when browser closes). Required when keepAlive is true.
  • domain - sets the cookie Domain value. Defaults to none.
  • path - sets the cookie path value. Defaults to /.
  • clearInvalid - if true, any authentication cookie that fails validation will be marked as expired in the response and cleared. Defaults to false.
  • keepAlive - if true, automatically sets the session cookie after validation to extend the current session for a new ttl duration. Defaults to false.
  • isSameSite - if false omitted. Other options Strict or Lax. Defaults to Strict.
  • isSecure - if false, the cookie is allowed to be transmitted over insecure connections which exposes it to attacks. Defaults to true.
  • isHttpOnly - if false, the cookie will not include the 'HttpOnly' flag. Defaults to true.
  • redirectTo - optional login URI or function function(request) that returns a URI to redirect unauthenticated requests to. Note that using redirectTo with authentication mode 'try' will cause the protected endpoint to always redirect, voiding 'try' mode. To set an individual route to use or disable redirections, use the route plugins config ({ options: { plugins: { 'hapi-auth-cookie': { redirectTo: false } } } }). Defaults to no redirection.
  • appendNext - if true and redirectTo is true, appends the current request path to the query component of the redirectTo URI using the parameter name 'next'. Set to a string to use a different parameter name. Defaults to false.
  • redirectOnTry - if false and route authentication mode is 'try', authentication errors will not trigger a redirection. Defaults to true;
  • async validateFunc - an optional session validation function used to validate the content of the session cookie on each request. Used to verify that the internal session state is still valid (e.g. user account still exists). The function has the signature function(request, session) where:
    • request - is the Hapi request object of the request which is being authenticated.
    • session - is the session object set via request.cookieAuth.set().

Must return an object that contains: - valid - true if the content of the session is valid, otherwise false. - credentials - a credentials object passed back to the application in request.auth.credentials. If value is null or undefined, defaults to session. If set, will override the current cookie as if request.cookieAuth.set() was called.

  • requestDecoratorName - USE WITH CAUTION an optional name to use with decorating the request object. Defaults to 'cookieAuth'. Using multiple decorator names for separate authentication strategies could allow a developer to call the methods for the wrong strategy. Potentially resulting in unintended authorized access.

When the cookie scheme is enabled on a route, the request.cookieAuth objects is decorated with the following methods:

  • set(session) - sets the current session. Must be called after a successful login to begin the session. session must be a non-null object, which is set on successful subsequent authentications in request.auth.credentials where:
    • session - the session object.
  • set(key, value) - sets a specific object key on the current session (which must already exist) where:
    • key - session key string.
    • value - value to assign key.
  • clear([key]) - clears the current session or session key where:
    • key - optional key string to remove a specific property of the session. If none provided, defaults to removing the entire session which is used to log the user out.
  • ttl(msecs) - sets the ttl of the current active session where:
    • msecs - the new ttl in milliseconds.

Because this scheme decorates the request object with session-specific methods, it cannot be registered more than once.

'use strict';

const Hapi = require('hapi');
const internals = {};

let uuid = 1;       // Use seq instead of proper unique identifiers for demo only

const users = {
    john: {
        id: 'john',
        password: 'password',
        name: 'John Doe'

const home = (request, h) => {

    return '<html><head><title>Login page</title></head><body><h3>Welcome ' +
      request.auth.credentials.name +
      '!</h3><br/><form method="get" action="/logout">' +
      '<input type="submit" value="Logout">' +

const login = async (request, h) => {

    if (request.auth.isAuthenticated) {
        return h.redirect('/');

    let message = '';
    let account = null;

    if (request.method === 'post') {

        if (!request.payload.username ||
            !request.payload.password) {

            message = 'Missing username or password';
        else {
            account = users[request.payload.username];
            if (!account ||
                account.password !== request.payload.password) {

                message = 'Invalid username or password';

    if (request.method === 'get' ||
        message) {

        return '<html><head><title>Login page</title></head><body>' +
            (message ? '<h3>' + message + '</h3><br/>' : '') +
            '<form method="post" action="/login">' +
            'Username: <input type="text" name="username"><br>' +
            'Password: <input type="password" name="password"><br/>' +
            '<input type="submit" value="Login"></form></body></html>';

    const sid = String(++uuid);

    await request.server.app.cache.set(sid, { account }, 0);
    request.cookieAuth.set({ sid });

    return h.redirect('/');

const logout = (request, h) => {

    return h.redirect('/');

const server = Hapi.server({ port: 8000 });

exports.start = async () => {

    await server.register(require('../'));

    const cache = server.cache({ segment: 'sessions', expiresIn: 3 * 24 * 60 * 60 * 1000 });
    server.app.cache = cache;

    server.auth.strategy('session', 'cookie', {
        password: 'password-should-be-32-characters',
        cookie: 'sid-example',
        redirectTo: '/login',
        isSecure: false,
        validateFunc: async (request, session) => {

            const cached = await cache.get(session.sid);
            const out = {
                valid: !!cached

            if (out.valid) {
                out.credentials = cached.account;

            return out;


        { method: 'GET', path: '/', options: { handler: home } },
        { method: ['GET', 'POST'], path: '/login', options: { handler: login, auth: { mode: 'try' }, plugins: { 'hapi-auth-cookie': { redirectTo: false } } } },
        { method: 'GET', path: '/logout', options: { handler: logout } }

    await server.start();

    console.log(`Server started at: ${server.info.uri}`);

internals.start = async function () {

    try {
        await exports.start();
    catch (err) {

hapi-auth-cookie open issues Ask a question     (View All Issues)
  • almost 4 years Troubleshooting cookieAuth.clear() issues.
  • almost 4 years What is the best approach to prevent concurrent sessions for same user?
  • almost 4 years Custom response on normal request and AJAX
  • almost 4 years Support SameSite attribute
  • about 4 years redirectTo as function?
  • about 4 years third argument to the validateFunc's callback
  • about 4 years I can't set a cookie with domain redirection.
  • about 4 years 'isAuthenticated' returning false when config auth set to false
  • about 4 years Simulate cookie authentication to run a Test
  • over 4 years Auth mode 'optional' does not distinguish between the lack of a session cookie and an invalid session cookie
  • over 4 years upgrading from 5.0.0 to ^6.0.0
hapi-auth-cookie open pull requests (View All Pulls)
  • update readme with information/warning about cookie length
  • Allow null to be passed for the ttl
  • fix typo in readme
  • Options aren't required
  • add note to readme about the 'ttl' option
  • Add isSameSite to schema
  • update the example
  • Format config as table
  • Allow redirectTo to be a function
  • Do not redecorate the request object if already decorated
  • referenced the raw request when setting next
  • Redirect only when auth is required
  • Respect auth mode for redirects
  • Fix redirectTo function w/ blank to behave like blank redirectTo (fix)
  • Drop session from cache in examples
  • Issue 163
hapi-auth-cookie questions on Stackoverflow (View All Questions)
  • Authentication with hapi-auth-cookie not setting session
  • hapi-auth-cookie not setting cookie
  • Session clears on app restart in hapi-auth-cookie
  • Set ttl for hapi-auth-cookie for specific route
  • hapi-auth-cookie failing to load session strategy
hapi-auth-cookie list of languages used
Other projects in JavaScript