Module Apache mod_auth_form

Configuration de base

Pour prot�ger une URL particuli�re avec le module mod_auth_form, vous devez d�terminer l'endroit o� vous allez stocker votre session, ainsi que la m�thode d'authentification. Dans cet exemple simple, les informations de connexion sont stock�es dans une session � l'aide du module mod_session_cookie, et l'authentification utilise un fichier en s'appuyant sur le module mod_authn_file. Si l'authentification �choue, l'utilisateur sera redirig� vers la page du formulaire de connexion.

AuthFormProvider file
AuthUserFile conf/passwd
AuthType form
AuthName realm
AuthFormLoginRequiredLocation http://example.com/login.html
Session On
SessionCookieName session path=/
SessionCryptoPassphrase secret

L'authentification mod_auth_form est activ�e en affectant la valeur form � la directive AuthType. Les directives AuthFormProvider et AuthUserFile sp�cifient que les noms d'utilisateurs et mots de passe seront v�rifi�s en utilisant le fichier choisi.

Les directives Session, SessionCookieName et SessionCryptoPassphrase cr�ent une session chiffr�e stock�e dans un cookie HTTP au niveau du navigateur. Pour plus d'informations � propos des diff�rentes options de configuration des sessions, reportez-vous � la documentation du module mod_session.

Dans l'exemple simple ci-dessus, une URL a �t� prot�g�e par mod_auth_form, mais on doit maintenant fournir � l'utilisateur un moyen de saisir un nom et un mot de passe. � cet effet, on peut soit �crire une page de connexion ind�pendante d�di�e, soit inclure le formulaire de connexion dans la page courante.

Page de connexion d�di�e

Le formulaire de connexion peut �tre contenu dans une page ind�pendante, ou �tre inclus dans la page courante.

Lorsque la connexion s'effectue � partir d'une page ind�pendante et si la tentative d'authentification �choue, l'utilisateur doit �tre redirig� vers un formulaire de connexion, cr�� � cet effet sur le site web, en utilisant la directive AuthFormLoginRequiredLocation. En g�n�ral, la page de connexion contiendra un formulaire HTML demandant � l'utilisateur de fournir un nom et un mot de passe.

<form method="POST" action="/dologin.html">
  Username: <input type="text" name="httpd_username" value="" />
  Password: <input type="password" name="httpd_password" value="" />
  <input type="submit" name="login" value="Login" />
</form>

La partie o� s'effectue la connexion proprement dite est trait�e par le gestionnaire form-login-handler. L'action de ce formulaire doit pointer vers ce gestionnaire, ce que l'on configure dans Apache httpd comme suit :

<Location /dologin.html>
    SetHandler form-login-handler
    AuthFormLoginRequiredLocation http://example.com/login.html
    AuthFormLoginSuccessLocation http://example.com/success.html
    AuthFormProvider file
    AuthUserFile conf/passwd
    AuthType form
    AuthName realm
    Session On
    SessionCookieName session path=/
    SessionCryptoPassphrase secret
</Location>

L'URL sp�cifi�e par la directive AuthFormLoginRequiredLocation r�f�rencera en g�n�ral une page expliquant � l'utilisateur que sa tentative de connexion a �chou�, et qu'il doit la renouveler. La directive AuthFormLoginSuccessLocation sp�cifie l'URL vers laquelle l'utilisateur doit �tre redirig� s'il s'est authentifi� avec succ�s.

Alternativement, l'URL vers laquelle doit �tre redirig� l'utilisateur s'il s'est authentifi� avec succ�s peut �tre int�gr�e dans le formulaire de connexion, comme dans l'exemple ci-dessous. Il en d�coule que le m�me gestionnaire form-login-handler pourra �tre utilis� pour diff�rentes zones du site web.

<form method="POST" action="/dologin.html">
  Username: <input type="text" name="httpd_username" value="" />
  Password: <input type="password" name="httpd_password" value="" />
  <input type="submit" name="login" value="Login" />
  <input type="hidden" name="httpd_location" value="http://example.com/success.html" />
</form>

Connexion � la vol�e

Comme alternative � la page de connexion d�di�e pour un site web, il est possible de configurer mod_auth_form pour authentifier les utilisateurs � la vol�e, sans les rediriger vers une autre page, ce qui permet de conserver l'�tat de la page courante au cours de la tentative de connexion. Ceci peut s'av�rer utile dans le cas d'une session limit�e dans le temps, si le d�lai de la session a expir� pendant la requ�te de l'utilisateur. Ce dernier peut alors se r�authentifier � la m�me place, et poursuivre son activit� � partir du point o� il en �tait rest�.

Si un utilisateur non authentifi� tente d'acc�der � une page prot�g�e par mod_auth_form, et si ce dernier n'est pas configur� avec une directive AuthFormLoginRequiredLocation, un code de statut HTTP_UNAUTHORIZED est renvoy� vers le navigateur, indiquant � l'utilisateur qu'il n'est pas autoris� � acc�der � cette page.

Pour configurer l'authentification � la vol�e, l'administrateur remplace le message d'erreur renvoy� par le code de statut HTTP_UNAUTHORIZED par un message d'erreur personnalis� contenant le formulaire de connexion comme suit :

AuthFormProvider file
ErrorDocument 401 /login.shtml
AuthUserFile conf/passwd
AuthType form
AuthName realm
AuthFormLoginRequiredLocation http://example.com/login.html
Session On
SessionCookieName session path=/
SessionCryptoPassphrase secret

La page du message d'erreur doit contenir un formulaire de connexion dont la propri�t� action est vide, comme dans l'exemple ci-dessous. Ceci a pour effet de soumettre le formulaire � l'URL prot�g�e originale, cette derni�re n'ayant pas besoin d'�tre connue de la page en cours.

<form method="POST" action="">
  Username: <input type="text" name="httpd_username" value="" />
  Password: <input type="password" name="httpd_password" value="" />
  <input type="submit" name="login" value="Login" />
</form>

Lorsque l'utilisateur final a entr� ses informations de connexion, le formulaire effectue une requ�te HTTP POST pour l'URL originale prot�g�e par mot de passe. mod_auth_form va alors intercepter cette requ�te POST, et dans le cas o� des champs HTML Utilisateur et Mot de passe corrects sont pr�sents, l'utilisateur sera connect�, et l'URL originale prot�g�e par mot de passe lui sera retourn�e en tant que requ�te GET.

Connexion � la vol�e avec conservation du contenu

Il existe une limite � la technique de connexion � la vol�e d�crite ci-dessus ; si un formulaire HTML POST entra�ne une demande d'authentification ou de r�authentification, le contenu du formulaire original envoy� par le navigateur sera perdu. Cela peut s'av�rer plus ou moins g�nant pour l'utilisateur final selon la fonction du site web.

Comme solution � ce probl�me, mod_auth_form permet d'int�grer la m�thode et le contenu de la requ�te originale dans le formulaire de connexion. Si l'authentification r�ussit, Apache httpd pourra refaire une tentative avec la m�thode et le contenu originaux, tout en conservant l'�tat de la requ�te originale.

Pour mettre en oeuvre la conservation du contenu, vous devez ajouter trois champs suppl�mentaires au formulaire de connexion comme dans l'exemple suivant :

<form method="POST" action="">
  Username: <input type="text" name="httpd_username" value="" />
  Password: <input type="password" name="httpd_password" value="" />
  <input type="submit" name="login" value="Login" />
  
  <input type="hidden" name="httpd_method" value="POST" />
  <input type="hidden" name="httpd_mimetype" value="application/x-www-form-urlencoded" />
  <input type="hidden" name="httpd_body" value="name1=value1&name2=value2" />

</form>

La mani�re dont la m�thode, le type MIME et le contenu de la requ�te originale seront int�gr�s dans le formulaire de connexion vont d�pendre de la plate-forme et de la technologie utilis�es au sein du site web.

Une option consiste � utiliser le module mod_include en association avec la directive KeptBodySize, ainsi qu'un script CGI adapt� pour int�grer les variables dans le formulaire.

Une autre option consiste � pr�senter le formulaire de connexion en utilisant un script CGI ou une autre technologie dynamique.

        AuthFormProvider file
        ErrorDocument 401 /cgi-bin/login.cgi
        ...

D�connexion

Pour permettre � un utilisateur de se d�connecter d'une session particuli�re, vous devez configurer une page pour qu'elle soit trait�e par le gestionnaire form-logout-handler. Tout acc�s � cette URL va entra�ner la suppression de l'Utilisateur et du Mot de passe de la session courante, ce qui aura pour effet de d�connecter l'utilisateur.

Vous pouvez sp�cifier une URL vers laquelle le navigateur sera redirig� en cas de d�connection r�ussie, en d�finissant la directive AuthFormLogoutLocation. Cette URL devra expliquer � l'utilisateur qu'il a �t� d�connect�, et lui donner la possibilit� de se connecter � nouveau.

SetHandler form-logout-handler
AuthName realm
AuthFormLogoutLocation http://example.com/loggedout.html
Session On
SessionCookieName session path=/
SessionCryptoPassphrase secret

Notez que la d�connexion d'un utilisateur ne supprime pas la session ; elle supprime seulement l'Utilisateur et le mot de passe de la session. Si la session qui en r�sulte est vide, elle sera probablement supprim�e, mais ce n'est pas garanti. Si vous voulez �tre s�r que la session sera supprim�e, affectez une petite valeur � la directive SessionMaxAge, par exemple 1 (affecter � cette directive la valeur z�ro signifie une session sans limite d'�ge).

SetHandler form-logout-handler
AuthFormLogoutLocation http://example.com/loggedout.html
Session On
SessionMaxAge 1
SessionCookieName session path=/
SessionCryptoPassphrase secret

Noms d'utilisateurs et mots de passe

Notez que la soumission d'un formulaire implique l'encodage URL (URLEncoding) des donn�es du formulaire, ici le nom d'utilisateur et le mot de passe. Vous devez donc choisir des noms d'utilisateurs et mots de passe qui ne contiennent pas de caract�res susceptibles d'�tre encod�s URL lors de la soumission du formulaire, sous peine d'obtenir des r�sultats inattendus.