-
-
Notifications
You must be signed in to change notification settings - Fork 9
Configuration
The sessions package provides a number of configuration variables which allow you to customize its functionality to your needs. This page provides detailed explanations for these variables as well as examples. See also the Godoc documentation for information.
You can use the package with all defaults but for production use, the very least you will need to define is the NewSessionCookie variable. It's a function that returns a new cookie. It is called by the sessions package any time a new cookie needs to be set on the user's browser.
Refer to the Golang cookie documentation for a list of fields that need to be specified, with two exceptions: Name and Value can be left blank as it will be set by the package. Be sure to specify Domain, Path, and Secure for production use.
Example:
sessions.NewSessionCookie = func() *http.Cookie {
return &http.Cookie{
Expires: time.Now().Add(10 * 365 * 24 * time.Hour),
MaxAge: 10 * 365 * 24 * 60 * 60, // Good for 10 years.
HttpOnly: true,
Secure: true,
Domain: ".example.com",
Path: "/",
}
}The specification for browser cookies is here and a more detailed explanation of the different attributes can be found on Wikipedia.
The name of the session cookie is specified in the SessionCookie variable. The default name is "id" and it is recommended to choose a name that does not indicate that the cookie content is used as a session identifier. (I.e. "PHPSESSID" or "JSESSIONID" are bad names from a security perspective as they even disclose the language or framework used to manage sessions.)
The SessionExpiry variable determines the maximum inactivity time before a session is destroyed. If a user is attached to a session, a destroyed session will effectively log a user out.
The default is to keep the session alive forever. From a usability point of view, this is convenient because it does not force the user to log in again after some period of inactivity. But in applications with sensitive data (e.g. banking), it may make sense to enforce activity. In case someone else gains access to the user's computer (for example, in a public library), at least if there was some inactive time, it will force them to log in again.
Thus, the correct value for this variable depends on your application. Note also that the "last activity" refers to the point in time when the sessions package touched the user's Session object. Any user activity that happens on the browser only will not count towards session activity. It may make sense to ping the server in such cases to refresh the "last activity" field.
There is also a timeout variable called SessionIDExpiry which does not refer to the session itself but only to the session ID which is stored in the browser cookie and used to identify the Session object on the server. When a session ID has been used longer than the SessionIDExpiry duration, it is replaced with a new session ID. The session itself lives on but its "primary key" will be different.
Exchanging session IDs reduces the possibility of attacks such as "session hijacking" where an attacker gains access to your session ID to impersonate you. If your session ID is renewed regularly, any captured session ID will not last long and such attacks become more difficult.
You should also use the RegenerateID() function to force a renewal of the session ID. This is specifically important when the user's privilege level changes, i.e. when a user logs in/out or when their access rights change.
When session IDs are renewed, old session IDs become invalid. This can pose problems when multiple requests are issued at about the same time on a slow network. For example, if the browser sends two requests to the server at almost the same time and the server decides to replace the session ID on the first request that it received, the second request may be rejected because it also contained the old session ID which is now invalid. On slow networks (e.g. mobile), this can become a problem.
The sessions package therefore keeps the old session alive after a session ID regeneration for a certain duration. This duration is defined by the SessionIDGracePeriod variable. The default is 5 minutes but if you expect your users to frequently be on very slow networks (or driving through long tunnels, for example), you may want to extent this duration.
The sessions package can check if the user's IP address has changed to a degree that it is likely that the session was hijacked. Currently, this works only for IPv4 addresses. The AcceptRemoteIP variable determines how much you will allow an IP address to change before the session will be destroyed. For example, if the session was last accessed with the IP address 192.168.178.46, the following values will have the described effects (xxx may change without the session being considered compromised):
-
1: xxx.xxx.xxx.xxx (accept all IP address changes) -
2: 192.xxx.xxx.xxx -
3: 192.168.xxx.xxx -
4: 192.168.178.xxx (good for dynamically assigned IP addresses of an internet provider)
Set the AcceptChangingUserAgent to false (the default) if you would like the sessions package to compare the browser's user agent strings and reject those sessions where the strings have changed. Of course, user agent strings can be modified but a session hijacker would, in addition to the session ID, have to acquire the user's user agent string to impersonate them. On the other hand, user agent strings can change when the user upgrades their browser. Therefore, the impact on usability - especially given that today's browsers upgrade frequently - needs to be considered.
The sessions package keeps a local session cache. This cache is write-through. That is, any changes to sessions will be written to the external database but read-only access happens only in the cache.
The MaxSessionCacheSize variable determines the maximum size of the local sessions cache. When there are more than this number of Session objects in the cache, the package will discard the sessions with the oldest access time to make space.
You can set this value to -1 to let the local session cache grow indefinitely. Sessions will then only be discarded based on the SessionCacheExpiry variable (see below).
Another special value is 0 which means that no Session objects are kept in the local cache. This makes sense of you rely completely on an external sessions database (e.g. Redis).
The SessionCacheExpiry variable defines the maximum duration an inactive Session object remains in the local session cache.