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 dera redirigé vers la page du formulaire de connexion.

<Location "/admin">
    AuthFormProvider file
    AuthUserFile "conf/passwd"
    AuthType form
    AuthName "/admin"
    AuthFormLoginRequiredLocation "https://example.com/login.html"

    Session On
    SessionCookieName session path=/

    Require valid-user
</Location>

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 et SessionCookieName 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.

Vous pouvez éventuellement ajouter une directive SessionCryptoPassphrase pour créer un cookie de session chiffré. Pour utiliser cette directive, le module mod_session_crypto doit avoir été préalablement chargé.

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 d'entrer 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 "https://example.com/login.html"
    AuthFormLoginSuccessLocation "https://example.com/admin/index.html"
    AuthFormProvider file
    AuthUserFile "conf/passwd"
    AuthType form
    AuthName /admin
    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="https://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 "https://example.com/login.html"
Session On
SessionCookieName session path=/

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 "https://example.com/loggedout.html"
Session On
SessionCookieName session path=/

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 valeur faible à 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 "https://example.com/loggedout.html"
Session On
SessionMaxAge 1
SessionCookieName session path=/

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.