mod_session
Session support
Extension
mod_session.c
session_module
Available in Apache 2.3 and later
Warning
The session modules make use of HTTP cookies, and as such can fall
victim to Cross Site Scripting attacks, or expose potentially private
information to clients. Please ensure that the relevant risks have
been taken into account before enabling the session functionality on
your server.
This module provides support for a server wide per user session
interface. Sessions can be used for keeping track of whether a user
has been logged in, or for other per user information that should
be kept available across requests.
Sessions may be stored on the server, or may be stored on the
browser. Sessions may also be optionally encrypted for added security.
These features are divided into several modules in addition to
mod_session; mod_session_crypto,
mod_session_cookie and mod_session_dbd.
Depending on the server requirements, load the appropriate modules
into the server (either statically at compile time or dynamically
via the LoadModule directive).
Sessions may be manipulated from other modules that depend on the
session, or the session may be read from and written to using
environment variables and HTTP headers, as appropriate.
mod_session_cookie
mod_session_crypto
mod_session_dbd
What is a session?
At the core of the session interface is a table of key and value pairs
that are made accessible across browser requests.
These pairs can be set to any valid string, as needed by the
application making use of the session.
Who can use a session?
The session interface is primarily developed for the use by other
server modules, such as mod_auth_form, however CGI
based applications can optionally be granted access to the contents
of the session via the HTTP_SESSION environment variable. Sessions
have the option to be modified and/or updated by inserting an HTTP
response header containing the new session parameters.
Keeping sessions on the server
Apache can be configured to keep track of per user sessions stored
on a particular server or group of servers. This functionality is
similar to the sessions available in typical application servers.
If configured, sessions are tracked through the use of a session ID that
is stored inside a cookie, or extracted from the parameters embedded
within the URL query string, as found in a typical GET request.
As the contents of the session are stored exclusively on the server,
there is an expectation of privacy of the contents of the session. This
does have performance and resource implications should a large number
of sessions be present, or where a large number of webservers have to
share sessions with one another.
The mod_session_dbd module allows the storage of user
sessions within a SQL database via mod_dbd.
Keeping sessions on the browser
Where keeping track of a session on a server is too resource
intensive or inconvenient, the option exists to store the contents
of the session within a cookie on the client browser instead.
This has the advantage that minimal resources are required on the
server to keep track of sessions, and multiple servers within a server
farm have no need to share session information.
The contents of the session however are exposed to the client, with a
corresponding risk of a loss of privacy. The
mod_session_crypto module can be configured to encrypt the
contents of the session before writing the session to the client.
The mod_session_cookie allows the storage of user
sessions on the browser within an HTTP cookie.
Basic Examples
Creating a session is as simple as turning the session on, and deciding
where the session will be stored. In this example, the session will be
stored on the browser, in a cookie called session.
Browser based session
Session On
SessionCookieName session path=/
The session is not useful unless it can be written to or read from. The
following example shows how values can be injected into the session through
the use of a predetermined HTTP response header called
X-Replace-Session.
Writing to a session
Session On
SessionCookieName session path=/
SessionHeader X-Replace-Session
The header should contain name value pairs expressed in the same format
as a query string in a URL, as in the example below. Setting a key to the
empty string has the effect of removing that key from the session.
CGI to write to a session
#!/bin/bash
echo "Content-Type: text/plain"
echo "X-Replace-Session: key1=foo&key2=&key3=bar"
echo
env
If configured, the session can be read back from the HTTP_SESSION
environment variable. By default, the session is kept private, so this
has to be explicitly turned on with the
SessionEnv directive.
Read from a session
Session On
SessionEnv On
SessionCookieName session path=/
SessionHeader X-Replace-Session
Once read, the CGI variable HTTP_SESSION should contain
the value key1=foo&key3=bar.
Session Privacy
Using the "show cookies" feature of your browser, you would have seen
a clear text representation of the session. This could potentially be a
problem should the end user need to be kept unaware of the contents of
the session, or where a third party could gain unauthorised access to the
data within the session.
The contents of the session can be optionally encrypted before being
placed on the browser using the mod_session_crypto
module.
Browser based encrypted session
Session On
SessionCryptoPassphrase secret
SessionCookieName session path=/
The session will be automatically decrypted on load, and encrypted on
save by Apache, the underlying application using the session need have
no knowledge that encryption is taking place.
Sessions stored on the server rather than on the browser can also be
encrypted as needed, offering privacy where potentially sensitive
information is being shared between webservers in a server farm using
the mod_session_dbd module.
Cookie Privacy
The HTTP cookie mechanism also offers privacy features, such as the
ability to restrict cookie transport to SSL protected pages only, or
to prevent browser based javascript from gaining access to the contents
of the cookie.
Warning
Some of the HTTP cookie privacy features are either non standard, or
are not implemented consistently across browsers. The session modules
allow you to set cookie parameters, but it makes no guarantee that privacy
will be respected by the browser. If security is a concern, use the
mod_session_crypto to encrypt the contents of the session,
or store the session on the server using the mod_session_dbd
module.
Standard cookie parameters can be specified after the name of the cookie,
as in the example below.
Setting cookie parameters
Session On
SessionCryptoPassphrase secret
SessionCookieName session path=/private;domain=example.com;httponly;secure;
In cases where the Apache server forms the frontend for backend origin servers,
it is possible to have the session cookies removed from the incoming HTTP headers using
the SessionCookieRemove directive.
This keeps the contents of the session cookies from becoming accessible from the
backend server.
Session Support for Authentication
As is possible within many application servers, authentication modules can use
a session for storing the username and password after login. The
mod_auth_form saves the user's login name and password within
the session.
Form based authentication
Session On
SessionCryptoPassphrase secret
SessionCookieName session path=/
AuthFormProvider file
AuthUserFile conf/passwd
AuthType form
AuthName realm
...
See the mod_auth_form module for documentation and complete
examples.
Session
Enables a session for the current directory or location
Session On|Off
Session Off
server config
virtual host
directory
.htaccess
The Session directive enables a session for the
directory or location container. Further directives control where the
session will be stored and how privacy is maintained.
SessionMaxAge
Define a maximum age in seconds for a session
SessionMaxAge maxage
SessionMaxAge 0
server config
virtual host
directory
.htaccess
The SessionMaxAge directive defines a time limit
for which a session will remain valid. When a session is saved, this time
limit is reset and an existing session can be continued. If a session
becomes older than this limit without a request to the server to refresh
the session, the session will time out and be removed. Where a session is
used to stored user login details, this has the effect of logging the user
out automatically after the given time.
Setting the maxage to zero disables session expiry.
SessionEnv
Control whether the contents of the session are written to the
HTTP_SESSION environment variable
SessionEnv On|Off
SessionEnv Off
server config
virtual host
directory
.htaccess
If set to On, the SessionEnv directive
causes the contents of the session to be written to a CGI environment
variable called HTTP_SESSION.
The string is written in the URL query format, for example:
key1=foo&key3=bar
SessionHeader
Import session updates from a given HTTP response header
SessionHeader header
none
server config
virtual host
directory
.htaccess
The SessionHeader directive defines the name of an
HTTP response header which, if present, will be parsed and written to the
current session.
The header value is expected to be in the URL query format, for example:
key1=foo&key2=&key3=bar
Where a key is set to the empty string, that key will be removed from the
session.
SessionInclude
Define URL prefixes for which a session is valid
SessionInclude path
all URLs
server config
virtual host
directory
.htaccess
The SessionInclude directive allows sessions to
be made valid for specific URL prefixes only. This can be used to make a
website more efficient, by targeting a more precise URL space for which
a session should be maintained. By default, all URLs within the directory
or location are included in the session.
Warning
This directive has a similar purpose to the path attribute
in HTTP cookies, but should not be confused with this attribute. This
directive does not set the path attribute, which must be
configured separately.
SessionExclude
Define URL prefixes for which a session is ignored
SessionExclude path
none
server config
virtual host
directory
.htaccess
The SessionExclude directive allows sessions to
be disabled relative to URL prefixes only. This can be used to make a
website more efficient, by targeting a more precise URL space for which
a session should be maintained. By default, all URLs within the directory
or location are included in the session. The
SessionExclude directive takes
precedence over the
SessionInclude directive.
Warning
This directive has a similar purpose to the path attribute
in HTTP cookies, but should not be confused with this attribute. This
directive does not set the path attribute, which must be
configured separately.