mod_auth_form
Authentification à l'aide d'un formulaire
Base
mod_auth_form.c
auth_form_module
Disponible à partir d'Apache 2.3

# Avertissement

L'authentification à base de formulaire dépend des modules mod_session qui utilisent les cookies HTTP, et en tant que tels s'exposent à des attaques de type Cross Site Scripting, ou risquent de divulguer des informations à caractère privé aux clients. Assurez-vous que ces risques ont bien été pris en compte avant d'activer les sessions sur votre serveur.

Ce module permet de restreindre l'accès en recherchant les utilisateurs dans les fournisseurs spécifiés à l'aide d'un formulaire de connexion HTML. Les formulaires HTML requièrent davantage de configuration que les méthodes d'authentification alternatives, mais ils peuvent s'avérer beaucoup plus conviviaux pour les utilisateurs.

L'authentification HTTP de base est fournie par le module mod_auth_basic, et l'authentification HTTP à base de condensé par le module mod_auth_digest. Le module mod_auth_form doit être utilisé avec au moins un module d'authentification du style mod_authn_file et un module d'autorisation comme mod_authz_user.

Lorsque l'utilisateur a été authentifié avec succès, ses informations de connexion sont stockés dans une session fournie par le module mod_session.

mod_session
AuthName
AuthType
Require
Mise en oeuvre de l'authentification

# 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.

## Exemple simple

<Location "/admin"> AuthFormProvider file AuthUserFile "conf/passwd" AuthType form AuthName "/admin" AuthFormLoginRequiredLocation "http://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.

## Exemple de formulaire de connexion

<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 :

## Exemple de configuration du gestionnaire de formulaire de connexion

<Location "/dologin.html"> SetHandler form-login-handler AuthFormLoginRequiredLocation "http://example.com/login.html" AuthFormLoginSuccessLocation "http://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.

## Exemple de formulaire d'authentification multizone

<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

## Avertissement

Il existe un risque, dans certaines circonstances, que le formulaire de connexion configuré pour une connexion à la volée soit soumis plusieurs fois, révélant de ce fait les paramètres de connexion à l'application sous-jacente. L'administrateur doit s'assurer que cette dernière est correctement sécurisée afin d'éviter les éventuels abus. En cas de doute, utilisez une page de connexion indépendante dédié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 :

## Exemple simple d'authentification à la volée

AuthFormProvider file ErrorDocument 401 "/login.shtml" AuthUserFile "conf/passwd" AuthType form AuthName realm AuthFormLoginRequiredLocation "http://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.

## Exemple de formulaire de connexion à la volée

<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 :

## Exemple de formulaire avec conservation du contenu

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

## Exemple avec script CGI

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.

## Exemple simple de configuration de la déconnexion

SetHandler form-logout-handler AuthName realm AuthFormLogoutLocation "http://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).

## Exemple simple avec durée de validité de session limitée

SetHandler form-logout-handler AuthFormLogoutLocation "http://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.

AuthFormProvider
Définit le(s) fournisseur(s) d'authentification pour la zone concernée
AuthFormProvider nom fournisseur [nom fournisseur] ...
AuthFormProvider file
directory
.htaccess
AuthConfig

La directive AuthFormProvider permet de définir quel fournisseur sera utilisé pour authentifier les utilisateurs pour la zone concernée. Le fournisseur par défaut `file` est implémenté par le module mod_authn_file. Assurez-vous que le fournisseur choisi soit bien présent dans le serveur.

# Exemple

<Location "/secure"> AuthType form AuthName "private area" AuthFormProvider dbm AuthDBMType SDBM AuthDBMUserFile "/www/etc/dbmpasswd" Require valid-user #... </Location>

Les différents fournisseurs sont implémentés par les modules mod_authn_dbm, mod_authn_file, mod_authn_dbd et mod_authnz_ldap.

AuthFormAuthoritative
Détermine si l'autorisation et l'authentification sont confiés à des modules de plus bas niveau
AuthFormAuthoritative On|Off
AuthFormAuthoritative On
directory
.htaccess
AuthConfig

Normalement, chacun des modules d'autorisation spécifiés par la directive AuthFormProvider va tenter de vérifier l'identité de l'utilisateur, et si ce dernier n'est trouvé dans aucun fournisseur, l'accès sera refusé. En définissant explicitement la directive AuthFormAuthoritative à `Off` on confie les processus d'authentification et d'autorisation à des modules ne s'appuyant pas sur des fournisseurs, si aucun identifiant utilisateur ou aucune règle ne correspond à l'identifiant utilisateur fourni. Ceci ne peut s'avérer nécessaire que si l'on combine mod_auth_form avec des modules tiers qui ne se configurent pas avec la directive AuthFormProvider. Lorsqu'on utilise de tels modules, la chronologie du processus est déterminée dans leur code source, et n'est pas configurable.

AuthFormUsername
Le nom du champ de formulaire qui contient le nom de connexion
AuthFormUsername nom du champ
httpd_username
directory
Disponible depuis la version 2.3.3 du serveur HTTP Apache

La directive AuthFormUsername permet de spécifier le nom du champ HTML qui, s'il existe, contiendra le nom d'utilisateur qui sera utilisé pour la connexion.

AuthFormPassword
Le nom du champ de formulaire qui contient le mot de passe de connexion
AuthFormPassword nom du champ
httpd_password
directory
Disponible depuis la version 2.3.0 du serveur HTTP Apache

La directive AuthFormPassword permet de spécifier le nom du champ HTML qui, s'il existe, contiendra le mot de passe qui sera utilisé pour la connexion.

AuthFormLocation
Le nom du champ de formulaire qui contiendra l'URL vers laquelle l'utilisateur sera redirigé en cas de connexion réussie
AuthFormLocation nom du champ
httpd_location
directory
Disponible depuis la version 2.3.0 du serveur HTTP Apache

La directive AuthFormLocation spécifie le nom du champ HTML qui, s'il existe, contiendra l'URL vers laquelle rediriger le navigateur en cas de connexion réussie.

AuthFormMethod
Le nom du champ de formulaire contenant la méthode de la requête à effectuer en cas de connexion réussie
AuthFormMethod nom du champ
httpd_method
directory
Disponible depuis la version 2.3.0 du serveur HTTP Apache

La directive AuthFormMethod spécifie le nom du champ HTML qui, s'il existe, contiendra le type MIME de la requête à effectuer en cas de connexion réussie.

En ajoutant au formulaire les champs décrits dans AuthFormMethod, AuthFormMimetype et AuthFormBody, un site web sera en mesure de relancer une requête qui a été éventuellement interrompue par l'écran de connexion, ou par l'expiration d'un délai de session.

AuthFormMimetype
Le nom du champ de formulaire contenant le type MIME du corps de la requête à effectuer en cas de connexion réussie
AuthFormMimetype nom du champ
httpd_mimetype
directory
Disponible depuis la version 2.3.0 du serveur HTTP Apache

La directive AuthFormMimetype spécifie le nom du champ HTML qui, s'il existe, contiendra le type MIME de la requête à effectuer en cas de connexion réussie.

En ajoutant au formulaire les champs décrits dans AuthFormMethod, AuthFormMimetype et AuthFormBody, un site web sera en mesure de relancer une requête qui a été éventuellement interrompue par l'écran de connexion, ou par l'expiration d'un délai de session.

AuthFormBody
Le nom du champ de formulaire contenant le corps de la requête à effectuer en cas de connexion réussie
AuthFormBody nom du champ
httpd_body
directory
Disponible depuis la version 2.3.0 du serveur HTTP Apache

La directive AuthFormBody spécifie le nom du champ HTML qui, s'il existe, contiendra le corps de la requête à effectuer en cas de connexion réussie.

En ajoutant au formulaire les champs décrits dans AuthFormMethod, AuthFormMimetype et AuthFormBody, un site web sera en mesure de relancer une requête qui a été éventuellement interrompue par l'écran de connexion, ou par l'expiration d'un délai de session.

AuthFormSize
La taille maximale en octets du formulaire dont seront extraites les informations de connexion
AuthFormSize taille
8192
directory
Disponible depuis la version 2.3.0 du serveur HTTP Apache

La directive AuthFormSize spécifie la taille maximale du corps de la requête qui sera utilisée pour trouver le formulaire de connexion.

Si une requête de connexion entrante possède une taille supérieure à cette valeur, elle sera rejetée avec le code de réponse HTTP `HTTP_REQUEST_TOO_LARGE`.

Si vous avez ajouté au formulaire des champs décrits dans AuthFormMethod, AuthFormMimetype et AuthFormBody, il est recommandé de définir cette directive à une valeur similaire à celle de la directive KeptBodySize.

AuthFormLoginRequiredLocation
L'URL de la page vers laquelle on doit être redirigé si une authentification est requise
AuthFormLoginRequiredLocation url
none
directory
Disponible depuis la version 2.3.0 du serveur HTTP Apache. L'interprétation des expressions rationnelles est supportée depuis la version 2.4.4.

La directive AuthFormLoginRequiredLocation spécifie l'URL vers laquelle l'utilisateur devra être redirigé s'il n'est pas autorisé à accéder à une page. Sa valeur est interprétée via l'interpréteur ap_expr avant d'être envoyée au client. Par défaut, si un utilisateur n'est pas autorisé à accéder à une page, le code de réponse HTTP `HTTP_UNAUTHORIZED` est renvoyé avec la page spécifiée par la directive ErrorDocument. La directive AuthFormLoginRequiredLocation permet de remplacer cette valeur par défaut.

Vous pouvez utiliser cette directive si vous voulez présenter une page de connexion personnalisée à vos utilisateurs.

AuthFormLoginSuccessLocation
L'URL de la page vers laquelle on doit être redirigé en cas de connexion réussie
AuthFormLoginSuccessLocation url
none
directory
Disponible depuis la version 2.3.0 du serveur HTTP Apache. L'interprétation des expressions rationnelles est supportée depuis la version 2.4.4.

La directive AuthFormLoginSuccessLocation spécifie l'URL vers laquelle l'utilisateur doit être redirigé en cas de connexion réussie. Sa valeur est interprétée via l'interpréteur ap_expr avant d'être envoyée au client. L'effet de cette directive peut être annulé si l'on a défini un champ de formulaire contenant une autre URL à l'aide de la directive AuthFormLocation.

Vous pouvez utiliser cette directive si vous possédez une URL de connexion personnalisée, et si vous n'avez pas intégré la page de destination dans le formulaire de connexion.

AuthFormFakeBasicAuth
Simule une en-tête d'authentification de base
AuthFormFakeBasicAuth On|Off
AuthFormFakeBasicAuth Off
directory
Disponible depuis la version 2.3.0 du serveur HTTP Apache

Le drapeau AuthFormFakeBasicAuth détermine si une en-tête d'`Authentification de base` sera ajoutée aux en-têtes de la requête. On peut utiliser cette méthode pour présenter le nom d'utilisateur et le mot de passe à l'application sous-jacente, sans que cette dernière ait besoin de connaître la manière dont le processus de connexion a été mené à bien.

AuthFormLogoutLocation
L'URL vers laquelle un utilisateur devra être redirigé après s'être déconnecté
AuthFormLogoutLocation uri
none
directory
Disponible depuis la version 2.3.0 du serveur HTTP Apache. L'interprétation des expressions rationnelles est supportée depuis la version 2.4.4.

La directive AuthFormLogoutLocation spécifie l'URL de la page du serveur vers laquelle l'utilisateur devra être redirigé s'il se déconnecte. Sa valeur est interprétée via l'interpréteur ap_expr avant d'être envoyée au client.

Lorsqu'un accès est tenté sur un URI traité par le gestionnaire `form-logout-handler`, la page spécifiée par cette directive sera présentée à l'utilisateur final. Par exemple :

# Exemple

<Location "/logout"> SetHandler form-logout-handler AuthFormLogoutLocation "http://example.com/loggedout.html" Session on #... </Location>

Si un utilisateur tente d'accéder à l'URI /logout/, il sera déconnecté, et la page /loggedout.html lui sera présentée. Assurez-vous que la page loggedout.html n'est pas protégée par mot de passe, car dans le cas contraire, elle ne serait pas affichée.

AuthFormDisableNoStore
Désactive l'en-tête CacheControl no-store sur la page de connexion
AuthFormDisableNoStore On|Off
AuthFormDisableNoStore Off
directory
Disponible depuis la version 2.3.0 du serveur HTTP Apache

Le drapeau AuthFormDisableNoStore supprime l'envoi d'un en-tête `Cache-Control no-store` lorsqu'une page avec code d'erreur 401 est renvoyée, si l'utilisateur n'est pas encore connecté. Avec cette en-tête, il est plus difficile pour une application `ecmascript` de resoumettre un formulaire de connexion, et ainsi révéler le nom d'utilisateur et le mot de passe à l'application sous-jacente. Vous devez être conscient des risques encourus si vous le désactivez.

AuthFormSitePassphrase
Court-circuite l'authentification pour les sites à fort trafic
AuthFormSitePassphrase secret
none
directory
Disponible depuis la version 2.3.0 du serveur HTTP Apache

La directive AuthFormSitePassphrase spécifie un mot de passe qui, s'il est présent dans la session utilisateur, indique à Apache httpd de court-circuiter l'authentification pour l'URL considérée. On peut l'utiliser dans le cas de sites web à fort trafic afin de réduire la charge induite sur l'infrastructure d'authentification.

On peut insérer le mot de passe dans une session utilisateur en ajoutant cette directive à la configuration concernant le gestionnaire form-login-handler. Le gestionnaire form-login-handler, quant à lui, effectuera toujours les vérifications d'authentification, qu'un mot de passe soit spécifié ou non.

# Avertissement

Si la session est présentée à l'utilisateur à l'aide du module mod_session_cookie, et si la session n'est pas protégée par le module mod_session_crypto, le mot de passe peut faire l'objet d'une attaque de type dictionnaire. Quelle que soit la configuration de la session, assurez-vous que cette directive n'est pas utilisée dans un espace d'URLs contenant des données privées, ou à partir desquelles des transactions sensibles pourraient être menées. En tout état de cause, vous devez être conscient des risques encourus avant de l'utiliser.