docs(portal): doc d'administration + guide utilisateur (#83)

- admin/k8s/auth-portal-admin.md : exploitation au quotidien — cycle de
  vie utilisateur (créer/groupe guacamole/assigner/révoquer), gestion des
  machines et des apps du hub, durcissement (MFA), table de débogage
- docs/portail-guide-utilisateur.md : guide grand public à envoyer aux
  utilisateurs (connexion, console, presse-papiers, règles, dépannage)
- renvois croisés depuis auth-portal.md et CLAUDE.md

Co-authored-by: Claude Fable 5 <noreply@anthropic.com>

admin/k8s/auth-portal-admin.md

@@ -0,0 +1,103 @@
+# Portail — administration au quotidien (Authentik + Guacamole)
+
+Guide d'exploitation du hub utilisateurs. L'architecture, le déploiement et les pièges
+sont dans **`admin/k8s/auth-portal.md`** ; le guide à envoyer aux utilisateurs est dans
+**`docs/portail-guide-utilisateur.md`**.
+
+## Les deux consoles d'admin
+
+| Console | URL | Compte |
+|---|---|---|
+| **Authentik** (identités, apps du hub) | `http://auth.lab.local` (LAN) ou `http://kaya.freeboxos.fr:9081` → icône ⚙ | `akadmin` |
+| **Guacamole** (connexions, sessions) | tuile « Portail consoles » puis *Settings* | `Alkatrazz` (SSO, « Administer system ») |
+
+> `guacadmin` (compte local) est **inaccessible** tant que le SSO est prioritaire —
+> c'est voulu. Dépannage : piège n°3 de `auth-portal.md`.
+
+## Cycle de vie d'un utilisateur
+
+### Créer (≈2 min)
+
+1. Authentik → *Directory → Users → Create* — `username` en minuscules (c'est lui qui
+   devient le compte Guacamole, casse comprise), email facultatif
+2. Sur l'utilisateur → *Set password* (mot de passe **dédié**, jamais réutilisé — le
+   portail est en HTTP)
+3. *Directory → Groups → `guacamole`* → onglet Users → **Add existing user** —
+   ⚠️ obligatoire : l'application est liée à ce groupe, sans lui → « accès refusé »
+4. L'utilisateur se connecte **une première fois** (hub → tuile) — son compte apparaît
+   alors côté Guacamole
+5. Guacamole → *Settings → Users → \<lui\>* → cocher **ses** connexions (s01 et/ou g01)
+   → Save. Ne **jamais** cocher les permissions du haut (Administer…) pour un invité.
+
+### Restreindre / auditer
+
+- **Qui est connecté** : Guacamole → *Settings → Active Sessions* — et **Kill** pour
+  couper une session en direct
+- **Historique** : *Settings → History* (qui, quelle machine, quand, durée)
+- **Événements de login** : Authentik → *Events → Logs* (échecs, IP, user agent)
+
+### Révoquer (départ, téléphone volé, doute)
+
+1. Authentik → *Directory → Users → \<lui\>* → **Deactivate** (il ne peut plus se
+   logger nulle part — c'est LE geste principal)
+2. Guacamole → *Active Sessions* → **Kill** sa session si une est ouverte
+3. (Optionnel, définitif) le retirer du groupe `guacamole`, puis supprimer les deux
+   comptes (Authentik + Guacamole)
+
+## Gérer les machines accessibles (Guacamole)
+
+Ajouter une machine = *Settings → Connections → New Connection* :
+
+| Champ | Valeur |
+|---|---|
+| Protocol | `SSH` |
+| Hostname / Port | IP de la machine / `22` |
+| Username | `console` (déployé par le rôle Ansible `console_user`) |
+| Private key | `vault_console_ssh_private_key` (`make vault-view`) |
+
+Prérequis côté machine : appliquer le rôle `console_user` (ajouter l'hôte au playbook
+si nouveau). Puis cocher la connexion aux utilisateurs concernés. Options utiles par
+connexion : SFTP (transfert de fichiers), enregistrement d'écran, limites de
+concurrence.
+
+## Ajouter une application au hub (le vrai pouvoir d'Authentik)
+
+Pour chaque nouvelle app (Grafana, n8n…) :
+
+1. *Applications → Providers → Create* — type selon l'app : **OAuth2/OpenID** (app
+   moderne), **Proxy** (app sans auth propre), SAML, LDAP
+2. *Applications → Applications → Create* — Name, **slug** (⚠️ utilisé dans les URLs
+   OIDC, piège n°4), provider, **Launch URL** (l'URL publique si accès Internet),
+   icône facultative
+3. Onglet *Policy / Group / User Bindings* → lier un groupe → seuls ses membres voient
+   la tuile
+4. Configurer l'app cliente (client ID, endpoints — cf. la page Overview du provider)
+
+La tuile apparaît automatiquement sur le hub des membres du groupe.
+
+## Durcissement (quand l'usage s'installe)
+
+- **MFA/TOTP** : chaque utilisateur peut enrôler une app d'authentification
+  (Settings utilisateur → MFA Devices). Pour l'**imposer** : Flows & Stages →
+  ajouter une stage `authenticator-validation` au flow d'authentification par défaut.
+- Rappels : rate-limit nftables 30 conn/min (rôle `gateway`), anti-bruteforce
+  Guacamole (5 échecs → ~5 min, IP Traefik = blocage global, piège n°5), lockout
+  Authentik (reputation policies).
+- Upgrade paths documentés : TLS (vrai domaine + Let's Encrypt) ou bascule VPN
+  (`admin/infra/wireguard.md`, serveur prêt et dormant).
+
+## Débogage express
+
+```bash
+kubectl -n auth get pods                                  # tout doit être 1/1
+kubectl -n auth logs deploy/guacamole --tail=50           # rejets de token, ban, DB
+kubectl -n auth logs deploy/authentik-server --tail=50    # flows, redirect_uri, 400
+```
+
+| Symptôme | Cause probable |
+|---|---|
+| « Redirect URI Error » (page Authentik) | Redirect URI du provider ≠ `http://kaya.freeboxos.fr:9080/` au caractère près |
+| Login SSO accepté puis retour à la page de login Guacamole | Signing Key absente du provider, ou slug ≠ `guacamole` (JWKS 404 dans les logs) |
+| Tout le monde bloqué au login | Anti-bruteforce (piège n°5) — attendre ~5 min ou redémarrer le pod guacamole |
+| Tuile absente pour un utilisateur | Pas membre du groupe `guacamole` |
+| Console noire / connexion SSH refusée | Machine éteinte, ou clé `console` révoquée (rôle `console_user`) |

admin/k8s/auth-portal.md

@@ -4,6 +4,11 @@ Annuaire d'identités **Authentik** (IdP OIDC/LDAP) et portail **Guacamole** don
 accès aux consoles SSH de storage-01 et gpu-01 **dans le navigateur**, avec un compte
 unique par utilisateur. Namespace k8s : **`auth`**.
 
+> Ce document = architecture, déploiement, pièges. Voir aussi :
+> **`admin/k8s/auth-portal-admin.md`** (administration au quotidien : utilisateurs,
+> machines, apps du hub, révocation) et **`docs/portail-guide-utilisateur.md`**
+> (guide à envoyer aux utilisateurs).
+
 ## Vue d'ensemble
 
 ```