sessions

Overview ¶

Package gorilla/sessions provides cookie sessions and infrastructure for custom session back-ends.

The key features are:

* Dead simple basic API: use it as an easy way to set signed (and optionally encrypted) cookies.

* Advanced API for custom back-ends: built-in support for custom storage systems; session store interface and helper functions; encoder interface and default implementation with customizable cryptography methods (thanks to Go interfaces).

* Conveniences: flash messages (session values that last until read); built-in mechanism to rotate authentication and encryption keys; multiple sessions per request, even using different back-ends; easy way to switch session persistency (aka "remember me") and set other attributes.

The most basic example to retrieve a session is to call sessions.Session() passing the current request. For example, in a handler:

func MyHandler(w http.ResponseWriter, r *http.Request) {
	if session, err := sessions.Session(r); err == nil {
		session["foo"] = "bar"
		session["baz"] = 128
		sessions.Save(r, w)
	}
}

The above snippet is "gorilla/sessions in a nutshell": a session is a simple map[string]interface{} returned from sessions.Session(). It stores any values that can be encoded using gob. After we set some values, we call sessions.Save() passing the current request and response.

Side note about "any values that can be encoded using gob": to store special structures in a session, we must register them using gob.Register() first. For basic types this is not needed; it works out of the box.

Is it that simple? Well, almost. Before we can use sessions, we must define a secret key to be used for authentication, and optionally an encryption key. They are both set calling SetStoreKeys() and should be done at initialization time:

func init() {
	sessions.SetStoreKeys("cookie",
						  []byte("my-hmac-key"),
						  []byte("my-aes-key"))
}

The first argument is the name used to register the session store. By default a "cookie" store is registered and available for use, so we use that name.

The second argument is the secret key used to authenticate the session cookie using HMAC. It is required; if no authentication key is set sessions can't be read or written (and a call to sessions.Session() will return an error).

The third argument is the encryption key; it is optional and can be omitted. For the cookie store, setting this will encrypt the contents stored in the cookie; otherwise the contents can be read, although not forged.

Side note about the encryption key: if set, must be either 16, 24, or 32 bytes to select AES-128, AES-192, or AES-256 modes. Otherwise a block can't be created and sessions won't work.

Exposing the contents of a session is not a big deal in many cases, like when we store a simple username or user id, but to to store sensitive information using the cookie store, we must set an encryption key. For custom stores that only set a random session id in the cookie, encryption is not needed.

And this is all you need to know about the basic usage. More advanced options are explained below.

Sometimes we may want to change authentication and/or encryption keys without breaking existing sessions. We can do this setting multiple authentication and encryption keys, in pairs, to be tested in order:

sessions.SetStoreKeys("cookie",
					  []byte("my-hmac-key"),
					  []byte("my-aes-key"),
					  []byte("my-previous-hmac-key"),
					  []byte("my-previous-aes-key"))

New sessions will be saved using the first pair. Old sessions can still be read because the first pair will fail, and the second will be tested. This makes it easy to "rotate" secret keys and still be able to validate existing sessions. Note: for all pairs the encryption key is optional; set it to nil and encryption won't be used.

Back to how sessions are retrieved.

Sessions are named. When we get a session calling sessions.Session(request), we are implicitly requesting a session using the default key ("s") and store (the CookieSessionStore). This is just a convenience; we can have as many sessions as needed, just passing different session keys. For example:

if authSession, err := sessions.Session(r, "auth"); err == nil {
	userId = authSession["userId"]
	// ...
}

Here we requested a session explicitly naming it "auth". It will be saved separately. This can be used as a convenient way to save signed cookies, and is also how we access multiple sessions per request.

Session stores also have a name, and need to be registered to be available. The default session store uses authenticated (and optionally encrypted) cookies, and is registered with the name "cookie". To use a custom session back-end, we first register it in the SessionFactory, then pass its name as the third argument to sessions.Session().

For the sake of demonstration, let's pretend that we defined a store called MemcacheSessionStore. First we register it using the "memcache" key. This should be done at initialization time:

func init() {
	sessions.SetStore("memcache", new(MemcacheSessionStore))
}

Then to get a session using memcached, we pass a third argument to sessions.Session(), the store key:

session, err := sessions.Session(r, "mysession", "memcache")

...and it will use the custom back-end we defined, instead of the default "cookie" one. This means that we can use multiple sessions in the same request even using different back-ends.

And how to configure session expiration time, path or other cookie attributes?

By default, session cookies last for a month. This is probably too long for a lot of cases, but it is easy to change this and other attributes during runtime. Just request the session configuration struct and change the variables as needed. The fields are basically a subset of http.Cookie fields. To change MaxAge, we would do:

if config, err = sessions.Config(r); err == nil {
	// Change max-age to 1 week.
	config.MaxAge = 86400 * 7
}

After this, cookies will last for a week only. The Config() function accepts an optional argument besides the request: the session key. If not defined, the configuration for the default session key is returned.

Bonus: flash messages. What are they? It basically means "session values that last until read". The term was popularized by Ruby On Rails a few years back. When we request a flash message, it is removed from the session. We have two convenience functions to read and set them: Flashes() and AddFlash(). Here is an example:

func MyHandler(w http.ResponseWriter, r *http.Request) {
	// Get the previously set flashes, if any.
	if flashes, _ := sessions.Flashes(r); flashes != nil {
		// Just print the flash values.
		fmt.Fprint(w, "%v", flashes)
	} else {
		fmt.Fprint(w, "No flashes found.")
		// Set a new flash.
		sessions.AddFlash(r, "Hello, flash messages world!")
	}
	sessions.Save(r, w)
}

Flash messages are useful to set information to be read after a redirection, usually after form submissions.