npm: npm install @hapi/cookie

yarn: yarn add @hapi/cookie


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 - an object with the following:

    • name - 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 none.
    • clearInvalid - if true, any authentication cookie that fails validation will be marked as expired in the response and cleared. 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.
  • keepAlive - if true, automatically sets the session cookie after validation to extend the current session for a new ttl duration. Defaults to false.

  • redirectTo - optional login URI or function function(request) that returns a URI to redirect unauthenticated requests to. Note that it will only trigger when the authentication mode is 'required'. To enable or disable redirections for a specific route, set the route plugins config ({ options: { plugins: { 'hapi-auth-cookie': { redirectTo: false } } } }). Defaults to no redirection.

  • appendNext - if redirectTo is true, can be a boolean, string, or object. Defaults to false.

    • if set to true, a string, or an object, appends the current request path to the query component of the redirectTo URI
    • set to a string value or set the name property in an object to define the parameter name. defaults to 'next'
    • set the raw property of the object to true to determine the current request path based on the raw node.js request object received from the HTTP server callback instead of the processed hapi request object
  • 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/hapi');

const internals = {};

// Simulate database for demo

internals.users = [
        id: 1,
        name: 'john',
        password: 'password',

internals.renderHtml = {
    login: (message) => {

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

        return `
    <html><head><title>Login page</title></head><body>
    <h3>Welcome ${name}! You are logged in!</h3>
    <form method="get" action="/logout">
      <input type="submit" value="Logout">

internals.server = async function () {

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

    await server.register(require('@hapi/cookie'));

    server.auth.strategy('session', 'cookie', {

        cookie: {
            name: 'sid-example',

            // Don't forget to change it to your own secret password!
            password: 'password-should-be-32-characters',

            // For working via HTTP in localhost
            isSecure: false

        redirectTo: '/login',

        validateFunc: async (request, session) => {

            const account = internals.users.find((user) => ( ===;

            if (!account) {
                // Must return { valid: false } for invalid cookies
                return { valid: false };

            return { valid: true, credentials: account };


            method: 'GET',
            path: '/',
            options: {
                handler: (request, h) => {

                    return internals.renderHtml.home(;
            method: 'GET',
            path: '/login',
            options: {
                auth: {
                    mode: 'try'
                plugins: {
                    'hapi-auth-cookie': {
                        redirectTo: false
                handler: async (request, h) => {

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

                    return internals.renderHtml.login();
            method: 'POST',
            path: '/login',
            options: {
                auth: {
                    mode: 'try'
                handler: async (request, h) => {

                    const { username, password } = request.payload;
                    if (!username || !password) {
                        return internals.renderHtml.login('Missing username or password');

                    // Try to find user with given credentials

                    const account = internals.users.find(
                        (user) => === username && user.password === password

                    if (!account) {
                        return internals.renderHtml.login('Invalid username or password');

                    request.cookieAuth.set({ id: });
                    return h.redirect('/');
            method: 'GET',
            path: '/logout',
            options: {
                handler: (request, h) => {

                    return h.redirect('/');

    await server.start();
    console.log(`Server started at: ${}`);

internals.start = async function() {

    try {
        await internals.server();
    catch (err) {



Update joi
Update deps
Change module namespace
Move all cookie settings to `cookie`
10.0.0 Release notes
Remove ignoreIfDecorated
No override of default cookie settings
Upgrade to hapi 18
Update for hapi 18
Support password rotation
referenced the raw request when setting next
breaking changes
Respect auth mode for redirects
Use options key for route configuration
Issue 163
Fix redirectTo function w/ blank to behave like blank redirectTo (fix)
Drop session from cache in examples
breaking changes
Update lead maintainer
Upgraded module to hapi v17
referenced the raw request when setting next
Do not redecorate the request object if already decorated
Allow redirectTo to be a function
Add isSameSite to schema
Options aren't required
add note to readme about the 'ttl' option
Test on node v6, update dependencies
fix typo in readme
Allow null to be passed for the ttl
update readme with information/warning about cookie length
decorator fix
support many strategies
Use server.decorate
breaking changes
move away from request.auth.session
Switch to use a request decoration instead of request.auth.session
breaking changes
node 4 update
Node >= 4 / es6 updates
allow buffer as password
Buffer type should be allowed for "password" option
breaking changes
validateFunc according to signature function
Updated docs
Pass request object to validation function
2.2.0 update
Fix support for custom appendNext param
`appendNext` no longer accepts a string
allow null setting for domain
domain is now required as a string, and null does not pass validation
Version 2.1.0
Allow environment variables to configure cookie scheme
breaking changes
Version 2.0.0
Use request.route.settings.plugin
Invalid cookie should still return 401
hapi 8.0 API
Invalid cookie blocks scheme from redirecting
Fix clearInvalid (for issue #34)
Bad cookie value even with clearInvalid true
Session keepAlive and ttl override
add set/clear key for cookie
Fix for handling multiple strategies
Update key in auth.credentials
Exposed path option for session cookie
Expose 'path' in cookieOptions
Update License
Fix hapi dev dep
Skip redirection on try
No way to use with 'try' mode if 'redirectTo' is set
validateFunc credentials override session
hapi 6.0
Bring coverage back to 100%
Bring coverage back to 100% after lab fix
fix peerDependencies for hapi