Advanced

Cookie Configuration

Advanced cookie settings and security configuration

Learn how to configure cookies for authentication in Nuxt Umbu, including security options, prefixes, and environment-specific settings.

Overview

Cookie configuration is crucial for authentication security. Nuxt Umbu provides flexible cookie options that can be customized for different environments and security requirements.

auth: {
  cookie: {
    prefix: 'auth.',
    options: {
      httpOnly: false,
      secure: false,
      sameSite: 'Lax',
      priority: 'high',
      maxAge: 60 * 60 * 24 * 7,  // 7 days
      domain: '.example.com'
    }
  }
}

httpOnly

Controls whether the cookie is accessible via JavaScript.

options: {
  httpOnly: true  // Cookie not accessible via document.cookie
}

true: Cookie only accessible via HTTP (recommended for production)
false: Cookie accessible via JavaScript (useful for debugging)

secure

Requires HTTPS for the cookie to be sent.

options: {
  secure: true  // Cookie only sent over HTTPS
}

true: Cookie only sent over HTTPS (required for production)
false: Cookie sent over HTTP and HTTPS (development only)

sameSite

Controls cross-site cookie sharing behavior.

options: {
  sameSite: 'Strict'  // Strict cross-site policy
}

Available values:

'Strict': Cookie never sent with cross-site requests (most secure)
'Lax': Cookie sent with top-level navigations (balanced security)
'None': Cookie sent with all cross-site requests (requires secure: true)

priority

Defines the cookie's priority in the browser.

options: {
  priority: 'high'  // High priority cookie
}

Available values:

'low': Low priority
'medium': Medium priority
'high': High priority (recommended for auth cookies)

maxAge

Cookie lifespan in seconds.

options: {
  maxAge: 60 * 60 * 24 * 7  // 7 days in seconds
}

domain

The domain for which the cookie is valid.

options: {
  domain: '.example.com'  // Valid for all subdomains
}

expires

Expiration date of the cookie.

options: {
  expires: new Date(Date.now() + 7 * 24 * 60 * 60 * 1000)  // 7 days from now
}

The prefix determines the cookie name and security level.

cookie: {
  prefix: 'auth.'  // Development prefix
}

Available Prefixes

'auth.': Development prefix (default in dev mode)
'__Secure-': Production prefix with security requirements
'__Host-': Strict production prefix with additional restrictions

Prefix Security Requirements

`__Secure-` Prefix

Requires secure: true
Requires HTTPS
Cannot be set over HTTP

`__Host-` Prefix

Requires secure: true
Requires HTTPS
Cannot set domain attribute
Must use exact host (no subdomains)
Requires path: '/'

// Example __Host- prefix configuration
cookie: {
  prefix: '__Host-',
  options: {
    httpOnly: true,
    secure: true,
    sameSite: 'Strict',
    priority: 'high',
    path: '/',  // Required for __Host- prefix
    maxAge: 60 * 60 * 24 * 7  // 7 days
  }
}

Environment-Specific Configuration

Development Configuration

// nuxt.config.ts (development)
export default defineNuxtConfig({
  auth: {
    cookie: {
      prefix: 'auth.',
      options: {
        httpOnly: false,
        secure: false,
        sameSite: 'Lax',
        priority: 'high'
      }
    }
  }
})

Production Configuration

// nuxt.config.ts (production)
export default defineNuxtConfig({
  auth: {
    cookie: {
      prefix: '__Secure-',
      options: {
        httpOnly: true,
        secure: true,
        sameSite: 'Strict',
        priority: 'high',
        maxAge: 60 * 60 * 24 * 7  // 7 days
      }
    }
  }
})

Dynamic Configuration

export default defineNuxtConfig({
  auth: {
    cookie: {
      prefix: process.env.NODE_ENV === 'production' ? '__Secure-' : 'auth.',
      options: {
        httpOnly: process.env.NODE_ENV === 'production',
        secure: process.env.NODE_ENV === 'production',
        sameSite: process.env.NODE_ENV === 'production' ? 'Strict' : 'Lax',
        priority: 'high'
      }
    }
  }
})

Automatic Configuration

Nuxt Umbu automatically adjusts cookie settings in development mode:

// Automatic development overrides
if (isDev) {
  options.cookie.prefix = 'auth.';
  options.cookie.options.secure = false;
}

This ensures:

Development uses auth. prefix
Development allows HTTP cookies
Development has relaxed security for debugging

Cookies are named using the prefix and strategy name:

// For strategy named 'password'
// With prefix 'auth.'
// Cookie name: 'auth.password'

Multiple Strategies

Each strategy gets its own cookie:

strategies: {
  password: { /* ... */ },    // Cookie: auth.password
  social: { /* ... */ }       // Cookie: auth.social
}

Security Best Practices

Production Settings

Always use these settings in production:

cookie: {
  prefix: '__Secure-',
  options: {
    httpOnly: true,      // Prevent XSS attacks
    secure: true,       // Require HTTPS
    sameSite: 'Strict', // Prevent CSRF attacks
    priority: 'high'    // Ensure cookie persistence
  }
}

Session Duration

Set appropriate session duration based on security requirements:

options: {
  maxAge: 60 * 60 * 24 * 1   // 1 day (high security)
  // maxAge: 60 * 60 * 24 * 7  // 7 days (balanced)
  // maxAge: 60 * 60 * 24 * 30 // 30 days (convenience)
}

Domain Configuration

Use domain configuration carefully:

options: {
  // For single domain
  domain: undefined  // Current domain only

  // For subdomains
  domain: '.example.com'  // All subdomains

  // Avoid overly broad domains
  // domain: '.com'  // BAD: Too broad
}

Common Issues

Cookies Not Setting

Check that secure: false in development
Verify HTTPS is enabled in production for secure: true
Ensure cookie prefix is valid for your environment

Cookies Not Being Sent

Verify sameSite setting allows your request type
Check that domain matches the request domain
Ensure cookie hasn't expired

Cross-Site Issues

Use sameSite: 'None' with secure: true for cross-site requests
Verify CORS configuration on your API
Check browser security settings

Browser DevTools

Open Application > Cookies in DevTools
Verify cookie attributes match your configuration
Test cookie behavior across different scenarios

Network Tab

Open Network tab in DevTools
Check Request Headers for cookie presence
Verify Set-Cookie headers in responses

Inform users about cookie usage
Provide cookie consent mechanisms
Allow users to manage cookie preferences

Security Headers

Combine with security headers:

// nuxt.config.ts
export default defineNuxtConfig({
  routeRules: {
    '/**': {
      headers: {
        'Strict-Transport-Security': 'max-age=31536000; includeSubDomains',
        'X-Content-Type-Options': 'nosniff',
        'X-Frame-Options': 'DENY'
      }
    }
  }
})

Troubleshooting

Development Issues

// If cookies don't work in development
cookie: {
  prefix: 'auth.',
  options: {
    secure: false,  // Must be false for HTTP
    httpOnly: false // Set to false for debugging
  }
}

Production Issues

// If cookies don't work in production
cookie: {
  prefix: '__Secure-',  // Must use secure prefix
  options: {
    secure: true,       // Must be true for HTTPS
    httpOnly: true,     // Recommended for security
    sameSite: 'Strict'  // Recommended for CSRF protection
  }
}

Best Practices Summary

Use __Secure- prefix in production
Enable httpOnly to prevent XSS attacks
Enable secure to require HTTPS
Use sameSite: 'Strict' for CSRF protection
Set appropriate maxAge for your security requirements
Test cookie behavior in both development and production
Monitor cookie-related security advisories
Keep cookie configuration in environment-specific files

Custom Configuration

Advanced customization of Nuxt Umbu module options

TypeScript Integration

TypeScript types and IDE support for Nuxt Umbu