2 <!DOCTYPE modulesynopsis SYSTEM "../style/modulesynopsis.dtd">
3 <?xml-stylesheet type="text/xsl" href="../style/manual.fr.xsl"?>
4 <!-- English Revision: 1793934 -->
5 <!-- French translation : Lucien GENTIS -->
8 Licensed to the Apache Software Foundation (ASF) under one or more
9 contributor license agreements. See the NOTICE file distributed with
10 this work for additional information regarding copyright ownership.
11 The ASF licenses this file to You under the Apache License, Version 2.0
12 (the "License"); you may not use this file except in compliance with
13 the License. You may obtain a copy of the License at
15 http://www.apache.org/licenses/LICENSE-2.0
17 Unless required by applicable law or agreed to in writing, software
18 distributed under the License is distributed on an "AS IS" BASIS,
19 WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
20 See the License for the specific language governing permissions and
21 limitations under the License.
24 <modulesynopsis metafile="mod_session.xml.meta">
26 <name>mod_session</name>
27 <description>Support des sessions</description>
28 <status>Extension</status>
29 <sourcefile>mod_session.c</sourcefile>
30 <identifier>session_module</identifier>
31 <compatibility>Disponible depuis la version 2.3 d'Apache</compatibility>
34 <note type="warning"><title>Avertissement</title>
35 <p>Le module session fait usage des cookies HTTP, et peut à ce
36 titre être victime d'attaques de type Cross Site Scripting, ou
37 divulguer des informations à caractère privé aux clients. Veuillez
38 vous assurer que les risques ainsi encourus ont été pris en compte
39 avant d'activer le support des sessions sur votre serveur.</p>
42 <p>Ce module fournit le support d'une interface de session pour
43 chaque utilisateur au niveau du serveur global. Les sessions
44 permettent de transmettre diverses informations : l'utilisateur
45 est-il connecté ou non, ou toute autre information qui doit être
46 conservée d'une requête à l'autre.</p>
48 <p>Les sessions peuvent être stockées sur le serveur, ou au niveau
49 du navigateur. Les sessions peuvent aussi être chiffrées pour une
50 sécurité accrue. Ces fonctionnalités sont réparties entre différents
51 modules complémentaires de <module>mod_session</module> :
52 <module>mod_session_crypto</module>,
53 <module>mod_session_cookie</module> et
54 <module>mod_session_dbd</module>. Chargez les modules appropriés
55 en fonction des besoins du serveur (soit statiquement à la
56 compilation, soit dynamiquement via la directive <directive
57 module="mod_so">LoadModule</directive>).</p>
59 <p>Les sessions peuvent être manipulées par d'autres modules qui
60 dépendent de la session, ou la session peut être lue et écrite dans
61 des variables d'environnement et des en-têtes HTTP, selon les
65 <seealso><module>mod_session_cookie</module></seealso>
66 <seealso><module>mod_session_crypto</module></seealso>
67 <seealso><module>mod_session_dbd</module></seealso>
69 <section id="whatisasession"><title>Qu'est-ce qu'une session ?</title>
70 <p>Au coeur de l'interface de session se trouve une table de
71 paires clé/valeur qui sont accessibles d'une requête du navigateur
72 à l'autre. Les valeurs de clés peuvent se voir affecter toute chaîne
73 valide, en fonction des besoins de l'application qui fait usage de
76 <p>Une "session" est une chaîne
77 <strong>application/x-www-form-urlencoded</strong> qui contient la
78 paire clé/valeur définie par la <a
79 href="http://www.w3.org/TR/html4/">specification HTML</a>.</p>
81 <p>Selon les souhaits de l'administrateur, la session peut être
82 chiffrée et codée en base64 avant d'être soumise au dispositif de
86 <section id="whocanuseasession"><title>Qui peut utiliser une session
88 <p>L'interface de session a été conçue à l'origine pour être
89 utilisée par d'autres modules du serveur comme
90 <module>mod_auth_form</module> ; les applications à base de
91 programmes CGI peuvent cependant se voir accorder l'accès au
92 contenu d'une session via la variable d'environnement
93 HTTP_SESSION. Il est possible de modifier et/ou de mettre à jour
94 une session en insérant un en-tête de réponse HTTP contenant les
95 nouveaux paramètres de session.</p>
98 <section id="serversession"><title>Stockage des sessions sur le
100 <p>Apache peut être configuré pour stocker les sessions
101 utilisateurs sur un serveur particulier ou un groupe de serveurs.
102 Cette fonctionnalité est similaire aus sessions disponibles sur
103 les serveurs d'applications courants.</p>
105 <p>Selon la configuration, les sessions sont suivies à
106 partir d'un identifiant de session stocké dans un cookie, ou
107 extrait de la chaîne de paramètres de l'URL, comme dans les
108 requêtes GET courantes.</p>
110 <p>Comme le contenu de la session est stocké exclusivement sur le
111 serveur, il est nécessaire de préserver la confidentialité de ce
112 contenu. Ceci a des implications en matière de performance et de
113 consommation de ressources lorsqu'un grand nombre de sessions est
114 stocké, ou lorsqu'un grand nombre de serveurs doivent se partager
115 les sessions entre eux.</p>
117 <p>Le module <module>mod_session_dbd</module> permet de stocker
118 les sessions utilisateurs dans une base de données SQL via le
119 module <module>mod_dbd</module>.</p>
121 </section> <!-- /serversession -->
123 <section id="browsersession"><title>Stockage des sessions au niveau
124 du navigateur</title>
125 <p>Dans les environnements à haut trafic où le stockage d'une
126 session sur un serveur consomme trop
127 de ressources, il est possible de stocker le contenu de la session
128 dans un cookie au niveau du navigateur client.</p>
130 <p>Ceci a pour avantage de ne nécessiter qu'une quantité minimale de
131 ressources sur le serveur pour suivre les sessions, et évite à
132 plusieurs serveurs parmi une forêt de serveurs de devoir partager
133 les informations de session.</p>
135 <p>Le contenu de la session est cependant présenté au client, avec
136 pour conséquence un risque de perte de confidentialité. Le module
137 <module>mod_session_crypto</module> peut être configuré pour
138 chiffrer le contenu de la session avant qu'elle soit stockée au
139 niveau du client.</p>
141 <p>Le module <module>mod_session_cookie</module> permet de stocker
142 les sessions au niveau du navigateur dans un cookie HTTP.+</p>
144 </section> <!-- /browsersession -->
146 <section id="basicexamples"><title>Exemples simples</title>
148 <p>La création d'une session consiste simplement à ouvrir la
149 session, et à décider de l'endroit où elle doit être stockée. Dans
150 l'exemple suivant, la session sera stockée au niveau du
151 navigateur, dans un cookie nommé <code>session</code>.</p>
153 <example><title>Session stockée au niveau du navigateur</title>
154 <highlight language="config">
156 SessionCookieName session path=/
160 <p>Une session est inutile s'il n'est pas possible d'y lire
161 ou d'y écrire. L'exemple suivant montre comment des valeurs
162 peuvent être injectées dans une session à l'aide d'un en-tête de
163 réponse HTTP prédéterminé nommé
164 <code>X-Replace-Session</code>.</p>
166 <example><title>Ecriture dans une session</title>
167 <highlight language="config">
169 SessionCookieName session path=/
170 SessionHeader X-Replace-Session
174 <p>L'en-tête doit contenir des paires clé/valeur sous le même
175 format que celui de la chaîne d'argument d'une URL, comme dans
176 l'exemple suivant. Donner pour valeur à une clé la chaîne vide a
177 pour effet de supprimer la clé de la session.</p>
179 <example><title>Script CGI pour écrire dans une session</title>
180 <highlight language="sh">
182 echo "Content-Type: text/plain"
183 echo "X-Replace-Session: key1=foo&key2=&key3=bar"
189 <p>Selon la configuration, les informations de la session peuvent
190 être extraites de la variable d'environnement HTTP_SESSION. Par
191 défaut la session est privée, et cette fonctionnalité doit donc
192 être explicitement activée via la directive <directive
193 module="mod_session">SessionEnv</directive>.</p>
195 <example><title>Lecture depuis une session</title>
196 <highlight language="config">
199 SessionCookieName session path=/
200 SessionHeader X-Replace-Session
204 <p>Une fois la lecture effectuée, la variable CGI
205 <code>HTTP_SESSION</code> doit contenir la valeur
206 <code>clé1=foo&clé3=bar</code>.</p>
209 <section id="sessionprivacy"><title>Confidentialité des
212 <p>En utilisant la fonctionnalité de votre navigateur "Afficher
213 les cookies", vous pouvez voir une réprésentation de la session
214 sous forme de texte en clair. Ceci peut poser problème si le
215 contenu de la session doit être dissimulé à l'utilisateur final,
216 ou si un tiers accède sans autorisation aux informations de
219 <p>A ce titre, le contenu de la session peut être chiffré à l'aide
220 du module <module>mod_session_crypto</module> avant d'être stocké
221 au niveau du navigateur.</p>
223 <example><title>Session chiffrée avant stockage au niveau du
225 <highlight language="config">
227 SessionCryptoPassphrase secret
228 SessionCookieName session path=/
232 <p>La session sera automatiquement déchiffrée à la lecture, et
233 rechiffrée par Apache lors de la sauvegarde, si bien que
234 l'application sous-jacente qui utilise la session n'a pas à se
235 préoccuper de savoir si un chiffrement a été mis en oeuvre ou
238 <p>Les sessions stockées sur le serveur plutôt qu'au niveau du
239 navigateur peuvent aussi être chiffrées, préservant par là-même la
240 confidentialité lorsque des informations sensibles sont partagées
241 entre les serveurs web d'une forêt de serveurs à l'aide du module
242 <module>mod_session_dbd</module>.</p>
245 <section id="cookieprivacy"><title>Confidentialité du cookie</title>
247 <p>Le mécanisme de cookie HTTP offre aussi des fonctionnalités
248 quant à la confidentialité, comme la possibilité de
249 restreindre le transport du cookie aux pages protégées par SSL
250 seulement, ou l'interdiction pour les scripts java qui
251 s'exécutent au niveau du navigateur d'obtenir l'accès au contenu
254 <note type="warning"><title>Avertissement</title>
255 <p>Certaines fonctionnalités de confidentialité du cookie HTTP ne
256 sont pas standardisées, ou ne sont pas toujours implémentées au
257 niveau du navigateur. Les modules de session vous permettent de
258 définir les paramètres du cookie, mais il n'est pas garanti que la
259 confidentialité sera respectée par le navigateur. Si la sécurité
260 est la principale préoccupation, chiffrez le contenu de la session
261 avec le module <module>mod_session_crypto</module>, ou stockez la
262 session sur le serveur avec le module
263 <module>mod_session_dbd</module>.</p>
266 <p>Les paramètres standards du cookie peuvent être spécifiés après
267 le nom du cookie comme dans l'exemple suivant :</p>
269 <example><title>Définition des paramètres du cookie</title>
270 <highlight language="config">
272 SessionCryptoPassphrase secret
273 SessionCookieName session path=/private;domain=example.com;httponly;secure;
277 <p>Dans les cas où le serveur Apache sert de frontal pour des
278 serveurs d'arrière-plan, il est possible de supprimer les cookies
279 de session des en-têtes HTTP entrants à l'aide de la directive
281 module="mod_session_cookie">SessionCookieRemove</directive>. Ceci
282 permet d'empêcher les serveurs d'arrière-plan d'accéder au contenu
283 des cookies de session.
287 <section id="authentication"><title>Support des sessions pour
288 l'authentification</title>
290 <p>Comme il est possible de le faire avec de nombreux serveurs
291 d'applications, les modules d'authentification peuvent utiliser
292 une session pour stocker le nom d'utilisateur et le mot de passe
293 après connexion. Le module <module>mod_auth_form</module> par
294 exemple, sauvegarde les nom de connexion et mot de passe de
295 l'utilisateur dans une session.</p>
297 <example><title>Authentification à base de formulaire</title>
298 <highlight language="config">
300 SessionCryptoPassphrase secret
301 SessionCookieName session path=/
302 AuthFormProvider file
303 AuthUserFile "conf/passwd"
310 <p>Pour la documentation et des exemples complets, voir le module
311 <module>mod_auth_form</module>.</p>
315 <section id="integration"><title>Intégration des sessions avec les
316 applications externes</title>
318 <p>Pour que les sessions soient utiles, leur contenu doit être
319 accessible aux applications externes, et ces dernières doivent
320 elles-mêmes être capables d'écrire une session.</p>
322 <p>L'exemple type est une application qui modifie le mot de passe
323 d'un utilisateur défini par <module>mod_auth_form</module>. Cette
324 application doit pouvoir extraire les nom d'utilisateur et mot de
325 passe courants de la session, effectuer les modifications
326 demandées, puis écrire le nouveau mot de passe dans la session,
327 afin que la transition vers le nouveau mot de passe soit
330 <p>Un autre exemple met en jeu une application qui enregistre un
331 nouvel utilisateur pour la première fois. Une fois
332 l'enregistrement terminé, le nom d'utilisateur et le mot de passe
333 sont écrits dans la session, fournissant là aussi une transition
337 <dt>Modules Apache</dt>
338 <dd>Selon les besoins, les modules du serveur peuvent utiliser
339 l'API <strong>mod_session.h</strong> pour lire et écrire dans les
340 sessions. Les modules tels que <module>mod_auth_form</module>
341 utilisent ce mécanisme.
344 <dt>Programmes CGI et langages de script</dt>
345 <dd>Les applications qui s'exécutent au sein du serveur web
346 peuvent éventuellement extraire la valeur de la session de la
347 variable d'environnement <strong>HTTP_SESSION</strong>. La session
348 doit être codée sous la forme d'une chaîne
349 <strong>application/x-www-form-urlencoded</strong> selon les
350 préconisations de la <a
351 href="http://www.w3.org/TR/html4/">specification HTML</a>. Cette
352 variable d'environnement est définie via la directive <directive
353 module="mod_session">SessionEnv</directive>. Un script peut écrire
354 dans la session en renvoyant un en-tête de réponse
355 <strong>application/x-www-form-urlencoded</strong> dont le nom est
356 défini via la directive <directive
357 module="mod_session">SessionHeader</directive>. Dans les deux cas,
358 tout chiffrement ou déchiffrement, ainsi que la lecture ou
359 l'écriture de ou vers la session à partir du mécanisme de stockage
360 choisi sont gérés par le module <module>mod_session</module> et la
361 configuration correspondante.
364 <dt>Applications situées derrière <module>mod_proxy</module></dt>
365 <dd>Si la directive <directive
366 module="mod_session">SessionHeader</directive> est utilisée pour
367 définir un en-tête de requête HTTP, la session codée sous la forme
368 d'une chaîne <strong>application/x-www-form-urlencoded</strong>
369 sera accessible pour l'application. Si ce même en-tête est fourni
370 dans la réponse, sa valeur sera utilisée pour remplacer la
371 session. Comme précédemment, tout chiffrement ou déchiffrement,
372 ainsi que la lecture ou
373 l'écriture de ou vers la session à partir du mécanisme de stockage
374 choisi sont gérés par le module <module>mod_session</module> et la
375 configuration correspondante.</dd>
377 <dt>Applications indépendantes</dt>
378 <dd>Les applications peuvent choisir de manipuler la session en
379 s'affranchissant du contrôle du serveur HTTP Apache. Dans ce cas,
380 c'est l'application qui doit prendre en charge la lecture de la
381 session depuis le mécanisme de stockage choisi, son déchiffrement,
382 sa mise à jour, son chiffrement et sa réécriture vers le mécanisme
383 de stockage choisi de manière appropriée.</dd>
390 <description>Ouvre une session pour le contexte courant</description>
391 <syntax>Session On|Off</syntax>
392 <default>Session Off</default>
393 <contextlist><context>server config</context>
394 <context>virtual host</context>
395 <context>directory</context>
396 <context>.htaccess</context>
398 <override>AuthConfig</override>
401 <p>La directive <directive>Session</directive> permet d'ouvrir une
402 session pour le contexte ou conteneur courant. Les directives
403 suivantes permettent de définir où la session sera stockée et
404 comment sera assurée la confidentialité.</p>
409 <name>SessionMaxAge</name>
410 <description>Définit une durée de vie maximale pour la session en
411 secondes</description>
412 <syntax>SessionMaxAge <var>durée de vie maximale</var></syntax>
413 <default>SessionMaxAge 0</default>
414 <contextlist><context>server config</context>
415 <context>virtual host</context>
416 <context>directory</context>
417 <context>.htaccess</context>
419 <override>AuthConfig</override>
422 <p>La directive <directive>SessionMaxAge</directive> permet de
423 définir la durée maximale pendant laquelle une session restera
424 valide. Lorsqu'une session est sauvegardée, cette durée est
425 réinitialisée et la session peut continuer d'exister. Si la durée
426 d'une session dépasse cette limite sans qu'une requête au serveur ne
427 vienne la rafraîchir, la session va passer hors délai et sera
428 supprimée. Lorsqu'une session est utilisée pour stocker les
429 informations de connexion d'un utilisateur, ceci aura pour effet de
430 le déconnecter automatiquement après le délai spécifié.</p>
432 <p>Donner à cette directive la valeur 0 empêche l'expiration de la
438 <name>SessionEnv</name>
439 <description>Définit si le contenu de la session doit être enregistré
440 dans la variable d'environnement <var>HTTP_SESSION</var></description>
441 <syntax>SessionEnv On|Off</syntax>
442 <default>SessionEnv Off</default>
443 <contextlist><context>server config</context>
444 <context>virtual host</context>
445 <context>directory</context>
446 <context>.htaccess</context>
448 <override>AuthConfig</override>
451 <p>Lorsque la directive <directive>SessionEnv</directive> est
452 définie à <var>On</var>, le contenu de la session est enregistré
453 dans une variable d'environnement CGI nommée
454 <var>HTTP_SESSION</var>.</p>
456 <p>La chaîne est écrite sous le même format que celui de la chaîne
457 d'arguments d'une URL, comme dans l'exemple suivant :</p>
460 <code>clé1=foo&clé3=bar</code>
467 <name>SessionHeader</name>
468 <description>Importation des mises à jour de session depuis l'en-tête de
469 réponse HTTP spécifié</description>
470 <syntax>SessionHeader <var>en-tête</var></syntax>
471 <default>none</default>
472 <contextlist><context>server config</context>
473 <context>virtual host</context>
474 <context>directory</context>
475 <context>.htaccess</context>
477 <override>AuthConfig</override>
480 <p>La directive <directive>SessionHeader</directive> permet de
481 définir le nom d'un en-tête de réponse HTTP qui, s'il est présent,
482 sera lu et son contenu écrit dans la session courante.</p>
484 <p>Le contenu de l'en-tête doit se présenter sous le même format que
485 celui de la chaîne d'arguments d'une URL, comme dans l'exemple
489 <code>clé1=foo&clé2=&clé3=bar</code>
492 <p>Si une clé a pour valeur la chaîne vide, elle sera supprimée de
499 <name>SessionInclude</name>
500 <description>Définit les préfixes d'URL pour lesquels une session est
502 <syntax>SessionInclude <var>chemin</var></syntax>
503 <default>toutes URLs</default>
504 <contextlist><context>server config</context>
505 <context>virtual host</context>
506 <context>directory</context>
507 <context>.htaccess</context>
509 <override>AuthConfig</override>
512 <p>La directive <directive>SessionInclude</directive> permet de
513 définir les préfixes d'URL spécifiques pour lesquels une session
514 sera valide. Ceci peut améliorer l'efficacité d'un site web, en
515 ciblant de manière plus précise l'espace d'URL pour lequel une
516 session devra être maintenue. Par défaut, toutes les URLs du
517 contexte ou du conteneur courant sont incluses dans la session.</p>
519 <note type="warning"><title>Avertissement</title>
520 <p>Cette directive a un comportement similaire à celui de l'attribut
521 <var>chemin</var> des cookies HTTP, mais ne doit pas être confondue
522 avec cet attribut. En effet, cette directive ne définit pas
523 l'attribut <var>chemin</var>, qui doit être configuré séparément.</p></note>
528 <name>SessionExclude</name>
529 <description>Définit les préfixes d'URLs pour lesquels une session sera
530 ignorée</description>
531 <syntax>SessionExclude <var>chemin</var></syntax>
532 <default>none</default>
533 <contextlist><context>server config</context>
534 <context>virtual host</context>
535 <context>directory</context>
536 <context>.htaccess</context>
538 <override>AuthConfig</override>
541 <p>La directive <directive>SessionExclude</directive> permet de
542 définir les préfixes d'URLs pour lesquels la session sera
543 désactivée. Ceci peut améliorer l'efficacité d'un site web, en
544 ciblant de manière plus précise l'espace d'URL pour lequel une
545 session devra être maintenue. Par défaut, toutes les URLs du
546 contexte ou du conteneur courant sont incluses dans la session. La
547 directive <directive module="mod_session">SessionExclude</directive>
548 l'emporte sur la directive <directive
549 module="mod_session">SessionInclude</directive>.</p>
551 <note type="warning"><title>Avertissement</title>
552 <p>Cette directive a un comportement similaire à celui de l'attribut
553 <var>chemin</var> des cookies HTTP, mais ne doit pas être confondue
554 avec cet attribut. En effet, cette directive ne définit pas
555 l'attribut <var>chemin</var>, qui doit être configuré
556 séparément.</p></note>
561 <name>SessionExpiryUpdateInterval</name>
562 <description>Définit le nombre de secondes dont la durée d'expiration d'une
563 session peut changer sans que cette session soit mise à jour</description>
564 <syntax>SessionExpiryUpdateInterval <var>interval</var></syntax>
565 <default>SessionExpiryUpdateInterval 0 (mise à jour systématique)</default>
566 <contextlist><context>server config</context>
567 <context>virtual host</context>
568 <context>directory</context>
569 <context>.htaccess</context>
571 <override>AuthConfig</override>
574 <p>La directive <directive>SessionExpiryUpdateInterval</directive>
575 permet d'éviter le coût de l'écriture d'une session pour chaque
576 requête en n'effectuant cette mise à jour que lorsque la date
577 d'expiration a changé. Ceci permet d'améliorer les performances d'un
578 site web ou de réduire la charge d'une base de données lorsqu'on
579 utilise <module>mod_session_dbd</module>. La session est
580 systématiquement mise à jour si les données stockées dans la session
581 ont été modifiées ou si la durée d'expiration a été modifiée d'une
582 durée supérieure à l'intervalle spécifié.</p>
584 <p>Définir l'intervalle à 0 désactive cette directive, et
585 l'expiration de la session sera alors rafraîchie pour chaque requête.</p>
587 <p>Cette directive n'a d'effet que si on l'utilise en combinaison
588 avec la directive <directive
589 module="mod_session">SessionMaxAge</directive> qui active
590 l'expiration des sessions. Les sessions sans date d'expiration ne
591 sont écrites que lorsque les données qu'elles renferment ont été
594 <note type="warning"><title>Avertissement</title>
595 <p>Comme l'expiration de la session n'est pas systématiquement
596 rafraîchie à chaque requête, une session peut arriver à expiration
597 plus tôt d'un nombre de secondes spécifié dans le paramètre
598 <var>interval</var>. Définir un petit intervalle est en général
599 assez sur, mais en revenche n'a qu'un effet minime sur la prise en
600 compte des durées d'expiration.</p></note>