review documentation

Author: dbarzin

INSTALL.debian.fr.md

@@ -79,13 +79,14 @@ Mettre les paramètre de connexion à la base de données :
 
     vi .env
 
-    ## .env file
-    DB_CONNECTION=mysql
-    DB_HOST=127.0.0.1
-    DB_PORT=3306
-    DB_DATABASE=deming
-    DB_USERNAME=deming_user
-    DB_PASSWORD=demPasssword-123
+```dotenv
+DB_CONNECTION=mysql
+DB_HOST=127.0.0.1
+DB_PORT=3306
+DB_DATABASE=deming
+DB_USERNAME=deming_user
+DB_PASSWORD=demPasssword-123
+```
 
 ## Créer la base de données
 
@@ -137,23 +138,23 @@ Pour importer un référentiel et générer des données de test, allez dans "Co
 Il est également possible de faire démarrer l'application en tant que service `systemd`. Pour cela, créez un nouveau fichier de définition du service :
 
 	su root -c "vi /etc/systemd/system/deming.service"
- 
+
 Ajoutez les lignes suivantes:
 
 	[Unit]
 	Description=Deming
 	After=network.target
 	After=mariadb.service
 	After=apache2.service
-	
+
 	[Service]
 	Type=simple
 	ExecStart=/usr/bin/php artisan serve --host 127.0.0.1 --port 8000
 	User=www-data
 	Group=www-data
 	WorkingDirectory=/var/www/deming
 	KillMode=mixed
-	
+
 	[Install]
 	WantedBy=multi-user.target
 
@@ -206,21 +207,21 @@ Ajouter les lignes suivantes :
 
 	<VirtualHost *:80>
 	   ServerName deming.local
-	
+
 	    RewriteEngine On
 	    RewriteRule ^/?(.*) https://%{SERVER_NAME}/$1
 	</VirtualHost>
-	
+
 	<VirtualHost *:443>
 	    ServerName deming.local
 	    DocumentRoot /var/www/deming/public
-	
+
 	    Protocols h2 h2c http/1.1
-	
+
 	    <Directory /var/www/deming>
 	        AllowOverride All
 	    </Directory>
-	
+
 	    ProxyPass / http://127.0.0.1:8000/
 	    ProxyPassReverse / http://127.0.0.1:8000/
 	    ProxyPreserveHost On
@@ -229,10 +230,10 @@ Ajouter les lignes suivantes :
 	    #<FilesMatch \.php$>
 	    #    SetHandler "proxy:unix:/var/run/php/php8.2-fpm.sock|fcgi://localhost/"
 	    #</FilesMatch>
-	
+
     	    ErrorLog ${APACHE_LOG_DIR}/error.log
     	    CustomLog ${APACHE_LOG_DIR}/access.log combined
-	
+
 	    <IfModule mod_headers.c>
 	        Header always set Strict-Transport-Security "max-age=15552000; includeSubDomains; preload"
 	        Header always set Referrer-Policy "no-referrer"
@@ -242,7 +243,7 @@ Ajouter les lignes suivantes :
 	        Header always set X-Frame-Options "SAMEORIGIN"
 	        Header edit Set-Cookie ^(.*)$ "$1;HttpOnly;Secure;SameSite=Strict"
 	    </IfModule>
-	
+
 	    SSLEngine on
 	    SSLCertificateFile  /etc/apache2/ssl/deming.local.crt
 	    SSLCertificateKeyFile /etc/apache2/ssl/deming.local.key
@@ -269,23 +270,139 @@ Après avoir modifié le(s) fichier(s) php.ini, vous devez redémarrer le servic
 Si vous souhaitez envoyer des e-mails de notification depuis Deming.
 Vous devez configurer l'accès au serveur SMTP dans .env
 
-    MAIL_HOST='smtp.localhost'
-    MAIL_PORT=2525
-    MAIL_AUTH=true
-    MAIL_SMTP_SECURE='ssl'
-    MAIL_SMTP_AUTO_TLS=false
-    MAIL_USERNAME=
-    MAIL_PASSWORD=
+```dotenv
+MAIL_HOST='smtp.localhost'
+MAIL_PORT=2525
+MAIL_AUTH=true
+MAIL_SMTP_SECURE='ssl'
+MAIL_SMTP_AUTO_TLS=false
+MAIL_USERNAME=
+MAIL_PASSWORD=
+```
 
 Vous pouvez également configurer DKIM :
 
-    MAIL_DKIM_DOMAIN = 'admin.local';
-    MAIL_DKIM_PRIVATE = '/path/to/private/key';
-    MAIL_DKIM_SELECTOR = 'default'; // Match your DKIM DNS selector
-    MAIL_DKIM_PASSPHRASE = '';      // Only if your key has a passphrase
+```dotenv
+MAIL_DKIM_DOMAIN = 'admin.local';
+MAIL_DKIM_PRIVATE = '/path/to/private/key';
+MAIL_DKIM_SELECTOR = 'default'; // Match your DKIM DNS selector
+MAIL_DKIM_PASSPHRASE = '';      // Only if your key has a passphrase
+```
 
 N'oubliez pas de [configurer](https://dbarzin.github.io/deming/config.fr/#notifications) le contenu et la fréquence d'envoi des mails.
 
+## LDAP / LDAPRecord configuration (optional)
+
+Cette section te permet d’activer l’authentification LDAP dans Deming avec **LDAPRecord v2**. Elle fonctionne indifféremment avec **Active Directory** *ou* **OpenLDAP**, et peut cohabiter avec l’authentification locale (base de données).
+
+### Prérequis
+
+Prérequis : l’extension PHP LDAP doit être installée et active.
+
+```bash
+sudo apt-get install php-ldap
+sudo systemctl restart apache2
+```
+
+### Environnement
+
+Ajouter / adapter les variables suivantes :
+
+```dotenv
+# Activation LDAP dans Deming (mode hybride)
+LDAP_ENABLED=true                 # Active l’authentification LDAP
+LDAP_FALLBACK_LOCAL=true          # Si LDAP échoue, tenter l’auth locale
+LDAP_AUTO_PROVISION=false         # Créer automatiquement l’utilisateur local après bind LDAP OK
+
+# Connexion au serveur LDAP
+LDAP_HOST=ldap.example.org
+LDAP_PORT=389                     # 389 (StartTLS) ou 636 (LDAPS)
+LDAP_BASE_DN=dc=example,dc=org
+LDAP_USERNAME=cn=admin,dc=example,dc=org   # Compte de service pour la recherche
+LDAP_PASSWORD=********
+LDAP_TLS=true                     # StartTLS (recommandé si port 389)
+LDAP_SSL=false                    # true si tu utilises ldaps:// sur 636
+LDAP_TIMEOUT=5                    # (optionnel)
+
+# Attributs candidats pour identifier l’utilisateur saisi dans le formulaire
+# L’ordre a de l’importance : le premier qui matche est utilisé.
+# OpenLDAP: uid, cn, mail ; AD: sAMAccountName, userPrincipalName, mail
+LDAP_LOGIN_ATTRIBUTES=uid,cn,mail,sAMAccountName,userPrincipalName
+```
+
+**Exemples**
+
+* OpenLDAP (DN utilisateur typique : `uid=jdupont,ou=people,dc=example,dc=org`) :
+
+  ```dotenv
+  LDAP_TLS=true
+  LDAP_SSL=false
+  LDAP_LOGIN_ATTRIBUTES=uid,cn,mail
+  ```
+* Active Directory (UPN : `jdupont@example.org`, sAM : `jdupont`) :
+
+  ```dotenv
+  LDAP_TLS=true
+  LDAP_SSL=false
+  LDAP_LOGIN_ATTRIBUTES=sAMAccountName,userPrincipalName,mail,cn
+  LDAP_USERNAME=EXAMPLE\\svc_ldap   # ou DN complet du compte de service
+  ```
+
+Après modification du `.env` :
+
+```bash
+php artisan config:clear
+php artisan optimize:clear
+```
+
+### Certificats
+
+**Certificats** : si tu utilises StartTLS/LDAPS avec un CA interne, ajoute le CA au trust store de ta distribution (ex. `/usr/local/share/ca-certificates` + `update-ca-certificates`).
+
+### Comment ça marche côté Deming
+
+Le contrôleur d’authentification :
+
+* recherche l’entrée LDAP via une **OR**-query sur les attributs listés dans `LDAP_LOGIN_ATTRIBUTES` ;
+* récupère le **DN** ;
+* tente un **bind** avec le mot de passe saisi ;
+* si OK, il connecte l’utilisateur applicatif local correspondant (et peut **auto-provisionner** s’il n’existe pas, selon `LDAP_AUTO_PROVISION`).
+
+### Test rapide
+
+Avant de tester via l’UI, valide la connexion en CLI :
+
+```bash
+php artisan tinker
+```
+
+Puis dans Tinker :
+
+```php
+use LdapRecord\Container;
+
+$dn = 'uid=jdupont,ou=people,dc=example,dc=org';  // ou cn=..., ou DN AD
+Container::getConnection()->auth()->attempt($dn, 'MOT_DE_PASSE', true);
+// => true attendu si l’authentification réussit
+```
+
+### Dépannage express
+
+* **PHP LDAP manquant** : `php -m | grep ldap` doit renvoyer `ldap`. Sinon `sudo apt-get install php-ldap`, puis redémarrage PHP/Apache.
+* **Mauvais DN** : ajoute les `ou=...` corrects (ex. `ou=people`).
+* **TLS/SSL** : StartTLS = `LDAP_TLS=true` (389). LDAPS = `LDAP_SSL=true` (636). Ne laisse pas en clair en prod.
+* **Certificat non approuvé** : ajoute le CA au système (voir ci-dessus).
+* **Recherche impossible** : vérifie `LDAP_USERNAME` / `LDAP_PASSWORD` (compte de service) et les ACL de l’annuaire.
+* **Attribut de login** : aligne `LDAP_LOGIN_ATTRIBUTES` avec ce que tes utilisateurs saisissent réellement (uid ? UPN ? email ?).
+
+### Sécurité – à faire, pas à discuter
+
+* Utilise **TLS/LDAPS**. Point.
+* Restreins les droits du **compte de service** au strict nécessaire (lecture des attributs requis).
+* Évite de logger des mots de passe ou DN complets côté application.
+* Si tu actives l’**auto-provisioning**, stocke un mot de passe aléatoire côté base (pas un duplicat du LDAP) et applique tes politiques de rôles/profils.
+
+
 ## Sheduler
 
 Modifier le crontab

INSTALL.fr.md

@@ -300,7 +300,7 @@ Prérequis : l’extension PHP LDAP doit être installée et active.
 
 ```bash
 sudo apt-get install php-ldap
-sudo systemctl restart php8.3-fpm || sudo systemctl restart apache2
+sudo systemctl restart apache2
 ```
 ### Environnement
 

INSTALL.md

@@ -294,7 +294,7 @@ The PHP LDAP extension must be installed and enabled.
 
 ```bash
 sudo apt-get install php-ldap
-sudo systemctl restart php8.3-fpm || sudo systemctl restart apache2
+sudo systemctl restart apache2
 ```
 
 ### Environment