SCS: A HTTP Session Manager

SCS is a fast and lightweight HTTP session manager for Go. It features:

• Built-in PostgreSQL, MySQL, Redis, Memcached, encrypted cookie and in-memory storage engines. Custom storage engines are also supported.
• Supports OWASP good-practices, including absolute and idle session timeouts and easy regeneration of session tokens.
• Fast and very memory-efficient performance.
• Type-safe and sensible API for managing session data. Safe for concurrent use.
• Automatic saving of session data.

Recent changes: Release v1.0.0 made breaking changes to the package layout and API. If you need the old version please vendor release v0.1.1.

Installation & Usage

Install with go get:

$ go get github.com/alexedwards/scs

Basic use

package main

import (
    "io"
    "net/http"

    "github.com/alexedwards/scs"
)

// Initialize a new encrypted-cookie based session manager and store it in a global
// variable. In a real application, you might inject the session manager as a
// dependency to your handlers instead. The parameter to the NewCookieManager()
// function is a 32 character long random key, which is used to encrypt and
// authenticate the session cookies.
var sessionManager = scs.NewCookieManager("u46IpCV9y5Vlur8YvODJEhgOY8m9JVE4")

func main() {
    // Set up your HTTP handlers in the normal way.
    mux := http.NewServeMux()
    mux.HandleFunc("/put", putHandler)
    mux.HandleFunc("/get", getHandler)

    // Wrap your handlers with the session manager middleware.
    http.ListenAndServe(":4000", sessionManager.Use(mux))
}

func putHandler(w http.ResponseWriter, r *http.Request) {
    // Load the session data for the current request. Any errors are deferred
    // until you actually use the session data.
    session := sessionManager.Load(r)

    // Use the PutString() method to add a new key and associated string value
    // to the session data. Methods for many other common data types are also
    // provided. The session data is automatically saved.
    err := session.PutString(w, "message", "Hello world!")
    if err != nil {
        http.Error(w, err.Error(), 500)
    }
}

func getHandler(w http.ResponseWriter, r *http.Request) {
    // Load the session data for the current request.
    session := sessionManager.Load(r)

    // Use the GetString() helper to retrieve the string value for the "message"
    // key from the session data. The zero value for a string is returned if the
    // key does not exist.
    message, err := session.GetString("message")
    if err != nil {
        http.Error(w, err.Error(), 500)
    }

    io.WriteString(w, message)
}

SCS provides a wide range of functions for working with session data.

• Put… and Get… methods for storing and retrieving a variety of common data types and custom objects.
• Pop… methods for one-time retrieval of common data types (and custom objects) from the session data.
• Keys returns an alphabetically-sorted slice of all keys in the session data.
• Exists returns whether a specific key exists in the session data.
• Remove removes an individual key and value from the session data.
• Clear removes all data for the current session.
• RenewToken creates a new session token. This should be used before privilege changes to help avoid session fixation.
• Destroy deletes the current session and instructs the browser to delete the session cookie.

A full list of available functions can be found in the GoDoc.

Customizing the session manager

The session manager can be configured to customize its behavior. For example:

sessionManager = scs.NewCookieManager("u46IpCV9y5Vlur8YvODJEhgOY8m9JVE4")
sessionManager.Lifetime(time.Hour) // Set the maximum session lifetime to 1 hour.
sessionManager.Persist(true) // Persist the session after a user has closed their browser.
sessionManager.Secure(true) // Set the Secure flag on the session cookie.

A full list of available settings can be found in the GoDoc.

Using a different session store

The above examples use encrypted cookies to store session data, but SCS also supports a range of server-side stores.

Compatibility

SCS is designed to be compatible with Go's net/http package and the http.Handler interface.

If you're using the Echo framework, the official session middleware for Echo is likely to be a better fit for your application.

Examples

• RequireLogin middleware