2 <!DOCTYPE modulesynopsis SYSTEM "../style/modulesynopsis.dtd">
3 <?xml-stylesheet type="text/xsl" href="../style/manual.fr.xsl"?>
4 <!-- English Revision: 1531961:1659902 (outdated) -->
5 <!-- French translation : Lucien GENTIS -->
6 <!-- Reviewed by : Vincent Deffontaines -->
9 Licensed to the Apache Software Foundation (ASF) under one or more
10 contributor license agreements. See the NOTICE file distributed with
11 this work for additional information regarding copyright ownership.
12 The ASF licenses this file to You under the Apache License, Version 2.0
13 (the "License"); you may not use this file except in compliance with
14 the License. You may obtain a copy of the License at
16 http://www.apache.org/licenses/LICENSE-2.0
18 Unless required by applicable law or agreed to in writing, software
19 distributed under the License is distributed on an "AS IS" BASIS,
20 WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
21 See the License for the specific language governing permissions and
22 limitations under the License.
25 <modulesynopsis metafile="mod_authn_socache.xml.meta">
27 <name>mod_authn_socache</name>
28 <description>Gère un cache des données d'authentification pour diminuer
29 la charge des serveurs d'arrière-plan</description>
31 <sourcefile>mod_authn_socache.c</sourcefile>
32 <identifier>authn_socache_module</identifier>
33 <compatibility>Versions 2.3 et ultérieures</compatibility>
36 <p>Maintient un cache des données d'authentification pour limiter
37 les sollicitations du serveur d'arrière-plan.</p>
40 <section id="intro"><title>Mise en cache des données d'authentification</title>
41 <p>Certains utilisateurs qui mettent oeuvre une authentification
42 lourde s'appuyant par exemple sur des requêtes SQL
43 (<module>mod_authn_dbd</module>) ont signalé une charge induite
44 inacceptable sur leur fournisseur d'authentification. Cela se
45 produit typiquement dans le cas où une page HTML contient des
46 centaines d'objets (images, scripts, pages de styles, media,
47 etc...), et où une requête pour cette page génère des centaines de
48 sous-requêtes à effet immédiat pour des contenus supplémentaires
49 authentifiés.</p>
50 <p>Pour résoudre ce problème, mod_authn_socache fournit une solution
51 qui permet de maintenir un cache des données d'authentification.</p>
54 <section id="usage"><title>Utilisation</title>
55 <p>Le cache d'authentification doit être utilisé lorsque les
56 requêtes d'authentification induisent une charge significative sur le
57 serveur, le serveur d'arrière-plan ou le réseau. Cette mise en cache
58 n'apportera probablement aucune amélioration dans le cas d'une
59 authentification à base de fichier (<module>mod_authn_file</module>)
60 ou de base de données dbm (<module>mod_authn_dbm</module>) car ces
61 méthodes sont de par leur conception rapides et légères (la mise en
62 cache peut cependant s'avérer utile dans le cas où le fichier est
63 situé sur un montage réseau). Les fournisseurs d'authentification
64 basés sur SQL ou LDAP ont plus de chances de tirer parti de cette
65 mise en cache, en particulier lorsqu'un problème de performances est
66 détecté. <module>mod_authnz_ldap</module> gérant son propre cache,
67 seul <module>mod_authn_dbd</module> est concerné par notre sujet.</p>
68 <p>Les principales règles à appliquer pour la mise en cache sont :</p>
69 <ol><li>Inclure le fournisseur pour lequel vous voulez effectuer une
70 mise en cache dans une directive
71 <directive>AuthnCacheProvideFor</directive>.</li>
72 <li>Mettre <var>socache</var> avant le fournisseur pour lequel
73 vous voulez effectuer une mise en cache dans votre directive
74 <directive module="mod_auth_basic">AuthBasicProvider</directive>
76 module="mod_auth_digest">AuthDigestProvider</directive>.</li>
78 <p>Voici un exemple simple permettant d'accélérer
79 <module>mod_authn_dbd</module> et utilisant dbm comme moteur de la
81 <highlight language="config">
82 #AuthnCacheSOCache est optionnel. S'il est défini, il l'est pour
83 #l'ensemble du serveur
85 <Directory /usr/www/myhost/private>
87 AuthName "Cached Authentication Example"
88 AuthBasicProvider socache dbd
89 AuthDBDUserPWQuery "SELECT password FROM authn WHERE user = %s"
90 AuthnCacheProvideFor dbd
93 AuthnCacheContext dbd-authn-example
98 <section id="dev"><title>La mise en cache avec les modules tiers</title>
99 <p>Les développeurs de modules doivent savoir que la mise en cache
100 avec mod_authn_socache doit être activée dans leurs modules. La
101 fonction de l'API <var>ap_authn_cache_store</var> permet de
102 mettre en cache les données d'authentification qu'un fournisseur
103 vient de rechercher ou de générer. Vous trouverez des exemples
104 d'utilisation à <a
105 href="http://svn.eu.apache.org/viewvc?view=revision&revision=957072"
106 >r957072</a>, où trois fournisseurs authn sont activés pour la mise
111 <name>AuthnCacheEnable</name>
112 <description>Active la mise en cache de l'authentification en tout
113 endroit</description>
114 <syntax>AuthnCacheEnable</syntax>
115 <contextlist><context>server config</context></contextlist>
116 <override>None</override>
119 <p>Normalement, cette directive n'est pas nécessaire : l'activation
120 est implicite si la mise en cache de l'authentification a été
121 activée en tout autre endroit du fichier <var>httpd.conf</var>. Par
122 contre, si cette mise en cache n'a pas été activée, par défaut, elle
123 ne sera pas initialisée, et ne sera donc pas disponible dans un
124 contexte de fichier <var>.htaccess</var>. Cette directive permet
125 d'être sûr que la mise en cache a bien été activée et pourra
126 donc être utilisée dans les fichiers <var>.htaccess</var>.</p>
131 <name>AuthnCacheSOCache</name>
132 <description>Sélectionne le fournisseur socache d'arrière-plan à
133 utiliser</description>
134 <syntax>AuthnCacheSOCache <var>nom-fournisseur[:arguments-fournisseur]</var></syntax>
135 <contextlist><context>server config</context></contextlist>
136 <override>None</override>
139 <p>Cette définition s'applique à l'ensemble du serveur et permet de
140 sélectionner un fournisseur pour le <a href="../socache.html">cache
141 d'objets partagés</a>, ainsi que des arguments éventuels pour ce
142 fournisseur. Les fournisseurs disponibles sont, entre autres, "dbm",
143 "dc", "memcache", ou "shmcb", chacun d'entre eux nécessitant le chargement
144 du module approprié. Si elle est
145 absente, c'est la valeur par défaut pour votre plate-forme qui sera
151 <name>AuthnCacheProvideFor</name>
152 <description>Spécifie le fournisseur pour lequel on veut effectuer une
153 mise en cache</description>
154 <syntax>AuthnCacheProvideFor <var>fournisseur-authn</var> [...]</syntax>
155 <default>None</default>
156 <contextlist><context>directory</context><context>.htaccess</context></contextlist>
157 <override>AuthConfig</override>
160 <p>Cette directive permet de spécifier un ou plusieurs fournisseurs
161 pour le(s)quel(s) on veut effectuer une mise en cache. Les données
162 d'authentification trouvées par un fournisseur non spécifié dans une
163 directive AuthnCacheProvideFor ne seront pas mises en cache.</p>
165 <p>Par exemple, pour mettre en cache les données d'authentification
166 trouvées par <module>mod_authn_dbd</module> ou par un fournisseur
167 personnalisé <var>mon-fournisseur</var>, et ne pas mettre en cache
168 celles trouvées par les fournisseurs légers comme file ou dbm :</p>
169 <highlight language="config">
170 AuthnCacheProvideFor dbd mon-fournisseur
176 <name>AuthnCacheTimeout</name>
177 <description>Définit une durée de vie pour les entrées du cache</description>
178 <syntax>AuthnCacheTimeout <var>durée-de-vie</var> (secondes)</syntax>
179 <default>300 (5 minutes)</default>
180 <contextlist><context>directory</context><context>.htaccess</context></contextlist>
181 <override>AuthConfig</override>
184 <p>La mise en cache des données d'authentification peut constituer
185 un trou de sécurité, bien qu'un mise en cache de courte durée ne
186 posera probablement pas de problème. En général, il est conseillé de
187 conserver les entrées du cache de façon à ce que la charge du serveur
188 d'arrière-plan reste normale, mais pas plus longtemps ;
189 une durée de vie plus longue peut être paramétrée si les
190 changements d'utilisateurs et de mots de passe sont peu fréquents.
191 La durée de vie par défaut de 300 secondes (5 minutes) est à la fois
192 raisonnable et suffisamment importante pour réduire la charge d'un
193 serveur d'arrière-plan comme dbd (requêtes SQL).</p>
194 <p>Cette durée de vie ne doit pas être confondue avec la durée de
195 vie de session qui est un tout autre sujet. Cependant, vous devez
196 utiliser votre logiciel de gestion de session pour vérifier si les
197 données d'authentification mises en cache peuvent allonger
198 accidentellement une session, et en tenir compte lorsque vous
199 définissez la durée de vie.</p>
204 <name>AuthnCacheContext</name>
205 <description>Spécifie une chaîne de contexte à utiliser dans la clé du
207 <syntax>AuthnCacheContext <var>directory|server|chaîne-personnalisée</var></syntax>
208 <default>directory</default>
209 <contextlist><context>directory</context></contextlist>
212 <p>Cette directive permet de spécifier une chaîne à utiliser avec le
213 nom d'utilisateur fourni (et le domaine d'authentification - realm -
214 dans le cas d'une authentification à base de condensés) lors de la
215 construction d'une clé de cache. Ceci permet de lever l'ambiguïté
216 entre plusieurs noms d'utilisateurs identiques servant différentes
217 zones d'authentification sur le serveur.</p>
218 <p>Il y a deux valeurs spéciales pour le paramètre : <var>directory</var>,
219 qui utilise le contexte de répertoire de la requête comme chaîne, et
220 <var>server</var>, qui utilise le nom du serveur virtuel.</p>
221 <p>La valeur par défaut est <var>directory</var>, qui est aussi la
222 définition la plus courante. Ceci est cependant loin d'être optimal,
223 car par exemple, <var>$app-base</var>, <var>$app-base/images</var>,
224 <var>$app-base/scripts</var> et <var>$app-base/media</var>
225 possèderont chacun leur propre clé de cache. Il est préférable
226 d'utiliser le fournisseur de mot de passe : par exemple un fichier
227 <var>htpasswd</var> ou une table de base de données.</p>
228 <p>Les contextes peuvent être partagés entre différentes zones du
229 serveur, où les données d'authentification sont partagées. Ceci est
230 cependant susceptible de créer des trous de sécurité de type
231 cross-site ou cross-application, et cette directive n'est donc pas
232 disponible dans les contextes <var>.htaccess</var>.</p>