Safe Haskell | None |
---|---|
Language | Haskell98 |
Snap server-side session support.
- initServerSessionManager :: (Storage sto, SnapSession (SessionData sto)) => IO (State sto) -> SnapletInit b SessionManager
- simpleServerSessionManager :: (Storage sto, SessionData sto ~ SessionMap) => IO sto -> (State sto -> State sto) -> SnapletInit b SessionManager
- class IsSessionData sess => SnapSession sess where
- forceInvalidate :: ForceInvalidate -> Handler b SessionManager ()
- data ForceInvalidate :: *
- setCookieName :: Text -> State sto -> State sto
- setAuthKey :: Text -> State sto -> State sto
- setIdleTimeout :: Maybe NominalDiffTime -> State sto -> State sto
- setAbsoluteTimeout :: Maybe NominalDiffTime -> State sto -> State sto
- setTimeoutResolution :: Maybe NominalDiffTime -> State sto -> State sto
- setPersistentCookies :: Bool -> State sto -> State sto
- setHttpOnlyCookies :: Bool -> State sto -> State sto
- setSecureCookies :: Bool -> State sto -> State sto
- data State sto :: * -> *
Using server-side sessions
initServerSessionManager :: (Storage sto, SnapSession (SessionData sto)) => IO (State sto) -> SnapletInit b SessionManager Source #
Create a new ServerSessionManager
using the given State
.
simpleServerSessionManager :: (Storage sto, SessionData sto ~ SessionMap) => IO sto -> (State sto -> State sto) -> SnapletInit b SessionManager Source #
Simplified version of initServerSessionManager
, sufficient
for most needs.
class IsSessionData sess => SnapSession sess where Source #
Class for data types that implement the operations Snap expects sessions to support.
ssInsert :: Text -> Text -> sess -> sess Source #
ssLookup :: Text -> sess -> Maybe Text Source #
ssDelete :: Text -> sess -> sess Source #
ssToList :: sess -> [(Text, Text)] Source #
ssInsertCsrf :: Text -> sess -> sess Source #
ssLookupCsrf :: sess -> Maybe Text Source #
ssForceInvalidate :: ForceInvalidate -> sess -> sess Source #
SnapSession SessionMap Source # | Uses |
Invalidating session IDs
forceInvalidate :: ForceInvalidate -> Handler b SessionManager () Source #
Invalidate the current session ID (and possibly more, check
ForceInvalidate
). This is useful to avoid session fixation
attacks (cf. http://www.acrossecurity.com/papers/session_fixation.pdf).
Note that the invalidate does not occur when the call to
this action is made! The sessions will be invalidated when
the session is commit
ed. This means that later calls to
forceInvalidate
on the same handler will override earlier
calls.
This function works by setting a session variable that is checked when saving the session. The session variable set by this function is then discarded and is not persisted across requests.
data ForceInvalidate :: * #
Which session IDs should be invalidated.
Note that this is not the same concept of invalidation as used on J2EE. In this context, invalidation means creating a fresh session ID for this user's session and disabling the old ID. Its purpose is to avoid session fixation attacks.
CurrentSessionId | Invalidate the current session ID. The current session
ID is automatically invalidated on login and logout
(cf. |
AllSessionIdsOfLoggedUser | Invalidate all session IDs beloging to the currently logged in user. Only the current session ID will be renewed (the only one for which a cookie can be set). This is useful, for example, if the user asks to change their password. It's also useful to provide a button to clear all other sessions. If the user is not logged in, this option behaves exactly
as Note that, for the purposes of
|
DoNotForceInvalidate | Do not force invalidate. Invalidate only if automatically. This is the default. |
State configuration
setCookieName :: Text -> State sto -> State sto #
Set the name of cookie where the session ID will be saved. Defaults to "JSESSIONID", which is a generic cookie name used by many frameworks thus making it harder to fingerprint this implementation.
setAuthKey :: Text -> State sto -> State sto #
Set the name of the session variable that keeps track of the logged user.
This setting is used by session data types that are
Map
-alike, using a lookup
function. However, the
IsSessionData
instance of a session data type may choose not
to use it. For example, if you implemented a custom data
type, you could return the AuthId
without needing a lookup.
Defaults to "_ID" (used by yesod-auth
).
setIdleTimeout :: Maybe NominalDiffTime -> State sto -> State sto #
Set the idle timeout for all sessions. This is used both on
the client side (by setting the cookie expires fields) and on
the server side (the idle timeout is enforced even if the
cookie expiration is ignored). Setting to Nothing
removes
the idle timeout entirely.
"[The idle timemout] defines the amount of time a session will remain active in case there is no activity in the session, closing and invalidating the session upon the defined idle period since the last HTTP request received by the web application for a given session ID." (Source)
Defaults to 7 days.
setAbsoluteTimeout :: Maybe NominalDiffTime -> State sto -> State sto #
Set the absolute timeout for all sessions. This is used both on
the client side (by setting the cookie expires fields) and on
the server side (the absolute timeout is enforced even if the
cookie expiration is ignored). Setting to Nothing
removes
the absolute timeout entirely.
"[The absolute timeout] defines the maximum amount of time a session can be active, closing and invalidating the session upon the defined absolute period since the given session was initially created by the web application. After invalidating the session, the user is forced to (re)authenticate again in the web application and establish a new session." (Source)
Defaults to 60 days.
setTimeoutResolution :: Maybe NominalDiffTime -> State sto -> State sto #
Set the timeout resolution.
We need to save both the creation and last access times on sessions in order to implement idle and absolute timeouts. This means that we have to save the updated session on the storage backend even if the request didn't change any session variable, if only to update the last access time.
This setting provides an optimization where the session is not updated on the storage backend provided that:
- No session variables were changed.
- The difference between the current time and the last saved access time is less than the timeout resolution.
For example, with a timeout resolution of 1 minute, every request that does not change the session variables within 1 minute of the last update will not generate any updates on the storage backend.
If the timeout resolution is Nothing
, then this optimization
becomes disabled and the session will always be updated.
Defaults to 10 minutes.
setPersistentCookies :: Bool -> State sto -> State sto #
Set whether by default cookies should be persistent (True
) or
non-persistent (False
). Persistent cookies are saved across
browser sessions. Non-persistent cookies are discarded when
the browser is closed.
If you set cookies to be persistent and do not define any
timeouts (setIdleTimeout
or setAbsoluteTimeout
), then the
cookie is set to expire in 10 years.
Defaults to True
.
setHttpOnlyCookies :: Bool -> State sto -> State sto #
Set whether cookies should be HTTP-only (True
) or not
(False
). Cookies marked as HTTP-only ("HttpOnly") are not
accessible from client-side scripting languages such as
JavaScript, thus preventing a large class of XSS attacks.
It's highly recommended to set this attribute to True
.
Defaults to True
.
setSecureCookies :: Bool -> State sto -> State sto #
Set whether cookies should be mared "Secure" (True
) or not
(False
). Cookies marked as "Secure" are not sent via
plain HTTP connections, only via HTTPS connections. It's
highly recommended to set this attribute to True
. However,
since many sites do not operate over HTTPS, the default is
False
.
Defaults to False
.
The server-side session backend needs to maintain some state in order to work:
- A nonce generator for the session IDs.
- A reference to the storage backend.
- The name of cookie where the session ID will be saved (
setCookieName
). - Authentication session variable (
setAuthKey
). - Idle and absolute timeouts (
setIdleTimeout
andsetAbsoluteTimeout
). - Timeout resolution (
setTimeoutResolution
). - Whether cookies should be persistent
(
setPersistentCookies
), HTTP-only (setHTTPOnlyCookies
) and/or secure (setSecureCookies
).
Create a new State
using createState
.