Comment configurer l’authentification Apache htpasswd sur Ubuntu

L’authentification `htpasswd` d’Apache fournit l’authentification HTTP Basic — un mécanisme de contrôle d’accès côté serveur qui soumet toute requête de navigateur à une invite de nom d’utilisateur/mot de passe avant de servir le contenu. Elle ne nécessite aucun code au niveau de la couche applicative, fonctionne entièrement dans le système de modules d’Apache, et est appliquée au niveau du serveur web avant l’exécution de toute logique backend PHP, Python ou Node.js.

Cela en fait la méthode la plus rapide et la plus fiable pour protéger les environnements de staging, les panneaux d’administration internes, les versions de développement, et tout répertoire qui doit être caché de l’internet public sans déployer un fournisseur d’identité complet.

Quand htpasswd est le bon outil — et quand il ne l’est pas

Avant de saisir la moindre commande, comprenez le modèle de menace. L’authentification HTTP Basic transmet les identifiants sous forme de chaîne encodée en Base64 dans l’en-tête `Authorization`. Le Base64 n’est pas du chiffrement — il est trivialement réversible. Cela signifie que l’authentification htpasswd n’est sécurisée que lorsqu’elle est déployée via HTTPS. Sans TLS, les identifiants sont exposés en clair à tout observateur réseau.

Cas d’utilisation appropriés :

• Environnements de staging et de pré-production
• Outils et tableaux de bord internes pour développeurs
• Restriction temporaire d’un site pendant la maintenance
• Ajout d’une couche d’authentification secondaire devant une application disposant de sa propre connexion
• Protection de `wp-admin` ou `xmlrpc.php` WordPress au niveau du serveur

Cas d’utilisation inappropriés :

• Authentification principale pour les applications publiques traitant des données utilisateur sensibles
• Environnements où la rotation des identifiants doit être auditée et journalisée
• Systèmes multi-locataires nécessitant un contrôle d’accès basé sur les rôles

Si votre cas d’utilisation implique des comptes utilisateurs en production, envisagez plutôt OAuth2, LDAP ou la gestion de sessions au niveau applicatif.

Prérequis

• Un serveur Ubuntu 20.04, 22.04 ou 24.04 avec accès root ou `sudo`
• Apache 2.4 installé ou installable via `apt`
• Un domaine enregistré avec DNS pointant vers votre serveur (fortement recommandé pour SSL)
• Familiarité de base avec la ligne de commande Linux et les éditeurs de texte

Si vous partez de zéro, un environnement VPS Hosting vous offre un accès root complet et une image Ubuntu propre — la base idéale pour cette configuration.

Étape 1 : Installer Apache2

Si Apache n’est pas encore installé, mettez à jour l’index des paquets et installez-le :

“`bash

sudo apt update && sudo apt install apache2 -y

“`

Vérifiez l’installation et confirmez que le service est en cours d’exécution :

“`bash

sudo systemctl status apache2

apache2 -v

“`

Activez Apache pour qu’il démarre automatiquement au redémarrage :

“`bash

sudo systemctl enable apache2

“`

La racine de document par défaut d’Apache est `/var/www/html`. La configuration principale du site se trouve dans `/etc/apache2/sites-available/000-default.conf`.

Étape 2 : Installer le paquet apache2-utils

Le binaire `htpasswd` fait partie du paquet `apache2-utils`. Sur la plupart des installations Ubuntu, ce paquet est installé avec Apache, mais confirmez explicitement sa présence :

“`bash

which htpasswd

“`

Si la commande ne retourne rien, installez le paquet :

“`bash

sudo apt install apache2-utils -y

“`

Le paquet `apache2-utils` fournit également `htdigest` (pour l’authentification Digest), `ab` (Apache Bench pour les tests de charge), et `htdbm` (pour les fichiers de mots de passe au format DBM). Pour la plupart des scénarios, `htpasswd` avec le hachage bcrypt ou MD5 par défaut est suffisant.

Étape 3 : Créer le fichier .htpasswd et ajouter des utilisateurs

Choisir un algorithme de hachage de mot de passe

C’est un détail que la documentation originale omet presque universellement. L’utilitaire `htpasswd` prend en charge plusieurs schémas de hachage, et le choix a de réelles implications en matière de sécurité :

Utilisez toujours bcrypt pour les nouveaux fichiers `.htpasswd` :

“`bash

sudo htpasswd -cB /etc/apache2/.htpasswd your_username

“`

Explication des options :

• `-c` — Crée un nouveau fichier. Avertissement critique : Si le fichier existe déjà, `-c` l’écrase silencieusement, supprimant tous les utilisateurs existants. N’utilisez `-c` qu’une seule fois, lors de la création initiale du fichier.
• `-B` — Force le hachage bcrypt
• `/etc/apache2/.htpasswd` — Le chemin du fichier cible, intentionnellement en dehors de la racine web
• `your_username` — Remplacez par le nom d’utilisateur réel

Vous serez invité à saisir et confirmer le mot de passe. L’entrée résultante dans le fichier ressemble à :

“`

your_username:$2y$05$randomsaltandhashedpasswordstring

“`

Ajouter des utilisateurs supplémentaires

Pour ajouter d’autres utilisateurs à un fichier existant, omettez l’option `-c` :

“`bash

sudo htpasswd -B /etc/apache2/.htpasswd second_user

sudo htpasswd -B /etc/apache2/.htpasswd third_user

“`

Supprimer un utilisateur

“`bash

sudo htpasswd -D /etc/apache2/.htpasswd username_to_remove

“`

Vérifier le contenu du fichier

“`bash

sudo cat /etc/apache2/.htpasswd

“`

Chaque ligne représente un utilisateur au format `username:hashed_password`.

Étape 4 : Configurer Apache pour la protection par mot de passe

Il existe deux méthodes pour appliquer l’authentification htpasswd : via les fichiers `.htaccess` ou directement dans la configuration de l’hôte virtuel. Chacune a des implications distinctes en termes de performances et de maintenance.

Comparaison des méthodes

Sur un Serveur Dédié ou VPS où vous disposez d’un accès root complet, la méthode de configuration de l’hôte virtuel est toujours préférable pour les performances et la maintenabilité.

Option 1 : Utilisation des fichiers .htaccess

Cette méthode nécessite que `AllowOverride` soit activé pour le répertoire cible. Modifiez d’abord la configuration du site :

“`bash

sudo nano /etc/apache2/sites-available/000-default.conf

“`

Localisez ou ajoutez le bloc `<Directory>` pour votre racine web et définissez `AllowOverride All` :

“`apache

<VirtualHost *:80>

ServerAdmin webmaster@localhost

DocumentRoot /var/www/html

<Directory /var/www/html>

AllowOverride All

Options -Indexes +FollowSymLinks

Require all granted

</Directory>

</VirtualHost>

“`

Redémarrez Apache pour appliquer le changement de configuration :

“`bash

sudo systemctl restart apache2

“`

Créez maintenant le fichier `.htaccess` dans le répertoire que vous souhaitez protéger :

“`bash

sudo nano /var/www/html/.htaccess

“`

Ajoutez les directives d’authentification suivantes :

“`apache

AuthType Basic

AuthName "Restricted Access — Authorized Personnel Only"

AuthUserFile /etc/apache2/.htpasswd

Require valid-user

“`

Explication des directives :

• `AuthType Basic` — Active l’authentification HTTP Basic. L’alternative est `Digest`, qui évite d’envoyer les identifiants en Base64 mais présente des problèmes de compatibilité plus larges.
• `AuthName` — La chaîne de domaine affichée dans la boîte de dialogue de connexion du navigateur. Rendez-la suffisamment descriptive pour que les utilisateurs légitimes comprennent ce à quoi ils accèdent.
• `AuthUserFile` — Chemin absolu vers le fichier `.htpasswd`. Doit être lisible par l’utilisateur du processus Apache (`www-data`).
• `Require valid-user` — Accorde l’accès à tout utilisateur présent dans le fichier `.htpasswd`. Vous pouvez restreindre davantage avec `Require user alice bob` pour n’autoriser que des comptes spécifiques.

Enregistrez et fermez le fichier. Aucun redémarrage d’Apache n’est nécessaire — les modifications `.htaccess` prennent effet immédiatement.

Option 2 : Configuration directe de l’hôte virtuel (recommandée)

C’est l’approche adaptée à la production. Modifiez directement le fichier de configuration de l’hôte virtuel :

“`bash

sudo nano /etc/apache2/sites-available/000-default.conf

“`

Ajoutez un bloc `<Directory>` avec des directives d’authentification à l’intérieur du bloc `<VirtualHost>` :

“`apache

<VirtualHost *:80>

ServerAdmin webmaster@localhost

DocumentRoot /var/www/html

ServerName yourdomain.com

<Directory "/var/www/html/protected">

AuthType Basic

AuthName "Internal Tools"

AuthUserFile /etc/apache2/.htpasswd

Require valid-user

Options -Indexes

</Directory>

</VirtualHost>

“`

Notez l’utilisation de `/var/www/html/protected` plutôt que de l’ensemble de la racine web. La limitation de l’authentification à un sous-répertoire est bien plus courante en pratique — vous protégez `/admin`, `/staging`, ou `/api-docs` tout en laissant le site public accessible.

Validez la syntaxe de la configuration avant de redémarrer :

“`bash

sudo apachectl configtest

“`

Vous devriez voir `Syntax OK`. En cas d’erreurs, Apache les décrira précisément. Ne redémarrez jamais Apache sans avoir passé cette vérification en production.

Redémarrez Apache :

“`bash

sudo systemctl restart apache2

“`

Protéger des types de fichiers spécifiques plutôt que des répertoires

Un modèle moins connu mais très pratique consiste à utiliser `<FilesMatch>` pour restreindre l’accès à des extensions de fichiers spécifiques plutôt qu’à des répertoires entiers :

“`apache

<FilesMatch ".(env|log|sql|bak)$">

AuthType Basic

AuthName "Restricted Files"

AuthUserFile /etc/apache2/.htpasswd

Require valid-user

</FilesMatch>

“`

Ceci est particulièrement utile pour bloquer l’accès direct aux fichiers `.env`, aux dumps de base de données, ou aux fichiers journaux qui peuvent exister dans la racine web pour des raisons héritées.

Étape 5 : Activer SSL avant la mise en production

Comme établi précédemment, l’authentification HTTP Basic sur HTTP simple est non sécurisée. Avant d’exposer toute ressource protégée par htpasswd à internet, appliquez HTTPS.

Installez Certbot pour les certificats Let’s Encrypt :

“`bash

sudo apt install certbot python3-certbot-apache -y

sudo certbot –apache -d yourdomain.com

“`

Certbot modifiera automatiquement votre configuration Apache pour rediriger HTTP vers HTTPS et installera le certificat. Vous pouvez également provisionner un certificat commercial via Certificats SSL pour les domaines nécessitant une validation étendue ou une couverture wildcard.

Après avoir activé SSL, ajoutez une redirection HTTPS à votre hôte virtuel HTTP :

“`apache

<VirtualHost *:80>

ServerName yourdomain.com

Redirect permanent / https://yourdomain.com/

</VirtualHost>

“`

Étape 6 : Renforcer les permissions du fichier .htpasswd

Le fichier `.htpasswd` contient des identifiants hachés. Même si les hachages bcrypt sont coûteux en calcul à craquer, le fichier doit être protégé au niveau du système de fichiers.

Définissez la propriété sur l’utilisateur du processus Apache et restreignez les permissions de lecture :

“`bash

sudo chown root:www-data /etc/apache2/.htpasswd

sudo chmod 640 /etc/apache2/.htpasswd

“`

Cette configuration signifie :

• `root` possède le fichier et peut le lire/écrire
• `www-data` (le processus Apache) peut le lire
• Tous les autres utilisateurs n’ont aucun accès

Vérifiez les permissions :

“`bash

ls -la /etc/apache2/.htpasswd

“`

Résultat attendu :

“`

-rw-r—– 1 root www-data 89 Jan 15 10:23 /etc/apache2/.htpasswd

“`

Bloquer l’accès web direct au fichier .htpasswd

Si pour une raison quelconque le fichier `.htpasswd` se trouve dans la racine web, ajoutez une règle de refus explicite à votre configuration Apache ou à votre fichier `.htaccess` :

“`apache

<Files ".htpasswd">

Require all denied

</Files>

“`

Il s’agit d’une mesure de défense en profondeur. Le fichier ne devrait jamais se trouver dans la racine web, mais cette règle garantit que même s’il y est, Apache retournera une réponse 403 Forbidden plutôt que de servir le fichier.

Étape 7 : Tester l’authentification

Ouvrez un navigateur et accédez à l’URL protégée :

“`

http://your_server_ip_or_domain/protected/

“`

Vous devriez voir une boîte de dialogue d’authentification native du navigateur. Saisissez les identifiants que vous avez créés avec `htpasswd`. Une authentification réussie accorde l’accès ; des identifiants incorrects retournent une réponse HTTP 401 Unauthorized.

Tester depuis la ligne de commande

Utilisez `curl` pour vérifier le comportement de l’authentification sans navigateur :

“`bash

Test with correct credentials — should return 200 OK

curl -u your_username:your_password -I http://yourdomain.com/protected/

Test without credentials — should return 401 Unauthorized

curl -I http://yourdomain.com/protected/

Test with wrong credentials — should return 401 Unauthorized

curl -u your_username:wrongpassword -I http://yourdomain.com/protected/

“`

Ceci est particulièrement utile dans les pipelines CI/CD ou les scripts de surveillance automatisés où vous devez vérifier que l’authentification est correctement appliquée après les déploiements.

Modèles de configuration avancés

Combiner htpasswd avec le contrôle d’accès basé sur l’IP

Vous pouvez combiner l’authentification par mot de passe avec la liste blanche d’IP en utilisant des blocs `RequireAll` ou `RequireAny` :

“`apache

<Directory "/var/www/html/admin">

AuthType Basic

AuthName "Admin Panel"

AuthUserFile /etc/apache2/.htpasswd

Allow access if EITHER condition is met

<RequireAny>

Require ip 192.168.1.0/24

Require valid-user

</RequireAny>

</Directory>

“`

Ou exiger les DEUX conditions simultanément (l’IP doit correspondre ET les identifiants doivent être valides) :

“`apache

<RequireAll>

Require ip 203.0.113.0/24

Require valid-user

</RequireAll>

“`

Ce modèle est extrêmement efficace pour les panneaux d’administration : les utilisateurs du réseau interne obtiennent un accès avec invite de mot de passe, tandis que les IP externes sont complètement bloquées indépendamment des identifiants.

Limiter le débit des tentatives d’authentification

L’authentification HTTP Basic n’a pas de protection intégrée contre la force brute. Atténuez cela avec `mod_evasive` ou `fail2ban` :

“`bash

sudo apt install fail2ban -y

“`

Créez un filtre Fail2ban personnalisé pour les échecs d’authentification Apache dans `/etc/fail2ban/filter.d/apache-auth.conf` :

“`ini

[Definition]

failregex = ^<HOST> -.*"(GET|POST|HEAD).*" 401

ignoreregex =

“`

Ajoutez une configuration de jail dans `/etc/fail2ban/jail.local` :

“`ini

[apache-auth]

enabled = true

port = http,https

filter = apache-auth

logpath = /var/log/apache2/access.log

maxretry = 5

bantime = 3600

findtime = 600

“`

Redémarrez Fail2ban :

“`bash

sudo systemctl restart fail2ban

“`

Cela bannit toute IP qui génère cinq réponses 401 en dix minutes pendant une heure — un moyen de dissuasion significatif contre le credential stuffing automatisé.

Utilisation des blocs Location pour la protection basée sur l’URL

Pour les applications où le contenu protégé est servi depuis un chemin URL spécifique plutôt qu’un répertoire du système de fichiers, utilisez `<Location>` au lieu de `<Directory>` :

“`apache

<Location "/api/internal">

AuthType Basic

AuthName "Internal API"

AuthUserFile /etc/apache2/.htpasswd

Require user api_user service_account

</Location>

“`

Notez l’utilisation de `Require user` avec des noms d’utilisateurs spécifiques plutôt que `Require valid-user` — cela restreint le point de terminaison à ces deux comptes uniquement, même si le fichier `.htpasswd` contient des utilisateurs supplémentaires.

Matrice de décision pratique

Utilisez cette matrice pour déterminer la bonne approche de configuration selon votre scénario :

Points techniques clés à retenir

• Utilisez toujours bcrypt (option `-B`) lors de la création de fichiers `.htpasswd`. Les hachages MD5 et SHA-1 hérités sont craquables avec du matériel GPU moderne en quelques secondes.
• Ne déployez jamais htpasswd sur HTTP dans tout environnement accessible depuis internet. L’encodage Base64 des identifiants Basic Auth ne fournit aucune confidentialité.
• Préférez la configuration de l’hôte virtuel à `.htaccess` sur tout serveur où vous disposez d’un accès root. La différence de performance est mesurable sous charge car Apache relit les fichiers `.htaccess` à chaque requête.
• Limitez la protection au répertoire ou chemin URL strictement nécessaire. Protéger `/var/www/html` entièrement alors que seul `/var/www/html/admin` nécessite une protection ajoute une friction inutile.
• Définissez les permissions `.htpasswd` à `640` avec la propriété `root:www-data`. Le fichier ne doit jamais être lisible par tous.
• Implémentez Fail2ban pour prévenir les attaques par force brute. L’authentification HTTP Basic n’a pas de mécanisme natif de limitation du débit ou de verrouillage de compte.
• Validez la configuration Apache avec `apachectl configtest` avant chaque redémarrage dans les environnements de production.
• Associez htpasswd à votre infrastructure de domaine. Un domaine correctement configuré avec DNS et SSL est la fondation — gérez le vôtre via Enregistrement de domaine pour regrouper tous les composants d’infrastructure chez un seul fournisseur.

Pour les équipes gérant plusieurs environnements protégés, un VPS avec cPanel fournit une interface graphique pour gérer les répertoires protégés par mot de passe sans accès direct à la ligne de commande, ce qui peut réduire les erreurs de configuration dans les équipes moins techniques.

FAQ

L’authentification htpasswd fonctionne-t-elle avec tous les navigateurs ?

Oui. L’authentification HTTP Basic est définie dans la RFC 7617 et est prise en charge par tous les navigateurs modernes, notamment Chrome, Firefox, Safari et Edge. Les navigateurs mobiles la prennent également en charge. L’apparence de la boîte de dialogue native du navigateur varie selon le navigateur et le système d’exploitation, mais le comportement du protocole sous-jacent est identique.

Que se passe-t-il si le chemin du fichier .htpasswd est incorrect dans la configuration Apache ?

Apache retournera une erreur 500 Internal Server Error pour toute requête vers la ressource protégée et journalisera une erreur similaire à `Could not open password file: /path/to/.htpasswd` dans `/var/log/apache2/error.log`. Vérifiez toujours que le chemin absolu est correct et que l’utilisateur `www-data` dispose de la permission de lecture sur le fichier.

Puis-je utiliser htpasswd pour protéger la zone d’administration d’un site WordPress ?

Oui, et c’est une pratique de renforcement recommandée. L’ajout de la protection htpasswd à `/wp-admin/` et la restriction de l’accès à `xmlrpc.php` ajoute une couche d’authentification au niveau du serveur avant l’exécution de la propre logique de connexion de WordPress, bloquant les bots automatisés et les scripts de force brute qui n’atteignent jamais PHP. Configurez-le comme un bloc `<Directory>` dans votre hôte virtuel plutôt que via `.htaccess` pour de meilleures performances.

Comment mettre à jour le mot de passe d’un utilisateur dans un fichier .htpasswd existant ?

Exécutez `htpasswd` sans l’option `-c` et spécifiez le nom d’utilisateur existant : `sudo htpasswd -B /etc/apache2/.htpasswd existing_user`. Vous serez invité à saisir le nouveau mot de passe. La commande écrase uniquement l’entrée de cet utilisateur, laissant tous les autres utilisateurs intacts.

Y a-t-il une limite au nombre d’utilisateurs pouvant être stockés dans un fichier .htpasswd ?

Il n’y a pas de limite stricte imposée par Apache. Cependant, comme Apache effectue un balayage linéaire du fichier pour chaque requête d’authentification, les performances se dégradent notablement avec des fichiers très volumineux — généralement au-delà de plusieurs centaines d’utilisateurs. Pour les environnements nécessitant une authentification pour des dizaines ou des centaines d’utilisateurs, envisagez `mod_authn_dbd` avec un backend de base de données, ou l’authentification LDAP via `mod_authnz_ldap`, qui sont conçus pour passer à l’échelle.