Session Plugin

Cookie-based session authentication with automatic renewal and secure cookie management.

Overview

The Session plugin provides cookie-based session authentication with automatic renewal and secure cookie management for your application. Whilst the main authentication configuration already configures the session and any properties to do with it, the Session plugin provides the actual implementation of cookie-based sessions, including issuing cookies, validating them on each request, and automatically renewing them as they approach expiration.

Features

Cookie-Based Sessions — Secure HTTP-only cookies for session tracking
Sliding Window Renewal — Sessions automatically renew when approaching expiration
Secure Cookie Attributes — Configurable HttpOnly, Secure, and SameSite settings
Automatic Cleanup — Optionally, expired sessions are automatically purged
Cooperative Authentication — Works seamlessly with other auth plugins (e.g., JWT) without conflicts

Configuration

Standalone Mode:

# Global Session Configuration
[session]
cookie_name = "authula.session_token"
expires_in = "30m"
update_age = "5m"
cookie_max_age = "24h"
secure = false
http_only = true
same_site = "lax"  # Options: "lax", "strict", "none"
auto_cleanup = false # Flag to automatically clean up expired sessions and enforce max sessions per user
cleanup_interval = "1m" # Interval for automatic cleanup of expired sessions
max_sessions_per_user = 5 # Maximum number of concurrent sessions per user (0 = unlimited)

# Enable the Session plugin
[plugins.session]
enabled = true

Library Mode:

import (
  "github.com/Authula/authula"
  authulaconfig "github.com/Authula/authula/config"
  authulamodels "github.com/Authula/authula/models"
  sessionplugin "github.com/Authula/authula/plugins/session"
)

config := authulaconfig.NewConfig(
  authulaconfig.WithSession(authulamodels.SessionConfig{
    CookieName:         "authula.session_token",
    ExpiresIn:          24 * time.Hour,
    UpdateAge:          5 * time.Minute,
    CookieMaxAge:       24 * time.Hour,
    Secure:             false,
    HttpOnly:           true,
    SameSite:           "lax",
    MaxSessionsPerUser: 5,
    AutoCleanup:        true,
    CleanupInterval:    time.Minute,
  }),
)
auth := authula.New(&authula.AuthConfig{
  Config: config,
  Plugins: []authulamodels.Plugin{
    sessionplugin.New(sessionplugin.SessionPluginConfig{
      Enabled: true,
    }),
  },
})

API Reference

The Session plugin doesn't expose any HTTP endpoints.

Database Schema

The Session plugin doesn't create any database tables.

Plugin Capabilities

The Session plugin provides the following hooks and capabilities:

Global hook to issue session cookie after successful authentication
Global hook to remove session cookie on sign-out
session.auth - Validates session cookie; returns 401 Unauthorized if invalid or missing
session.auth.optional - Validates session if present; silently continues if invalid or missing

Usage

Standalone Mode:

[[route_mappings]]
paths = ["GET:/some/path"]
# Requires authentication - returns 401 if session is missing or invalid
plugins = ["session.auth"]

[[route_mappings]]
paths = ["GET:/some/other/path"]
# Optional authentication - allows access even if session is missing or invalid
plugins = ["session.auth.optional"]

Library Mode:

import (
  authulaconfig "github.com/Authula/authula/config"
  authulamodels "github.com/Authula/authula/models"
  sessionplugin "github.com/Authula/authula/plugins/session"
)

authulaconfig.NewConfig(
  authulaconfig.WithRouteMappings([]authulamodels.RouteMapping{
    {
      Paths:   []string{"GET:/some/path"},
      Plugins: []string{sessionplugin.HookIDSessionAuth.String()},
    },
    {
      Paths:   []string{"GET:/some/other/path"},
      Plugins: []string{sessionplugin.HookIDSessionAuthOptional.String()},
    },
  }),
)

Security Recommendations

Token Hashing — Session tokens are hashed before storage in the database.
HttpOnly Cookies — Prevents XSS attacks by restricting JavaScript access.
Secure Flag — Ensures cookies are only transmitted over HTTPS. Set secure = true in production.
SameSite Protection — Defends against CSRF attacks. Use strict for maximum security, lax for typical web apps.
Automatic Expiration — Sessions cannot be used beyond their expiration time. Configure expires_in and update_age based on your security requirements.
Session Cleanup — Enable auto_cleanup to automatically remove expired sessions from the database.

Session Plugin

On this page