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>

CLAUDE.md

@@ -21,7 +21,7 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
 - ✅ SearXNG opérationnel — `searxng.lab.local`, namespace `ai`, **méta-moteur de recherche web self-host** (privé, in-cluster) consommé par l'outil `web_search` d'Asa (API JSON). Manifests `k8s/apps/searxng/`
 - ✅ Ghostfolio opérationnel — `ghostfolio.lab.local`, namespace `ai`, suivi de portefeuille (PostgreSQL s01 + Redis in-cluster)
 - ✅ hermes-auto-improve — analyse quotidienne de `admin/` par Hermes à 22h (n8n → trigger :9095), PR sur `hermes/daily-work`
-- 🆕 Annuaire + portail consoles (2026-07-06) — **Authentik** (`auth.lab.local`, IdP OIDC) + **Guacamole** (`portail.lab.local`, consoles SSH web vers s01/g01 via user `console` sans sudo), namespace `auth`. Config initiale (admin Authentik, provider OIDC, connexions) : voir `admin/k8s/auth-portal.md`. **Accès Internet** : Authentik = hub utilisateur (`kaya.freeboxos.fr:9081`, page « My applications ») → SSO vers Guacamole (`:9080`) — VIPs MetalLB `.201`/`.202`, rate-limit nftables, URL canonique publique pour tous (hairpin LAN)
+- 🆕 Annuaire + portail consoles (2026-07-06) — **Authentik** (`auth.lab.local`, IdP OIDC) + **Guacamole** (`portail.lab.local`, consoles SSH web vers s01/g01 via user `console` sans sudo), namespace `auth`. Config initiale (admin Authentik, provider OIDC, connexions) : voir `admin/k8s/auth-portal.md`. **Accès Internet** : Authentik = hub utilisateur (`kaya.freeboxos.fr:9081`, page « My applications ») → SSO vers Guacamole (`:9080`) — VIPs MetalLB `.201`/`.202`, rate-limit nftables, URL canonique publique pour tous (hairpin LAN). Admin quotidienne : `admin/k8s/auth-portal-admin.md` ; guide utilisateur : `docs/portail-guide-utilisateur.md`
 - 🆕 WireGuard (2026-07-06) — serveur VPN prêt sur s01 (pairs `full`/`portal`, filtrage nftables) mais **dormant** : pas de redirection Freebox `51820/udp` (choix simplicité 2026-07-07, accès portail via `:9080` direct). Voir `admin/infra/wireguard.md`
 - ⏳ WOL compute nodes non configuré (BIOS) — allumage manuel requis
 

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

docs/portail-guide-utilisateur.md

@@ -0,0 +1,59 @@
+# 🖥️ Accéder aux machines du lab Funk — guide utilisateur
+
+Bienvenue ! Ce guide t'explique comment ouvrir un **terminal sur les serveurs du lab,
+directement dans ton navigateur**. Rien à installer.
+
+## Ce qu'il te faut
+
+- Un navigateur (PC, Mac, tablette… ça marche partout)
+- Ton **compte** : un nom d'utilisateur + mot de passe fournis par Ali
+- L'adresse du portail : **http://kaya.freeboxos.fr:9081**
+
+## Se connecter (30 secondes)
+
+1. Ouvre **http://kaya.freeboxos.fr:9081**
+2. Entre ton nom d'utilisateur puis ton mot de passe
+3. Tu arrives sur **ta page d'applications** : chaque vignette est un service auquel
+   tu as accès
+4. Clique sur **« Portail consoles »** → tu es connecté automatiquement (pas de
+   deuxième mot de passe)
+5. Clique sur une machine (ex. *Console s01* ou *Console g01*) → **un terminal
+   s'ouvre dans l'onglet** — tu es dessus, tu peux taper des commandes
+
+> 💡 À ta **toute première** connexion, il est possible que tu voies « aucune
+> machine » : c'est normal, Ali doit t'attribuer les accès après ton premier login.
+> Préviens-le, puis reconnecte-toi.
+
+## Utiliser la console
+
+- C'est un **vrai terminal Linux** : `ls`, `htop`, `df -h`, `exit`… tape comme si tu
+  y étais
+- **Le menu magique : `Ctrl + Alt + Shift`** — ouvre un panneau latéral avec :
+  - le **presse-papiers** : colle du texte dedans → clic droit/collage dans le
+    terminal ; et inversement pour copier vers ton PC
+  - les réglages d'affichage (zoom, clavier)
+  - le bouton **Déconnexion**
+- Pour quitter : referme l'onglet, ou `Ctrl+Alt+Shift` → Disconnect. (Ta session se
+  ferme aussi toute seule après un moment d'inactivité.)
+- Retour à la liste des machines : bouton « Home » du menu, ou ré-ouvre le portail
+
+## Les règles du jeu 🤝
+
+- Ton compte est **personnel** — ne le prête pas, ne partage pas ton mot de passe
+- Tu es connecté avec un utilisateur **sans droits d'administration** : tu peux
+  observer et utiliser, pas casser — c'est fait exprès 😉
+- Les connexions sont **journalisées** (qui, quand, sur quelle machine)
+- Un doute, une commande qui te dépasse ? Demande avant de taper
+
+## En cas de pépin
+
+| Problème | Solution |
+|---|---|
+| La page ne charge pas | Vérifie l'adresse exacte (avec le `:9081`) et ta connexion |
+| Mot de passe refusé | Attention aux majuscules ; sinon demande une réinitialisation à Ali |
+| « Trop de tentatives » | Patiente 5 minutes, puis réessaie calmement |
+| La vignette « Portail consoles » n'apparaît pas | Ton compte n'est pas encore activé pour le portail — préviens Ali |
+| Terminal noir ou « connexion refusée » | La machine est peut-être éteinte — préviens Ali |
+| Le copier/coller ne marche pas | Passe par le presse-papiers du menu `Ctrl+Alt+Shift` |
+
+Bonne exploration 🚀