1 // Copyright 2012 The Gorilla Authors. All rights reserved. 2 // Use of this source code is governed by a BSD-style 3 // license that can be found in the LICENSE file. 4 5 /* 6 Package sessions provides cookie and filesystem sessions and 7 infrastructure for custom session backends. 8 9 The key features are: 10 11 * Simple API: use it as an easy way to set signed (and optionally 12 encrypted) cookies. 13 * Built-in backends to store sessions in cookies or the filesystem. 14 * Flash messages: session values that last until read. 15 * Convenient way to switch session persistency (aka "remember me") and set 16 other attributes. 17 * Mechanism to rotate authentication and encryption keys. 18 * Multiple sessions per request, even using different backends. 19 * Interfaces and infrastructure for custom session backends: sessions from 20 different stores can be retrieved and batch-saved using a common API. 21 22 Let's start with an example that shows the sessions API in a nutshell: 23 24 import ( 25 "net/http" 26 "github.com/gorilla/sessions" 27 ) 28 29 // Note: Don't store your key in your source code. Pass it via an 30 // environmental variable, or flag (or both), and don't accidentally commit it 31 // alongside your code. Ensure your key is sufficiently random - i.e. use Go's 32 // crypto/rand or securecookie.GenerateRandomKey(32) and persist the result. 33 // Ensure SESSION_KEY exists in the environment, or sessions will fail. 34 var store = sessions.NewCookieStore([]byte(os.Getenv("SESSION_KEY"))) 35 36 func MyHandler(w http.ResponseWriter, r *http.Request) { 37 // Get a session. Get() always returns a session, even if empty. 38 session, err := store.Get(r, "session-name") 39 if err != nil { 40 http.Error(w, err.Error(), http.StatusInternalServerError) 41 return 42 } 43 44 // Set some session values. 45 session.Values["foo"] = "bar" 46 session.Values[42] = 43 47 // Save it before we write to the response/return from the handler. 48 err = session.Save(r, w) 49 if err != nil { 50 http.Error(w, err.Error(), http.StatusInternalServerError) 51 return 52 } 53 } 54 55 First we initialize a session store calling NewCookieStore() and passing a 56 secret key used to authenticate the session. Inside the handler, we call 57 store.Get() to retrieve an existing session or a new one. Then we set some 58 session values in session.Values, which is a map[interface{}]interface{}. 59 And finally we call session.Save() to save the session in the response. 60 61 Note that in production code, we should check for errors when calling 62 session.Save(r, w), and either display an error message or otherwise handle it. 63 64 Save must be called before writing to the response, otherwise the session 65 cookie will not be sent to the client. 66 67 That's all you need to know for the basic usage. Let's take a look at other 68 options, starting with flash messages. 69 70 Flash messages are session values that last until read. The term appeared with 71 Ruby On Rails a few years back. When we request a flash message, it is removed 72 from the session. To add a flash, call session.AddFlash(), and to get all 73 flashes, call session.Flashes(). Here is an example: 74 75 func MyHandler(w http.ResponseWriter, r *http.Request) { 76 // Get a session. 77 session, err := store.Get(r, "session-name") 78 if err != nil { 79 http.Error(w, err.Error(), http.StatusInternalServerError) 80 return 81 } 82 83 // Get the previous flashes, if any. 84 if flashes := session.Flashes(); len(flashes) > 0 { 85 // Use the flash values. 86 } else { 87 // Set a new flash. 88 session.AddFlash("Hello, flash messages world!") 89 } 90 err = session.Save(r, w) 91 if err != nil { 92 http.Error(w, err.Error(), http.StatusInternalServerError) 93 return 94 } 95 } 96 97 Flash messages are useful to set information to be read after a redirection, 98 like after form submissions. 99 100 There may also be cases where you want to store a complex datatype within a 101 session, such as a struct. Sessions are serialised using the encoding/gob package, 102 so it is easy to register new datatypes for storage in sessions: 103 104 import( 105 "encoding/gob" 106 "github.com/gorilla/sessions" 107 ) 108 109 type Person struct { 110 FirstName string 111 LastName string 112 Email string 113 Age int 114 } 115 116 type M map[string]interface{} 117 118 func init() { 119 120 gob.Register(&Person{}) 121 gob.Register(&M{}) 122 } 123 124 As it's not possible to pass a raw type as a parameter to a function, gob.Register() 125 relies on us passing it a value of the desired type. In the example above we've passed 126 it a pointer to a struct and a pointer to a custom type representing a 127 map[string]interface. (We could have passed non-pointer values if we wished.) This will 128 then allow us to serialise/deserialise values of those types to and from our sessions. 129 130 Note that because session values are stored in a map[string]interface{}, there's 131 a need to type-assert data when retrieving it. We'll use the Person struct we registered above: 132 133 func MyHandler(w http.ResponseWriter, r *http.Request) { 134 session, err := store.Get(r, "session-name") 135 if err != nil { 136 http.Error(w, err.Error(), http.StatusInternalServerError) 137 return 138 } 139 140 // Retrieve our struct and type-assert it 141 val := session.Values["person"] 142 var person = &Person{} 143 if person, ok := val.(*Person); !ok { 144 // Handle the case that it's not an expected type 145 } 146 147 // Now we can use our person object 148 } 149 150 By default, session cookies last for a month. This is probably too long for 151 some cases, but it is easy to change this and other attributes during 152 runtime. Sessions can be configured individually or the store can be 153 configured and then all sessions saved using it will use that configuration. 154 We access session.Options or store.Options to set a new configuration. The 155 fields are basically a subset of http.Cookie fields. Let's change the 156 maximum age of a session to one week: 157 158 session.Options = &sessions.Options{ 159 Path: "/", 160 MaxAge: 86400 * 7, 161 HttpOnly: true, 162 } 163 164 Sometimes we may want to change authentication and/or encryption keys without 165 breaking existing sessions. The CookieStore supports key rotation, and to use 166 it you just need to set multiple authentication and encryption keys, in pairs, 167 to be tested in order: 168 169 var store = sessions.NewCookieStore( 170 []byte("new-authentication-key"), 171 []byte("new-encryption-key"), 172 []byte("old-authentication-key"), 173 []byte("old-encryption-key"), 174 ) 175 176 New sessions will be saved using the first pair. Old sessions can still be 177 read because the first pair will fail, and the second will be tested. This 178 makes it easy to "rotate" secret keys and still be able to validate existing 179 sessions. Note: for all pairs the encryption key is optional; set it to nil 180 or omit it and and encryption won't be used. 181 182 Multiple sessions can be used in the same request, even with different 183 session backends. When this happens, calling Save() on each session 184 individually would be cumbersome, so we have a way to save all sessions 185 at once: it's sessions.Save(). Here's an example: 186 187 var store = sessions.NewCookieStore([]byte("something-very-secret")) 188 189 func MyHandler(w http.ResponseWriter, r *http.Request) { 190 // Get a session and set a value. 191 session1, _ := store.Get(r, "session-one") 192 session1.Values["foo"] = "bar" 193 // Get another session and set another value. 194 session2, _ := store.Get(r, "session-two") 195 session2.Values[42] = 43 196 // Save all sessions. 197 err = sessions.Save(r, w) 198 if err != nil { 199 http.Error(w, err.Error(), http.StatusInternalServerError) 200 return 201 } 202 } 203 204 This is possible because when we call Get() from a session store, it adds the 205 session to a common registry. Save() uses it to save all registered sessions. 206 */ 207 package sessions 208