1 <?xml version="1.0" encoding="ISO-8859-1"?>
2 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
3 <html xmlns="http://www.w3.org/1999/xhtml" lang="en" xml:lang="en"><head><!--
4 XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
5 This file is generated from xml source: DO NOT EDIT
6 XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
8 <title>mod_session - Apache HTTP Server Version 2.5</title>
9 <link href="../style/css/manual.css" rel="stylesheet" media="all" type="text/css" title="Main stylesheet" />
10 <link href="../style/css/manual-loose-100pc.css" rel="alternate stylesheet" media="all" type="text/css" title="No Sidebar - Default font size" />
11 <link href="../style/css/manual-print.css" rel="stylesheet" media="print" type="text/css" /><link rel="stylesheet" type="text/css" href="../style/css/prettify.css" />
12 <script src="../style/scripts/prettify.min.js" type="text/javascript">
15 <link href="../images/favicon.ico" rel="shortcut icon" /></head>
17 <div id="page-header">
18 <p class="menu"><a href="../mod/">Modules</a> | <a href="../mod/quickreference.html">Directives</a> | <a href="http://wiki.apache.org/httpd/FAQ">FAQ</a> | <a href="../glossary.html">Glossary</a> | <a href="../sitemap.html">Sitemap</a></p>
19 <p class="apache">Apache HTTP Server Version 2.5</p>
20 <img alt="" src="../images/feather.gif" /></div>
21 <div class="up"><a href="./"><img title="<-" alt="<-" src="../images/left.gif" /></a></div>
23 <a href="http://www.apache.org/">Apache</a> > <a href="http://httpd.apache.org/">HTTP Server</a> > <a href="http://httpd.apache.org/docs/">Documentation</a> > <a href="../">Version 2.5</a> > <a href="./">Modules</a></div>
24 <div id="page-content">
25 <div id="preamble"><h1>Apache Module mod_session</h1>
27 <p><span>Available Languages: </span><a href="../en/mod/mod_session.html" title="English"> en </a></p>
29 <table class="module"><tr><th><a href="module-dict.html#Description">Description:</a></th><td>Session support</td></tr>
30 <tr><th><a href="module-dict.html#Status">Status:</a></th><td>Extension</td></tr>
31 <tr><th><a href="module-dict.html#ModuleIdentifier">Module Identifier:</a></th><td>session_module</td></tr>
32 <tr><th><a href="module-dict.html#SourceFile">Source File:</a></th><td>mod_session.c</td></tr>
33 <tr><th><a href="module-dict.html#Compatibility">Compatibility:</a></th><td>Available in Apache 2.3 and later</td></tr></table>
36 <div class="warning"><h3>Warning</h3>
37 <p>The session modules make use of HTTP cookies, and as such can fall
38 victim to Cross Site Scripting attacks, or expose potentially private
39 information to clients. Please ensure that the relevant risks have
40 been taken into account before enabling the session functionality on
44 <p>This module provides support for a server wide per user session
45 interface. Sessions can be used for keeping track of whether a user
46 has been logged in, or for other per user information that should
47 be kept available across requests.</p>
49 <p>Sessions may be stored on the server, or may be stored on the
50 browser. Sessions may also be optionally encrypted for added security.
51 These features are divided into several modules in addition to
52 <code class="module"><a href="../mod/mod_session.html">mod_session</a></code>; <code class="module"><a href="../mod/mod_session_crypto.html">mod_session_crypto</a></code>,
53 <code class="module"><a href="../mod/mod_session_cookie.html">mod_session_cookie</a></code> and <code class="module"><a href="../mod/mod_session_dbd.html">mod_session_dbd</a></code>.
54 Depending on the server requirements, load the appropriate modules
55 into the server (either statically at compile time or dynamically
56 via the <code class="directive"><a href="../mod/mod_so.html#loadmodule">LoadModule</a></code> directive).</p>
58 <p>Sessions may be manipulated from other modules that depend on the
59 session, or the session may be read from and written to using
60 environment variables and HTTP headers, as appropriate.</p>
63 <div id="quickview"><h3 class="directives">Directives</h3>
65 <li><img alt="" src="../images/down.gif" /> <a href="#session">Session</a></li>
66 <li><img alt="" src="../images/down.gif" /> <a href="#sessionenv">SessionEnv</a></li>
67 <li><img alt="" src="../images/down.gif" /> <a href="#sessionexclude">SessionExclude</a></li>
68 <li><img alt="" src="../images/down.gif" /> <a href="#sessionheader">SessionHeader</a></li>
69 <li><img alt="" src="../images/down.gif" /> <a href="#sessioninclude">SessionInclude</a></li>
70 <li><img alt="" src="../images/down.gif" /> <a href="#sessionmaxage">SessionMaxAge</a></li>
74 <li><img alt="" src="../images/down.gif" /> <a href="#whatisasession">What is a session?</a></li>
75 <li><img alt="" src="../images/down.gif" /> <a href="#whocanuseasession">Who can use a session?</a></li>
76 <li><img alt="" src="../images/down.gif" /> <a href="#serversession">Keeping sessions on the server</a></li>
77 <li><img alt="" src="../images/down.gif" /> <a href="#browsersession">Keeping sessions on the browser</a></li>
78 <li><img alt="" src="../images/down.gif" /> <a href="#basicexamples">Basic Examples</a></li>
79 <li><img alt="" src="../images/down.gif" /> <a href="#sessionprivacy">Session Privacy</a></li>
80 <li><img alt="" src="../images/down.gif" /> <a href="#cookieprivacy">Cookie Privacy</a></li>
81 <li><img alt="" src="../images/down.gif" /> <a href="#authentication">Session Support for Authentication</a></li>
82 <li><img alt="" src="../images/down.gif" /> <a href="#integration">Integrating Sessions with External Applications</a></li>
83 </ul><h3>See also</h3>
85 <li><code class="module"><a href="../mod/mod_session_cookie.html">mod_session_cookie</a></code></li>
86 <li><code class="module"><a href="../mod/mod_session_crypto.html">mod_session_crypto</a></code></li>
87 <li><code class="module"><a href="../mod/mod_session_dbd.html">mod_session_dbd</a></code></li>
88 </ul><ul class="seealso"><li><a href="#comments_section">Comments</a></li></ul></div>
89 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
90 <div class="directive-section"><h2><a name="Session" id="Session">Session</a> <a name="session" id="session">Directive</a></h2>
91 <table class="directive">
92 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Enables a session for the current directory or location</td></tr>
93 <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>Session On|Off</code></td></tr>
94 <tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>Session Off</code></td></tr>
95 <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory, .htaccess</td></tr>
96 <tr><th><a href="directive-dict.html#Override">Override:</a></th><td>AuthConfig</td></tr>
97 <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
98 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_session</td></tr>
100 <p>The <code class="directive">Session</code> directive enables a session for the
101 directory or location container. Further directives control where the
102 session will be stored and how privacy is maintained.</p>
105 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
106 <div class="directive-section"><h2><a name="SessionEnv" id="SessionEnv">SessionEnv</a> <a name="sessionenv" id="sessionenv">Directive</a></h2>
107 <table class="directive">
108 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Control whether the contents of the session are written to the
109 <var>HTTP_SESSION</var> environment variable</td></tr>
110 <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>SessionEnv On|Off</code></td></tr>
111 <tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>SessionEnv Off</code></td></tr>
112 <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory, .htaccess</td></tr>
113 <tr><th><a href="directive-dict.html#Override">Override:</a></th><td>AuthConfig</td></tr>
114 <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
115 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_session</td></tr>
117 <p>If set to <var>On</var>, the <code class="directive">SessionEnv</code> directive
118 causes the contents of the session to be written to a CGI environment
119 variable called <var>HTTP_SESSION</var>.</p>
121 <p>The string is written in the URL query format, for example:</p>
123 <div class="example"><p><code>
124 <code>key1=foo&key3=bar</code>
129 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
130 <div class="directive-section"><h2><a name="SessionExclude" id="SessionExclude">SessionExclude</a> <a name="sessionexclude" id="sessionexclude">Directive</a></h2>
131 <table class="directive">
132 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Define URL prefixes for which a session is ignored</td></tr>
133 <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>SessionExclude <var>path</var></code></td></tr>
134 <tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>none</code></td></tr>
135 <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory, .htaccess</td></tr>
136 <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
137 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_session</td></tr>
139 <p>The <code class="directive">SessionExclude</code> directive allows sessions to
140 be disabled relative to URL prefixes only. This can be used to make a
141 website more efficient, by targeting a more precise URL space for which
142 a session should be maintained. By default, all URLs within the directory
143 or location are included in the session. The
144 <code class="directive"><a href="#sessionexclude">SessionExclude</a></code> directive takes
146 <code class="directive"><a href="#sessioninclude">SessionInclude</a></code> directive.</p>
148 <div class="warning"><h3>Warning</h3>
149 <p>This directive has a similar purpose to the <var>path</var> attribute
150 in HTTP cookies, but should not be confused with this attribute. This
151 directive does not set the <var>path</var> attribute, which must be
152 configured separately.</p></div>
155 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
156 <div class="directive-section"><h2><a name="SessionHeader" id="SessionHeader">SessionHeader</a> <a name="sessionheader" id="sessionheader">Directive</a></h2>
157 <table class="directive">
158 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Import session updates from a given HTTP response header</td></tr>
159 <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>SessionHeader <var>header</var></code></td></tr>
160 <tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>none</code></td></tr>
161 <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory, .htaccess</td></tr>
162 <tr><th><a href="directive-dict.html#Override">Override:</a></th><td>AuthConfig</td></tr>
163 <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
164 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_session</td></tr>
166 <p>The <code class="directive">SessionHeader</code> directive defines the name of an
167 HTTP response header which, if present, will be parsed and written to the
170 <p>The header value is expected to be in the URL query format, for example:</p>
172 <div class="example"><p><code>
173 <code>key1=foo&key2=&key3=bar</code>
176 <p>Where a key is set to the empty string, that key will be removed from the
181 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
182 <div class="directive-section"><h2><a name="SessionInclude" id="SessionInclude">SessionInclude</a> <a name="sessioninclude" id="sessioninclude">Directive</a></h2>
183 <table class="directive">
184 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Define URL prefixes for which a session is valid</td></tr>
185 <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>SessionInclude <var>path</var></code></td></tr>
186 <tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>all URLs</code></td></tr>
187 <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory, .htaccess</td></tr>
188 <tr><th><a href="directive-dict.html#Override">Override:</a></th><td>AuthConfig</td></tr>
189 <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
190 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_session</td></tr>
192 <p>The <code class="directive">SessionInclude</code> directive allows sessions to
193 be made valid for specific URL prefixes only. This can be used to make a
194 website more efficient, by targeting a more precise URL space for which
195 a session should be maintained. By default, all URLs within the directory
196 or location are included in the session.</p>
198 <div class="warning"><h3>Warning</h3>
199 <p>This directive has a similar purpose to the <var>path</var> attribute
200 in HTTP cookies, but should not be confused with this attribute. This
201 directive does not set the <var>path</var> attribute, which must be
202 configured separately.</p></div>
205 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
206 <div class="directive-section"><h2><a name="SessionMaxAge" id="SessionMaxAge">SessionMaxAge</a> <a name="sessionmaxage" id="sessionmaxage">Directive</a></h2>
207 <table class="directive">
208 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Define a maximum age in seconds for a session</td></tr>
209 <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>SessionMaxAge <var>maxage</var></code></td></tr>
210 <tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>SessionMaxAge 0</code></td></tr>
211 <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory, .htaccess</td></tr>
212 <tr><th><a href="directive-dict.html#Override">Override:</a></th><td>AuthConfig</td></tr>
213 <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
214 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_session</td></tr>
216 <p>The <code class="directive">SessionMaxAge</code> directive defines a time limit
217 for which a session will remain valid. When a session is saved, this time
218 limit is reset and an existing session can be continued. If a session
219 becomes older than this limit without a request to the server to refresh
220 the session, the session will time out and be removed. Where a session is
221 used to stored user login details, this has the effect of logging the user
222 out automatically after the given time.</p>
224 <p>Setting the maxage to zero disables session expiry.</p>
227 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
228 <div class="section">
229 <h2><a name="whatisasession" id="whatisasession">What is a session?</a></h2>
230 <p>At the core of the session interface is a table of key and value pairs
231 that are made accessible across browser requests. These pairs can be set
232 to any valid string, as needed by the application making use of the
235 <p>The "session" is a <strong>application/x-www-form-urlencoded</strong>
236 string containing these key value pairs, as defined by the
237 <a href="http://www.w3.org/TR/html4/">HTML specification</a>.</p>
239 <p>The session can optionally be encrypted and base64 encoded before
240 being written to the storage mechanism, as defined by the
243 </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
244 <div class="section">
245 <h2><a name="whocanuseasession" id="whocanuseasession">Who can use a session?</a></h2>
246 <p>The session interface is primarily developed for the use by other
247 server modules, such as <code class="module"><a href="../mod/mod_auth_form.html">mod_auth_form</a></code>, however CGI
248 based applications can optionally be granted access to the contents
249 of the session via the HTTP_SESSION environment variable. Sessions
250 have the option to be modified and/or updated by inserting an HTTP
251 response header containing the new session parameters.</p>
253 </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
254 <div class="section">
255 <h2><a name="serversession" id="serversession">Keeping sessions on the server</a></h2>
256 <p>Apache can be configured to keep track of per user sessions stored
257 on a particular server or group of servers. This functionality is
258 similar to the sessions available in typical application servers.</p>
260 <p>If configured, sessions are tracked through the use of a session ID that
261 is stored inside a cookie, or extracted from the parameters embedded
262 within the URL query string, as found in a typical GET request.</p>
264 <p>As the contents of the session are stored exclusively on the server,
265 there is an expectation of privacy of the contents of the session. This
266 does have performance and resource implications should a large number
267 of sessions be present, or where a large number of webservers have to
268 share sessions with one another.</p>
270 <p>The <code class="module"><a href="../mod/mod_session_dbd.html">mod_session_dbd</a></code> module allows the storage of user
271 sessions within a SQL database via <code class="module"><a href="../mod/mod_dbd.html">mod_dbd</a></code>.</p>
273 </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
274 <div class="section">
275 <h2><a name="browsersession" id="browsersession">Keeping sessions on the browser</a></h2>
276 <p>In high traffic environments where keeping track of a session on a
277 server is too resource intensive or inconvenient, the option exists to store
278 the contents of the session within a cookie on the client browser instead.</p>
280 <p>This has the advantage that minimal resources are required on the
281 server to keep track of sessions, and multiple servers within a server
282 farm have no need to share session information.</p>
284 <p>The contents of the session however are exposed to the client, with a
285 corresponding risk of a loss of privacy. The
286 <code class="module"><a href="../mod/mod_session_crypto.html">mod_session_crypto</a></code> module can be configured to encrypt the
287 contents of the session before writing the session to the client.</p>
289 <p>The <code class="module"><a href="../mod/mod_session_cookie.html">mod_session_cookie</a></code> allows the storage of user
290 sessions on the browser within an HTTP cookie.</p>
292 </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
293 <div class="section">
294 <h2><a name="basicexamples" id="basicexamples">Basic Examples</a></h2>
296 <p>Creating a session is as simple as turning the session on, and deciding
297 where the session will be stored. In this example, the session will be
298 stored on the browser, in a cookie called <code>session</code>.</p>
300 <div class="example"><h3>Browser based session</h3><pre class="prettyprint lang-config">Session On
301 SessionCookieName session path=/</pre>
304 <p>The session is not useful unless it can be written to or read from. The
305 following example shows how values can be injected into the session through
306 the use of a predetermined HTTP response header called
307 <code>X-Replace-Session</code>.</p>
309 <div class="example"><h3>Writing to a session</h3><pre class="prettyprint lang-config">Session On
310 SessionCookieName session path=/
311 SessionHeader X-Replace-Session</pre>
314 <p>The header should contain name value pairs expressed in the same format
315 as a query string in a URL, as in the example below. Setting a key to the
316 empty string has the effect of removing that key from the session.</p>
318 <div class="example"><h3>CGI to write to a session</h3><pre class="prettyprint lang-sh">#!/bin/bash
319 echo "Content-Type: text/plain"
320 echo "X-Replace-Session: key1=foo&key2=&key3=bar"
325 <p>If configured, the session can be read back from the HTTP_SESSION
326 environment variable. By default, the session is kept private, so this
327 has to be explicitly turned on with the
328 <code class="directive"><a href="#sessionenv">SessionEnv</a></code> directive.</p>
330 <div class="example"><h3>Read from a session</h3><pre class="prettyprint lang-config">Session On
332 SessionCookieName session path=/
333 SessionHeader X-Replace-Session</pre>
336 <p>Once read, the CGI variable <code>HTTP_SESSION</code> should contain
337 the value <code>key1=foo&key3=bar</code>.</p>
339 </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
340 <div class="section">
341 <h2><a name="sessionprivacy" id="sessionprivacy">Session Privacy</a></h2>
343 <p>Using the "show cookies" feature of your browser, you would have seen
344 a clear text representation of the session. This could potentially be a
345 problem should the end user need to be kept unaware of the contents of
346 the session, or where a third party could gain unauthorised access to the
347 data within the session.</p>
349 <p>The contents of the session can be optionally encrypted before being
350 placed on the browser using the <code class="module"><a href="../mod/mod_session_crypto.html">mod_session_crypto</a></code>
353 <div class="example"><h3>Browser based encrypted session</h3><pre class="prettyprint lang-config">Session On
354 SessionCryptoPassphrase secret
355 SessionCookieName session path=/</pre>
358 <p>The session will be automatically decrypted on load, and encrypted on
359 save by Apache, the underlying application using the session need have
360 no knowledge that encryption is taking place.</p>
362 <p>Sessions stored on the server rather than on the browser can also be
363 encrypted as needed, offering privacy where potentially sensitive
364 information is being shared between webservers in a server farm using
365 the <code class="module"><a href="../mod/mod_session_dbd.html">mod_session_dbd</a></code> module.</p>
367 </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
368 <div class="section">
369 <h2><a name="cookieprivacy" id="cookieprivacy">Cookie Privacy</a></h2>
371 <p>The HTTP cookie mechanism also offers privacy features, such as the
372 ability to restrict cookie transport to SSL protected pages only, or
373 to prevent browser based javascript from gaining access to the contents
376 <div class="warning"><h3>Warning</h3>
377 <p>Some of the HTTP cookie privacy features are either non-standard, or
378 are not implemented consistently across browsers. The session modules
379 allow you to set cookie parameters, but it makes no guarantee that privacy
380 will be respected by the browser. If security is a concern, use the
381 <code class="module"><a href="../mod/mod_session_crypto.html">mod_session_crypto</a></code> to encrypt the contents of the session,
382 or store the session on the server using the <code class="module"><a href="../mod/mod_session_dbd.html">mod_session_dbd</a></code>
386 <p>Standard cookie parameters can be specified after the name of the cookie,
387 as in the example below.</p>
389 <div class="example"><h3>Setting cookie parameters</h3><pre class="prettyprint lang-config">Session On
390 SessionCryptoPassphrase secret
391 SessionCookieName session path=/private;domain=example.com;httponly;secure;</pre>
394 <p>In cases where the Apache server forms the frontend for backend origin servers,
395 it is possible to have the session cookies removed from the incoming HTTP headers using
396 the <code class="directive"><a href="../mod/mod_session_cookie.html#sessioncookieremove">SessionCookieRemove</a></code> directive.
397 This keeps the contents of the session cookies from becoming accessible from the
401 </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
402 <div class="section">
403 <h2><a name="authentication" id="authentication">Session Support for Authentication</a></h2>
405 <p>As is possible within many application servers, authentication modules can use
406 a session for storing the username and password after login. The
407 <code class="module"><a href="../mod/mod_auth_form.html">mod_auth_form</a></code> saves the user's login name and password within
410 <div class="example"><h3>Form based authentication</h3><pre class="prettyprint lang-config">Session On
411 SessionCryptoPassphrase secret
412 SessionCookieName session path=/
413 AuthFormProvider file
414 AuthUserFile "conf/passwd"
420 <p>See the <code class="module"><a href="../mod/mod_auth_form.html">mod_auth_form</a></code> module for documentation and complete
423 </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
424 <div class="section">
425 <h2><a name="integration" id="integration">Integrating Sessions with External Applications</a></h2>
427 <p>In order for sessions to be useful, it must be possible to share the contents
428 of a session with external applications, and it must be possible for an
429 external application to write a session of its own.</p>
431 <p> A typical example might be an application that changes a user's password set by
432 <code class="module"><a href="../mod/mod_auth_form.html">mod_auth_form</a></code>. This application would need to read the current
433 username and password from the session, make the required changes to the user's
434 password, and then write the new password to the session in order to provide a
435 seamless transition to the new password.</p>
437 <p>A second example might involve an application that registers a new user for
438 the first time. When registration is complete, the username and password is
439 written to the session, providing a seamless transition to being logged in.</p>
442 <dt>Apache modules</dt>
443 <dd>Modules within the server that need access to the session can use the
444 <strong>mod_session.h</strong> API in order to read from and write to the
445 session. This mechanism is used by modules like <code class="module"><a href="../mod/mod_auth_form.html">mod_auth_form</a></code>.
448 <dt>CGI programs and scripting languages</dt>
449 <dd>Applications that run within the webserver can optionally retrieve the
450 value of the session from the <strong>HTTP_SESSION</strong> environment
451 variable. The session should be encoded as a
452 <strong>application/x-www-form-urlencoded</strong> string as described by the
453 <a href="http://www.w3.org/TR/html4/">HTML specification</a>. The environment
454 variable is controlled by the setting of the
455 <code class="directive"><a href="#sessionenv">SessionEnv</a></code> directive. The session
456 can be written to by the script by returning a
457 <strong>application/x-www-form-urlencoded</strong> response header with a name
458 set by the <code class="directive"><a href="#sessionheader">SessionHeader</a></code>
459 directive. In both cases, any encryption or decryption, and the reading the
460 session from or writing the session to the chosen storage mechanism is handled
461 by the <code class="module"><a href="../mod/mod_session.html">mod_session</a></code> modules and corresponding configuration.
464 <dt>Applications behind <code class="module"><a href="../mod/mod_proxy.html">mod_proxy</a></code></dt>
465 <dd>If the <code class="directive"><a href="#sessionheader">SessionHeader</a></code>
466 directive is used to define an HTTP request header, the session, encoded as
467 a <strong>application/x-www-form-urlencoded</strong> string, will be made
468 available to the application. If the same header is provided in the response,
469 the value of this response header will be used to replace the session. As
470 above, any encryption or decryption, and the reading the session from or
471 writing the session to the chosen storage mechanism is handled by the
472 <code class="module"><a href="../mod/mod_session.html">mod_session</a></code> modules and corresponding configuration.</dd>
474 <dt>Standalone applications</dt>
475 <dd>Applications might choose to manipulate the session outside the control
476 of the Apache HTTP server. In this case, it is the responsibility of the
477 application to read the session from the chosen storage mechanism,
478 decrypt the session, update the session, encrypt the session and write
479 the session to the chosen storage mechanism, as appropriate.</dd>
484 <div class="bottomlang">
485 <p><span>Available Languages: </span><a href="../en/mod/mod_session.html" title="English"> en </a></p>
486 </div><div class="top"><a href="#page-header"><img src="../images/up.gif" alt="top" /></a></div><div class="section"><h2><a id="comments_section" name="comments_section">Comments</a></h2><div class="warning"><strong>Notice:</strong><br />This is not a Q&A section. Comments placed here should be pointed towards suggestions on improving the documentation or server, and may be removed again by our moderators if they are either implemented or considered invalid/off-topic. Questions on how to manage the Apache HTTP Server should be directed at either our IRC channel, #httpd, on Freenode, or sent to our <a href="http://httpd.apache.org/lists.html">mailing lists</a>.</div>
487 <script type="text/javascript"><!--//--><![CDATA[//><!--
488 var comments_shortname = 'httpd';
489 var comments_identifier = 'http://httpd.apache.org/docs/trunk/mod/mod_session.html';
491 if (w.location.hostname.toLowerCase() == "httpd.apache.org") {
492 d.write('<div id="comments_thread"><\/div>');
493 var s = d.createElement('script');
494 s.type = 'text/javascript';
496 s.src = 'https://comments.apache.org/show_comments.lua?site=' + comments_shortname + '&page=' + comments_identifier;
497 (d.getElementsByTagName('head')[0] || d.getElementsByTagName('body')[0]).appendChild(s);
500 d.write('<div id="comments_thread">Comments are disabled for this page at the moment.<\/div>');
502 })(window, document);
503 //--><!]]></script></div><div id="footer">
504 <p class="apache">Copyright 2015 The Apache Software Foundation.<br />Licensed under the <a href="http://www.apache.org/licenses/LICENSE-2.0">Apache License, Version 2.0</a>.</p>
505 <p class="menu"><a href="../mod/">Modules</a> | <a href="../mod/quickreference.html">Directives</a> | <a href="http://wiki.apache.org/httpd/FAQ">FAQ</a> | <a href="../glossary.html">Glossary</a> | <a href="../sitemap.html">Sitemap</a></p></div><script type="text/javascript"><!--//--><![CDATA[//><!--
506 if (typeof(prettyPrint) !== 'undefined') {