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