Gabriel Radureau
515b407db4
All checks were successful
Docker Build / build-and-push-image (push) Successful in 56s
Mirror of factory#8 path correction. Updates Gitea URLs in AUTH.md / HOWTO_ADD_BOT.md and the '// Voir factory/...' header comments in code.
107 lines
4.7 KiB
Markdown
107 lines
4.7 KiB
Markdown
[← README](README.md) · [HOWTO_ADD_BOT](HOWTO_ADD_BOT.md) · **Authentification**
|
|
|
|
> **Détails de design** : [factory ADR 20260509 — telegram-gateway auth](https://gitea.arcodange.lab/arcodange-org/factory/src/branch/main/doc/adr/20260509-telegram-gateway-auth.md)
|
|
|
|
# Authentification
|
|
|
|
Le gateway est protégé en deux couches :
|
|
|
|
1. **Allowlist** (`ALLOWED_USERS`, optionnelle) — filtre la liste des Telegram user IDs autorisés à parler à n'importe quel bot. Hors-liste : silent drop, le bot ne répond rien (l'inconnu ne sait même pas que le bot existe).
|
|
2. **Session `/auth`** — par défaut, **tous les bots du gateway exigent une session active** (`requireAuth: true` par défaut). Pour ouvrir une session, il faut DM `@arcodange_factory_bot` avec `/auth <code>`. Une session dure **24 h** (configurable via `AUTH_SESSION_TTL`).
|
|
|
|
## Côté utilisateur
|
|
|
|
### 1. Ouvrir une session
|
|
|
|
1. Sur Telegram, ouvre `@arcodange_factory_bot`.
|
|
2. Envoie `/auth <code>` (le code t'a été partagé par l'admin du gateway).
|
|
3. Le bot répond `✅ Authentifié pour 24 h`. Ton message contenant le code est **automatiquement supprimé** du chat (replay defense).
|
|
4. Tu peux maintenant DM les autres bots normalement.
|
|
|
|
### 2. Vérifier sa session
|
|
|
|
```
|
|
/whoami
|
|
```
|
|
|
|
Réponse type : `user=123456 : ✅ authentifié, reste 23h59m.` ou `user=123456 : non authentifié.`.
|
|
|
|
### 3. Fermer une session
|
|
|
|
```
|
|
/logout
|
|
```
|
|
|
|
### 4. Quand un bot répond `🔒 Authentifie-toi …`
|
|
|
|
Ta session a expiré (TTL dépassé) ou tu n'as jamais fait `/auth`. Va sur `@arcodange_factory_bot`, refais `/auth <code>`.
|
|
|
|
## Côté opérateur
|
|
|
|
### Définir / changer le code `AUTH_SECRET`
|
|
|
|
```bash
|
|
# Choisir un code fort (ex : openssl rand -hex 16)
|
|
SECRET='<chosen-code>'
|
|
|
|
kubectl -n telegram-gateway patch secret telegram-gateway-bots --type=json -p="[
|
|
{\"op\":\"replace\",\"path\":\"/data/AUTH_SECRET\",\"value\":\"$(echo -n "$SECRET" | base64)\"}
|
|
]"
|
|
|
|
# Restart pour reload du Secret
|
|
kubectl -n telegram-gateway rollout restart deploy/telegram-gateway
|
|
```
|
|
|
|
> Rotation : changer `AUTH_SECRET` invalide les **futurs** `/auth` mais **pas** les sessions Redis déjà ouvertes (elles vivent jusqu'à leur TTL). Pour invalider tout : `kubectl exec -n tools redis-0 -- redis-cli --scan --pattern 'tg-gw:auth:*' | xargs -I{} kubectl exec -n tools redis-0 -- redis-cli DEL {}`.
|
|
|
|
### Définir / changer l'allowlist
|
|
|
|
```bash
|
|
kubectl -n telegram-gateway patch secret telegram-gateway-bots --type=json -p="[
|
|
{\"op\":\"replace\",\"path\":\"/data/ALLOWED_USERS\",\"value\":\"$(echo -n '12345,67890' | base64)\"}
|
|
]"
|
|
kubectl -n telegram-gateway rollout restart deploy/telegram-gateway
|
|
```
|
|
|
|
Pour **désactiver** l'allowlist (ouvrir à tout Telegram user en allowlist) :
|
|
|
|
```bash
|
|
kubectl -n telegram-gateway patch secret telegram-gateway-bots --type=json -p='[
|
|
{"op":"remove","path":"/data/ALLOWED_USERS"}
|
|
]'
|
|
kubectl -n telegram-gateway rollout restart deploy/telegram-gateway
|
|
```
|
|
|
|
### Inspecter une session Redis
|
|
|
|
```bash
|
|
USER_ID=123456
|
|
kubectl exec -n tools redis-0 -- redis-cli GET "tg-gw:auth:$USER_ID" # → "1" ou (nil)
|
|
kubectl exec -n tools redis-0 -- redis-cli TTL "tg-gw:auth:$USER_ID" # → secondes restantes
|
|
kubectl exec -n tools redis-0 -- redis-cli DEL "tg-gw:auth:$USER_ID" # → forcer logout
|
|
```
|
|
|
|
### Rendre un bot public (opt-out de l'auth)
|
|
|
|
Dans `chart/values.yaml`, ajouter `requireAuth: false` au bot concerné :
|
|
|
|
```yaml
|
|
bots:
|
|
statusbot:
|
|
handler: echo
|
|
requireAuth: false # bot public, pas de session requise
|
|
```
|
|
|
|
> Cas spécial : `handler: auth` (le bot principal `factory`) force toujours `requireAuth: false` automatiquement (sinon l'auth elle-même serait inaccessible — chicken-and-egg).
|
|
|
|
## Limites connues
|
|
|
|
- **Pas de TOTP / OTP rotatif** — un code partagé suffit pour cet usage privé. À reconsidérer si on ouvre à plus d'utilisateurs.
|
|
- **Pas de rate-limit sur `/auth`** — l'`ALLOWED_USERS` joue le rôle de garde-fou. Avec un code fort (≥ 128 bits), le bruteforce est inutile dans la fenêtre de TTL.
|
|
- **Sessions invalidées si Redis tombe** — fail-closed : tous les bots gated répondent `🔒` jusqu'à ce que Redis revienne. Acceptable.
|
|
- **`from.id`-based, pas IP-based** — Telegram n'expose pas l'IP du user au bot. Une session couvre tous les devices d'un même compte Telegram, ce qui est le comportement attendu.
|
|
|
|
## Chemin de migration vers Vault (Phase 2+)
|
|
|
|
Aujourd'hui, `AUTH_SECRET` et `ALLOWED_USERS` vivent dans un `Secret` k8s créé via `kubectl create secret`. À terme, ils basculeront dans Vault (toggle `vault.enabled: true` dans `chart/values.yaml`, provisionner `kvv2/telegram-gateway/config`). Le code n'a pas à changer — `envFrom: secretRef` consomme indifféremment un Secret manuel ou un Secret produit par VaultStaticSecret.
|