ultisuite-backend/deploy/authentik/README.md

# Authentik — provisioning local

Blueprints in `blueprints/` are mounted into Authentik at `/blueprints/custom` and applied automatically by the worker on startup.

| Fichier | Rôle |
|---------|------|
| `01-ulti-enrollment.yaml` | Inscription self-service (`ulti-enrollment`, @ultisuite.fr) |
| `02-ulti-brand.yaml` | Branding UltiSuite + lien « Créer un compte » sur login |
| `03-ulti-suite-groups.yaml` | Claim OIDC `groups` (RBAC contacts/calendar/drive/photos) |
| `04-ulti-post-migration-security.yaml` | Flow WebAuthn/TOTP post-migration (`ulti-post-migration-security`) |
| `05-ulti-recovery.yaml` | Mot de passe oublié (`ulti-recovery`) + e-mail → `/reset-password` |
| `ulti-oidc.yaml` | App OIDC Ultimail |
| `nextcloud-oidc.yaml` | App OIDC Nextcloud |
| `onlyoffice-oidc.yaml` | App OIDC OnlyOffice |

Assets branding : générés depuis le frontend (`pnpm run brand:authentik` dans `gmail-interface-clone`, source : `public/ultisuite-mark.svg`) :

| Fichier Authentik | Thème | Description |
|-------------------|-------|-------------|
| `ultisuite-logo-light.png` | clair | Mark + wordmark UltiSuite, texte sombre, fond transparent |
| `ultisuite-logo-dark.png` | sombre | Mark + texte clair, fond transparent |
| `ultisuite-favicon.png` | — | Mark 32×32 transparent (favicon onglet, URL **sans** `%(theme)s`) |
| `ultisuite-favicon-light.png` | clair | Variante archive (fond blanc) |
| `ultisuite-favicon-dark.png` | sombre | Variante archive (fond sombre) |

Logo : placeholder Authentik `%(theme)s` + fallback CSS `prefers-color-scheme`.  
Favicon onglet : **chemin statique** — Authentik ne substitue pas `%(theme)s` dans le `<link rel="icon">` SSR (erreur 400).

Regénérer après MAJ du master brand :

```bash
cd ../gmail-interface-clone
pnpm run brand:authentik
cd ../ulti-backend
./deploy/compose-up.sh up -d authentik-server authentik-worker
docker exec deploy-authentik-server-1 ak apply_blueprint /blueprints/custom/02-ulti-brand.yaml
```

### Mot de passe oublié (recovery embedded)

1. L'utilisateur saisit son e-mail sur `/forgot-password` (UI Ulti).
2. Authentik envoie un e-mail avec lien vers `{AUTH_APP_URL}/reset-password?flow_token=…` (template `email/ulti_password_reset.html`).
3. `/reset-password` reprend le flow `ulti-recovery` via le BFF (`is_restored` → étapes mot de passe embedded).

Variable `.env` : `AUTH_APP_URL` (défaut dev `http://localhost:3004`). Régénérée dans le template e-mail par `./deploy/authentik/render-blueprints.sh`.

Appliquer après changement recovery :

```bash
./deploy/authentik/render-blueprints.sh   # depuis ulti-backend avec .env.resolved sourcé
docker exec deploy-authentik-server-1 ak apply_blueprint /blueprints/custom/05-ulti-recovery.yaml
./deploy/compose-up.sh restart authentik-worker
```

## Inscription utilisateur

Flow public : `http://localhost/auth/if/flow/ulti-enrollment/`

Étapes collectées :

1. E-mail (identifiant), mot de passe
2. Nom et prénom, téléphone (optionnel), avatar (optionnel)
3. Création du compte + connexion automatique

L'email d'inscription est construit comme `username@ultisuite.fr`. ultid peut provisionner la boîte Stalwart via `POST /internal/provision/user` (header `X-Provision-Secret: $PROVISION_WEBHOOK_SECRET`).

Flow post-migration (WebAuthn/TOTP) : `/auth/if/flow/ulti-post-migration-security/`

Sur la page de connexion Authentik, lien **« Besoin d'un compte ? S'inscrire »** (identification stage).

## Branding

- Titre navigateur : **UltiSuite**
- Logo / favicon : marque UltiSuite (grille 4 couleurs plates), variantes **light** et **dark** (thème Authentik)
- CSS custom : masque « Powered by authentik » et liens goauthentik.io
- Locale par défaut : `fr`

Modifier le logo : `pnpm run brand:authentik` dans le repo frontend, puis redémarrer Authentik + réappliquer le blueprint brand.

## Secrets OIDC

| App | Slug | Client ID | Secret (`.env`) |
|-----|------|-----------|------------------|
| Ultimail | `ulti` | `ulti-backend` | `ULTID_OIDC_CLIENT_SECRET` |
| Nextcloud | `nextcloud` | `ulti-nextcloud` | `NC_OIDC_CLIENT_SECRET` |
| OnlyOffice | `onlyoffice` | `ulti-onlyoffice` | `ONLYOFFICE_OIDC_CLIENT_SECRET` |
| Immich | `immich` | `ulti-immich` | `IMMICH_OIDC_CLIENT_SECRET` |

Defaults blueprints : `changeme` — sync avec `.env`.

## Provisioning automatique (ultid)

Si `AUTHENTIK_API_TOKEN` est défini, **ultid** provisionne au démarrage les applications OIDC des briques activées (`NEXTCLOUD_ENABLED`, `ONLYOFFICE_ENABLED`, `IMMICH_ENABLED`, etc.) via l’API Authentik, puis enregistre l’état dans Postgres (`suite_authentik_provisioned`) pour ne pas recréer à chaque restart.

1. Authentik Admin → **Directory** → **Tokens** → créer un token API (intent: `api`)
2. `.env` : `AUTHENTIK_API_TOKEN=<token>`
3. Redémarrer `ultid`

Sans token : les blueprints ci-dessus restent la source (worker Authentik au boot).

Les blueprints OIDC (`*-oidc.yaml`) sont **générés** depuis `*.yaml.template` au lancement de `./deploy/compose-up.sh`, avec les redirect URIs dérivés de `SUITE_ORIGIN` (`PUBLIC_HOST` + `SECURE`). Éditer les `.template`, pas les `.yaml` générés.

## Appliquer / vérifier

```bash
# Re-render + re-appliquer après changement de domaine
./deploy/compose-up.sh restart authentik-worker

# Ou manuellement :
./deploy/authentik/render-blueprints.sh   # source .env.resolved d'abord
docker exec deploy-authentik-server-1 ak apply_blueprint /blueprints/custom/ulti-oidc.yaml
./deploy/compose-up.sh restart authentik-worker

# Vérifier OIDC Ultimail
curl -s http://localhost/auth/application/o/ulti/.well-known/openid-configuration | head -5
```

`redirect_uris` : objets `{ matching_mode, url }` (Authentik 2025.2+).

## Limites connues

- « Powered by authentik » masqué via CSS (pas d’option officielle en open source).
- Placeholder `%(theme)s` sur le **logo** : non remplacé sur certaines pages SSR ; fallback CSS `prefers-color-scheme`.
- Favicon onglet : pas de `%(theme)s` (bug SSR Authentik → 400) ; mark transparent unique.
- Avatar stocké en attribut utilisateur (data-URI), pas encore affiché dans Ultimail header.
- Multi-comptes simultanés type Gmail : non implémenté côté Ultimail.