From 0957db28321c1dbac2df493428b844f170420669 Mon Sep 17 00:00:00 2001 From: alkatrazz Date: Tue, 7 Jul 2026 11:34:52 +0200 Subject: [PATCH] docs(portal): doc d'administration + guide utilisateur MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 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 --- CLAUDE.md | 2 +- admin/k8s/auth-portal-admin.md | 103 ++++++++++++++++++++++++++++++ admin/k8s/auth-portal.md | 5 ++ docs/portail-guide-utilisateur.md | 59 +++++++++++++++++ 4 files changed, 168 insertions(+), 1 deletion(-) create mode 100644 admin/k8s/auth-portal-admin.md create mode 100644 docs/portail-guide-utilisateur.md diff --git a/CLAUDE.md b/CLAUDE.md index c0e58ac..3d63954 100644 --- a/CLAUDE.md +++ b/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 diff --git a/admin/k8s/auth-portal-admin.md b/admin/k8s/auth-portal-admin.md new file mode 100644 index 0000000..53998f5 --- /dev/null +++ b/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 → \* → 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 → \* → **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`) | diff --git a/admin/k8s/auth-portal.md b/admin/k8s/auth-portal.md index 379ec38..a60301d 100644 --- a/admin/k8s/auth-portal.md +++ b/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 ``` diff --git a/docs/portail-guide-utilisateur.md b/docs/portail-guide-utilisateur.md new file mode 100644 index 0000000..5b0977e --- /dev/null +++ b/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 🚀