Skip to content

Commit 74cf366

Browse files
tacxoutacxou
committed
documentation cron password mdp
1 parent 6d27a8f commit 74cf366

4 files changed

Lines changed: 185 additions & 1 deletion

File tree

‎docs/configuration/config-gestion-mdp.md‎

Lines changed: 57 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -37,6 +37,63 @@ Ces deux limites sont representé dans l'interface de changement de mot de passe
3737
* Caractères obligatoires : Vous pouvez régler quels caractères obligatoires doit comporter le nouveau mot de passe
3838
* Vérifier si le mot de passe est connu avec haveibeenpwned (voir [https://haveibeenpwned.com/](https://haveibeenpwned.com/)). Si le mot de passe est connu l'utilisateur ne pourra pas l'utiliser
3939

40+
### Vérification HIBP et empreintes planifiées
41+
42+
Deux niveaux complémentaires :
43+
44+
| Option (interface) | Champ API | Effet |
45+
| --- | --- | --- |
46+
| Vérifier les mots de passe compromis | `checkPwned` | Refus immédiat à la saisie si le mot de passe est dans HIBP (k-anonymity) |
47+
| Stockage des empreintes HIBP | `pwnedRecheckEnabled` | Enregistre une empreinte SHA-1 **chiffrée** dans l'historique pour re-vérifier plus tard via cron |
48+
49+
Le stockage d'empreintes **nécessite** :
50+
51+
- l'historique des mots de passe (`passwordHistoryEnabled`, activé par défaut) ;
52+
- `checkPwned` activé ;
53+
- la variable d'environnement `SESAME_PASSWORD_HISTORY_HIBP_KEY` sur l'orchestrateur.
54+
55+
#### Génération de la clé
56+
57+
Depuis le dépôt `sesame-orchestrator` :
58+
59+
```bash
60+
make hibp-key-hex
61+
# affiche : SESAME_PASSWORD_HISTORY_HIBP_KEY=<64_caracteres_hex>
62+
63+
# alternative base64 (32 octets décodés)
64+
make hibp-key-b64
65+
```
66+
67+
Formats acceptés :
68+
69+
- **Hex** : exactement 64 caractères hexadécimaux (32 octets) ;
70+
- **Base64** : chaîne qui décode en 32 octets.
71+
72+
#### Configuration Docker / `.env`
73+
74+
Ajouter dans le fichier d'environnement de **sesame-orchestrator** :
75+
76+
```env
77+
SESAME_PASSWORD_HISTORY_HIBP_KEY=votre_cle_generee
78+
```
79+
80+
Puis redémarrer le conteneur. Sans cette clé, l'interface désactive le toggle « Stockage des empreintes HIBP » et la sauvegarde de la policy avec `pwnedRecheckEnabled=true` est refusée.
81+
82+
#### Activation dans l'interface
83+
84+
1. Menu **Paramètres → Politique de mot de passe**.
85+
2. Activer **Vérifier les mots de passe compromis**.
86+
3. Activer **Stockage des empreintes HIBP (Pwned Passwords)** (si la clé est valide).
87+
4. Régler **Âge max avant re-check HIBP** (secondes) — par défaut 7 jours.
88+
5. Sauvegarder.
89+
6. Activer la tâche cron `identities-pwned-recheck` (voir [Configuration cron](cron.html#tache-par-defaut-re-check-hibp-pwned-passwords)).
90+
91+
#### Sécurité et rotation de clé
92+
93+
- Le mot de passe en clair n'est **pas** stocké pour HIBP : seule l'empreinte SHA-1 chiffrée (`hibpSha1Enc`).
94+
- Le serveur peut déchiffrer l'empreinte **uniquement** avec `SESAME_PASSWORD_HISTORY_HIBP_KEY` pour interroger l'API HIBP en mode *range* (5 premiers caractères du hash envoyés, reste comparé localement).
95+
- **Rotation de clé** : sans ré-encryptage des entrées existantes, les anciennes empreintes ne pourront plus être re-vérifiées (statut « déchiffrement impossible » côté cron).
96+
4097
* Réinitialisez par SMS : L'utilisateur aura le choix de recevoir son code de réinitialisation par mail ou par SMS
4198
### Les paramêtres d'envoi
4299
#### Initialisation du mot de passe

‎docs/configuration/cron.md‎

Lines changed: 45 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -91,6 +91,51 @@ Le contenu des emails (jalons, templates, sujets) est défini dans `settings.pas
9191
- `passwordExpirationReminderSubject` (sujet par défaut)
9292
- template par défaut backend (si non fourni sur le jalon) : `password_reminder`
9393

94+
## Tâche par défaut : re-check HIBP (Pwned Passwords)
95+
96+
Fichier fourni : `defaults/cron/identities-pwned-recheck.yml`
97+
98+
Configuration livrée :
99+
100+
```yml
101+
tasks:
102+
- name: "identities-pwned-recheck"
103+
description: "Re-check HIBP (pwned passwords) for stored password history fingerprints"
104+
enabled: false
105+
schedule: "0 3 * * *"
106+
handler: "identities-pwned-recheck"
107+
options:
108+
limit: 500
109+
```
110+
111+
### Prérequis
112+
113+
- Policy : `pwnedRecheckEnabled=true` et historique des mots de passe actif.
114+
- Variable `SESAME_PASSWORD_HISTORY_HIBP_KEY` configurée sur l'orchestrateur.
115+
- Entrées d'historique avec `hibpSha1Enc` renseigné (créées après activation du stockage d'empreintes).
116+
117+
### Activation
118+
119+
1. Ouvrir ou copier le fichier dans `configs/cron/identities-pwned-recheck.yml`.
120+
2. Passer `enabled` à `true`.
121+
3. Ajuster `schedule` si besoin (défaut : tous les jours à 03:00).
122+
4. Optionnel : modifier `options.limit` (nombre max d'entrées traitées par exécution, défaut 500).
123+
124+
Vous pouvez aussi activer la tâche depuis l'interface **Paramètres → Cron** (`/settings/cron`).
125+
126+
### Comportement
127+
128+
- **Handler** : `identities-pwned-recheck` → commande `yarn run console identities pwned recheck`.
129+
- Sélectionne les entrées d'historique ayant une empreinte (`hibpSha1Enc`) dont `hibpLastCheckAt` est absent ou plus ancien que `pwnedRecheckMaxAgeSeconds` (policy).
130+
- Déchiffre l'empreinte, appelle `https://api.pwnedpasswords.com/range/<prefix>` (k-anonymity), met à jour `hibpLastCheckAt` et `hibpPwnCount`.
131+
- Si `hibpPwnCount > 0`, applique `pwnedRecheckAction` : `none` (log uniquement), `notify` (email), `expire` (forcer changement de mot de passe).
132+
133+
### Test manuel
134+
135+
```bash
136+
yarn run console identities pwned recheck --limit=10
137+
```
138+
94139
## Variables dynamiques dans `options`
95140

96141
Les `options` supportent des variables dynamiques évaluées au runtime (à chaque exécution de la tâche).

‎docs/pages/settings/cron.md‎

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -38,3 +38,18 @@ Cette page permet de gérer les **tâches planifiées** (route `/settings/cron`)
3838
- envoie les emails pour les jalons correspondants (`J-30`, `J-7`, `J-1`, `J0`, etc.)
3939
- évite les doublons via l’historique (`passwordExpiryReminderSentDays`)
4040

41+
## Tâche liée au re-check HIBP (empreintes Pwned Passwords)
42+
43+
- **Nom de tâche** : `identities-pwned-recheck`
44+
- **Défaut** : désactivée (`enabled: false`) dans `defaults/cron/identities-pwned-recheck.yml`
45+
- **Planification par défaut** : `0 3 * * *` (tous les jours à 03:00)
46+
- **Handler** : `identities-pwned-recheck`
47+
- **Commande appelée** : `yarn run console identities pwned recheck`
48+
- **Prérequis** : policy `pwnedRecheckEnabled`, clé `SESAME_PASSWORD_HISTORY_HIBP_KEY`, historique MDP actif
49+
- **Comportement** :
50+
- re-vérifie les empreintes chiffrées de l’historique des mots de passe via l’API HIBP ;
51+
- met à jour `hibpLastCheckAt` / `hibpPwnCount` sur chaque entrée ;
52+
- peut notifier ou forcer l’expiration selon `pwnedRecheckAction` (si configuré côté policy)
53+
54+
Voir [Configuration cron](../../configuration/cron.html#tache-par-defaut-re-check-hibp-pwned-passwords) et [Politique mots de passe](password-policy.html#stockage-des-empreintes-hibp-pwnedrecheckenabled).
55+

‎docs/pages/settings/password-policy.md‎

Lines changed: 68 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -11,7 +11,8 @@ Cette page permet de configurer la **politique de mot de passe** (route `/settin
1111
## Contenu de l’interface
1212

1313
- **Paramètres numériques** : longueur minimale, entropie minimale, complexité souhaitée, TTL code reset, TTL token init.
14-
- **Toggles** : majuscule/minuscule/chiffre/spéciaux, vérification pwned, reset par SMS.
14+
- **Toggles** : majuscule/minuscule/chiffre/spéciaux, vérification HIBP (pwned), stockage des empreintes HIBP, reset par SMS.
15+
- **Re-check HIBP** : âge max avant re-check (`pwnedRecheckMaxAgeSeconds`, affiché en durée lisible).
1516
- **Attributs identité** : attribut mail alternatif, attribut mobile, URL de redirection.
1617
- **Rappels d’expiration** :
1718
- `passwordExpirationReminderSteps` : liste des jalons (par défaut vide)
@@ -35,4 +36,70 @@ Cette page permet de configurer la **politique de mot de passe** (route `/settin
3536

3637
- **Lecture** : `GET /settings/passwdadm/getpolicies`
3738
- **Sauvegarde** : `POST /settings/passwdadm/setpolicies` (avec gestion des validations)
39+
- **Statut clé HIBP** : `GET /settings/passwdadm/hibp-keystatus` (valide la présence/format de `SESAME_PASSWORD_HISTORY_HIBP_KEY`)
40+
41+
## Vérification HIBP à la saisie (`checkPwned`)
42+
43+
Le toggle **« Vérifier les mots de passe compromis »** active le contrôle en temps réel via l’API [Have I Been Pwned – Pwned Passwords](https://haveibeenpwned.com/Passwords) (k-anonymity : seuls les 5 premiers caractères du hash SHA-1 sont envoyés).
44+
45+
- Si le mot de passe apparaît dans une fuite connue, il est **refusé** à la création/changement.
46+
- Ce contrôle ne nécessite **pas** de clé `SESAME_PASSWORD_HISTORY_HIBP_KEY`.
47+
48+
## Stockage des empreintes HIBP (`pwnedRecheckEnabled`)
49+
50+
Le toggle **« Stockage des empreintes HIBP (Pwned Passwords) »** permet de conserver, dans l’**historique des mots de passe**, une empreinte chiffrée utilisable pour un **re-check planifié** (sans renvoyer le mot de passe en clair à chaque exécution du cron).
51+
52+
### Prérequis
53+
54+
1. **Historique des mots de passe activé** (`passwordHistoryEnabled=true`, défaut côté API). Sans historique, aucune entrée n’est enregistrée et aucune empreinte n’est stockée.
55+
2. **Vérification HIBP activée** (`checkPwned=true`) : le toggle empreintes est désactivé sinon.
56+
3. **Clé de chiffrement serveur** `SESAME_PASSWORD_HISTORY_HIBP_KEY` définie et valide (32 octets, en hex 64 caractères ou en base64). L’interface interroge `GET /settings/passwdadm/hibp-keystatus` et grise le toggle si la clé est absente ou invalide.
57+
4. **Tâche cron** `identities-pwned-recheck` activée pour exécuter le re-check (voir [Configuration cron](../../configuration/cron.html#tache-par-defaut-re-check-hibp-pwned-passwords)).
58+
59+
### Comment activer (résumé)
60+
61+
1. Générer une clé (ex. depuis le dépôt orchestrator) :
62+
```bash
63+
make hibp-key-hex
64+
# ou
65+
make hibp-key-b64
66+
```
67+
2. Ajouter la variable dans l’environnement de **sesame-orchestrator** (fichier `.env` ou secrets) :
68+
```env
69+
SESAME_PASSWORD_HISTORY_HIBP_KEY=<valeur_generee>
70+
```
71+
3. Redémarrer l’orchestrateur.
72+
4. Dans **Paramètres → Politique de mot de passe** :
73+
- activer **« Vérifier les mots de passe compromis »** ;
74+
- activer **« Stockage des empreintes HIBP »** ;
75+
- ajuster **« Âge max avant re-check HIBP »** si besoin (défaut : 7 jours) ;
76+
- sauvegarder.
77+
5. Dans **Paramètres → Cron**, activer la tâche `identities-pwned-recheck` (ou éditer `configs/cron/identities-pwned-recheck.yml`).
78+
79+
### Paramètres associés (policy)
80+
81+
| Champ | Rôle |
82+
| --- | --- |
83+
| `pwnedRecheckEnabled` | Active le stockage de `hibpSha1Enc` à chaque enregistrement d’historique |
84+
| `pwnedRecheckMaxAgeSeconds` | Délai minimum entre deux re-checks HIBP pour une même entrée (défaut : 604800 = 7 jours) |
85+
| `pwnedRecheckAction` | Action si compromis détecté au cron : `none`, `notify`, `expire` (l’UI force `none` à la sauvegarde actuelle) |
86+
87+
### Ce qui est stocké (sans exposer le mot de passe)
88+
89+
Pour chaque changement enregistré dans l’historique :
90+
91+
1. Hash du mot de passe (Argon2) pour l’anti-réutilisation — **jamais exposé dans l’UI**.
92+
2. Si `pwnedRecheckEnabled` : `SHA-1(mot de passe)` puis chiffrement **AES-256-GCM** → champ Mongo `hibpSha1Enc` (format `iv.tag.cipher` en base64).
93+
94+
L’API liste d’historique (`GET /management/password-history/:identityId`) ne renvoie **pas** `hibpSha1Enc` : seulement `hasHibpFingerprint`, `hibpLastCheckAt`, `hibpPwnCount`.
95+
96+
### Consultation côté identité
97+
98+
Dans la fiche identité, onglet **Historique des mots de passe** : colonne **HIBP** avec les états possibles :
99+
100+
- **Empreinte non stockée** : entrée créée avant activation ou échec de chiffrement ;
101+
- **Non vérifié** : empreinte présente, en attente du cron ;
102+
- **OK** / **Pwned (N)** : résultat du dernier re-check (`hibpPwnCount` = occurrences dans la base HIBP).
103+
104+
Voir aussi la configuration détaillée : [Configuration de la politique de mot de passe](../../configuration/config-gestion-mdp.html#verification-hibp-et-empreintes-planifiees).
38105

0 commit comments

Comments
 (0)