Référence de configuration

Les principales variables d'environnement de l'auth-service, famille par famille : base de données, chiffrement, sessions, e-mail, politiques de connexion, stockage et observabilité.

L'auth-service suit le modèle 12-factor : toute la configuration provient de variables d'environnement, chargées et validées au démarrage. Cette page liste les variables principales par famille, avec leurs défauts exacts.

Comment la configuration est chargée

Une valeur requise absente ou invalide arrête le service au démarrage avec une erreur explicite, jamais un repli silencieux. Les durées utilisent la syntaxe Go (30m, 24h, 720h) ; les booléens acceptent true et false. Deux garde-fous de production s'appliquent : avec APP_ENV=production, SESSION_SECURE doit valoir true et MAIL_TRANSPORT=log est refusé. SESSION_SECURE=true est aussi exigé dès que OIDC_ISSUER est en HTTPS.

Service de base

Variable	Rôle	Défaut
`APP_ENV`	`development` ou `production` ; la production active des garde-fous stricts	`development`
`HTTP_ADDR`	Adresse d'écoute de l'API	`:8080`
`LOG_LEVEL`	Niveau des logs structurés JSON	`info`
`OIDC_ISSUER`	URL publique de l'API : le claim `iss` et la base des URLs de découverte	`http://localhost:8080`
`LOGIN_UI_URL`	URL publique de l'interface de connexion (les liens magiques pointent dessus)	`http://localhost:3000`
`ALLOWED_DATA_REGIONS`	Régions de résidence des données autorisées pour les tenants (CSV)	`eu`

Base de données et Redis

Variable	Rôle	Défaut
`DATABASE_URL`	Chaîne de connexion PostgreSQL ; porte tout l'état durable	requise
`REDIS_URL`	Chaîne de connexion Redis ; sessions et rate limiting, volatile	requise

Sur des services managés, utilisez sslmode=verify-full pour PostgreSQL et rediss:// pour Redis : TLS de bout en bout.

Chiffrement au repos

Variable	Rôle	Défaut
`ENCRYPTION_KEY`	Clé primaire AES-256-GCM : chiffre les secrets TOTP et les clés privées de signature OIDC stockées en base (base64, exactement 32 octets)	requise
`ENCRYPTION_KEY_OLD`	Clés précédentes (CSV), conservées en déchiffrement seul pendant une rotation de clé	vide

Générer une clé :

openssl rand -base64 32

Danger

Conservez ENCRYPTION_KEY dans un coffre à secrets, séparément des sauvegardes de base. Un dump restauré est illisible sans la clé qui a chiffré ses secrets.

Sessions, cookies et proxys

Variable	Rôle	Défaut
`SESSION_TTL`	Durée de vie des sessions	`24h`
`SESSION_SECURE`	Marque les cookies `Secure` ; obligatoire en production	`false`
`SESSION_COOKIE_NAME`	Nom du cookie de session	`obexal_session`
`SESSION_COOKIE_DOMAIN`	Domaine du cookie, si partagé entre sous-domaines	vide
`COOKIE_SAMESITE`	`lax`, `strict` ou `none`	`lax`
`CSRF_COOKIE_NAME`	Nom du cookie CSRF	`obexal_csrf`
`ALLOWED_ORIGINS`	Origines CORS autorisées à appeler l'API (CSV)	vide
`TRUSTED_PROXIES`	Plages CIDR des reverse proxys dont le `X-Forwarded-For` est honoré	vide

Attention

Laissez TRUSTED_PROXIES vide et le service ne fait confiance qu'à l'adresse TCP de la connexion : derrière un proxy, tous les clients s'effondrent sur l'IP du proxy et le rate limiting par IP cesse de fonctionner.

Durées de vie des jetons

Variable	Rôle	Défaut
`OAUTH_ACCESS_TOKEN_TTL`	Durée de vie de l'access token	`10m`
`OAUTH_ID_TOKEN_TTL`	Durée de vie de l'ID token	`10m`
`OAUTH_REFRESH_TOKEN_TTL`	Durée de vie du refresh token	`720h`
`OAUTH_AUTH_CODE_TTL`	Durée de vie du code d'autorisation	`1m`

Ces durées bornent aussi la période de grâce d'une rotation de clé de signature.

Envoi d'e-mails

Variable	Rôle	Défaut
`MAIL_TRANSPORT`	`smtp` ou `log` (débogage : écrit les e-mails dans les logs, refusé en production)	`log`
`SMTP_HOST`	Hôte du relais SMTP (choisissez un relais UE)	vide
`SMTP_PORT`	Port SMTP	`587`
`SMTP_USERNAME`	Utilisateur SMTP	vide
`SMTP_PASSWORD`	Mot de passe SMTP	vide
`MAIL_FROM`	Adresse d'expéditeur	`no-reply@obexal.local`

Politiques de connexion et de compte

Variable	Rôle	Défaut
`REQUIRE_EMAIL_VERIFICATION`	Bloque la connexion par mot de passe des adresses non vérifiées	`false`
`EMAIL_OTP`	Exige un code e-mail comme second facteur à la connexion par mot de passe quand l'utilisateur n'a pas de TOTP	`true`
`MFA_ENROLLMENT_STRICT`	Quand un tenant exige la MFA, rejette les requêtes authentifiées (403) tant qu'aucun facteur n'est enrôlé	`false`
`ORG_SIGNUP_ENABLED`	Autorise la création d'organisation en self-service	`true`
`ACCOUNT_SELF_DELETE_ENABLED`	Permet à l'utilisateur final de supprimer lui-même son compte (tenants grand public seulement)	`false`
`ACCOUNT_SELF_EMAIL_CHANGE_ENABLED`	Permet à l'utilisateur final de changer lui-même son adresse e-mail (tenants grand public seulement)	`false`

Rate limiting et verrouillage

Variable	Rôle	Défaut
`RATE_LIMIT_LOGIN_MAX`	Tentatives de connexion par compte et par fenêtre	`10`
`RATE_LIMIT_LOGIN_WINDOW`	Fenêtre du rate limit de connexion	`15m`
`RATE_LIMIT_LOGIN_IP_MAX`	Tentatives de connexion par IP et par fenêtre	`100`
`RATE_LIMIT_SIGNUP_MAX`	Inscriptions par identifiant et par fenêtre	`5`
`RATE_LIMIT_SIGNUP_WINDOW`	Fenêtre du rate limit d'inscription	`1h`
`RATE_LIMIT_SIGNUP_IP_MAX`	Inscriptions par IP et par fenêtre	`50`
`LOGIN_LOCKOUT_MAX`	Échecs avant verrouillage d'un compte (0 ou moins désactive)	`10`
`LOGIN_LOCKOUT_WINDOW`	Fenêtre de comptage des échecs	`15m`
`LOGIN_LOCKOUT_DURATION`	Durée du verrou	`15m`

Fichiers de données locaux

Deux fonctions optionnelles lisent des fichiers locaux, sans appel réseau et sans qu'aucune donnée ne quitte votre périmètre :

Variable	Rôle	Défaut
`GEOIP_DB_PATH`	Chemin d'une base GeoIP `.mmdb` pour les règles par pays de l'accès conditionnel	vide
`BREACHED_PASSWORD_FILE`	Chemin d'un corpus de mots de passe compromis, format HIBP `SHA1:count` ou texte brut	vide

Les deux sont fail-open : si le fichier est absent ou illisible, la fonction reste inerte et rien n'est bloqué. Rafraîchissez périodiquement le fichier GeoIP (il est chargé au démarrage).

Stockage objet (logos de tenant)

Variable	Rôle	Défaut
`S3_ENDPOINT`	Endpoint compatible S3, `hôte:port` sans schéma	vide
`S3_ACCESS_KEY`	Clé d'accès	vide
`S3_SECRET_KEY`	Clé secrète	vide
`S3_BUCKET`	Bucket des éléments de marque des tenants	`obexal-branding`
`S3_USE_SSL`	TLS vers l'endpoint	`false`
`S3_REGION`	Étiquette de région du protocole S3	`us-east-1`

L'upload de logo est proprement désactivé tant que l'endpoint, la clé d'accès et la clé secrète ne sont pas tous les trois renseignés. L'étiquette de région par défaut n'est qu'une convention du protocole S3 utilisée par MinIO : aucun service américain n'est impliqué.

Webhooks et audit

Variable	Rôle	Défaut
`WEBHOOK_WORKERS`	Taille du pool de livraison	`4`
`WEBHOOK_QUEUE_SIZE`	Capacité de la file de livraison	`256`
`WEBHOOK_TIMEOUT`	Timeout de chaque tentative de livraison	`10s`
`WEBHOOK_ALLOW_PRIVATE_TARGETS`	Autorise des URLs de webhook vers des adresses privées ou de bouclage	`false`
`AUDIT_RETENTION`	Rétention du journal d'audit ; `0` désactive la purge	`0`

Danger

WEBHOOK_ALLOW_PRIVATE_TARGETS=true est réservé au développement. En production, il ouvre la porte au SSRF : un admin de tenant pourrait viser votre réseau interne. Laissez false.

Agents IA

Variable	Rôle	Défaut
`AGENT_AUTO_CONTAINMENT_ENABLED`	Confine automatiquement un agent IA dont l'activité explose très au-delà de sa baseline (applique le kill switch)	`true`

Observabilité

Variable	Rôle	Défaut
`METRICS_ENABLED`	Expose `GET /metrics` au format Prometheus	`true`
`METRICS_TOKEN`	Si définie, exige `Authorization: Bearer` sur `/metrics`	vide
`HTTP_REQUEST_TIMEOUT`	Timeout de traitement par requête (503 au-delà) ; `0` désactive	`15s`

Variables consommées par d'autres composants

Celles-ci ne sont pas lues par l'auth-service :

OBEXAL_CONNECT_SRC : la directive CSP connect-src des interfaces de connexion et d'administration. Resserrez-la sur l'origine exacte de l'API en production.
NEXT_PUBLIC_OBEXAL_API_URL, NEXT_PUBLIC_LOGIN_UI_URL, NEXT_PUBLIC_ADMIN_URL, NEXT_PUBLIC_ALLOWED_REDIRECTS : arguments de build intégrés aux images des interfaces.
OBEXAL_ACME_EMAIL, OBEXAL_API_HOST, OBEXAL_ADMIN_HOST, OBEXAL_LOGIN_HOST : consommées par l'overlay TLS Caddy (voir Déployer avec Docker Compose).