From 59f5ec798ed1e0318addb66fe8753364ef2e6643 Mon Sep 17 00:00:00 2001 From: Priveetee Date: Wed, 5 Aug 2026 11:09:35 +0200 Subject: [PATCH] docs: document account session configuration --- docs/.vitepress/config.mts | 10 ++++++ docs/es/self-hosting/authentication.md | 46 ++++++++++++++++++++++++++ docs/fr/self-hosting/authentication.md | 46 ++++++++++++++++++++++++++ docs/self-hosting/authentication.md | 30 +++++++++++++++-- docs/self-hosting/configuration.md | 21 ++++++++++++ docs/self-hosting/troubleshooting.md | 20 +++++++---- 6 files changed, 164 insertions(+), 9 deletions(-) create mode 100644 docs/es/self-hosting/authentication.md create mode 100644 docs/fr/self-hosting/authentication.md diff --git a/docs/.vitepress/config.mts b/docs/.vitepress/config.mts index 753a97b..d84d2f5 100644 --- a/docs/.vitepress/config.mts +++ b/docs/.vitepress/config.mts @@ -23,6 +23,7 @@ export default defineConfig({ nav: [ { text: "Accueil", link: "/fr/" }, { text: "Prérequis", link: "/fr/self-hosting/prerequisites" }, + { text: "Sessions", link: "/fr/self-hosting/authentication" }, { text: "Guide en anglais", link: "/" }, { text: "Code source", link: "https://github.com/TypeType-Video/TypeType" }, ], @@ -35,6 +36,10 @@ export default defineConfig({ text: "Prérequis et ressources", link: "/fr/self-hosting/prerequisites", }, + { + text: "Sessions de compte", + link: "/fr/self-hosting/authentication", + }, ], }, ], @@ -81,6 +86,7 @@ export default defineConfig({ nav: [ { text: "Inicio", link: "/es/" }, { text: "Requisitos", link: "/es/self-hosting/prerequisites" }, + { text: "Sesiones", link: "/es/self-hosting/authentication" }, { text: "Guía en inglés", link: "/" }, { text: "Código fuente", link: "https://github.com/TypeType-Video/TypeType" }, ], @@ -93,6 +99,10 @@ export default defineConfig({ text: "Requisitos y recursos", link: "/es/self-hosting/prerequisites", }, + { + text: "Sesiones de cuenta", + link: "/es/self-hosting/authentication", + }, ], }, ], diff --git a/docs/es/self-hosting/authentication.md b/docs/es/self-hosting/authentication.md new file mode 100644 index 0000000..3e282a5 --- /dev/null +++ b/docs/es/self-hosting/authentication.md @@ -0,0 +1,46 @@ +# Sesiones de cuenta + +Después de iniciar sesión de forma local o mediante OIDC, el token de acceso de +TypeType dura una hora. Una sesión de actualización renueva automáticamente ese +token sin pedir otro inicio de sesión. + +## Duración de la sesión + +La sesión de actualización dura 30 días de forma predeterminada. Puedes elegir una +duración de 1 a 365 días en `.env`: + +```dotenv +AUTH_SESSION_TTL_DAYS=90 +``` + +La nueva duración se aplica a las sesiones creadas o renovadas después del cambio. +Vuelve a crear Server para aplicar la configuración: + +```sh +docker compose up -d --force-recreate typetype-server +``` + +## HTTPS y redes locales + +De forma predeterminada, la cookie de actualización es `HttpOnly`, `Secure` y +`SameSite=None`. Usa HTTPS para cualquier instancia pública. + +En una red local de confianza que no pueda usar HTTPS, una opción de compatibilidad +permite que la cookie funcione mediante HTTP con `SameSite=Lax`: + +```dotenv +AUTH_ALLOW_INSECURE_COOKIES=true +``` + +::: danger +No actives esta opción en Internet ni en una red que no sea de confianza. La cookie +podría viajar por una conexión HTTP sin cifrar. +::: + +Un cierre de sesión exactamente después de una hora suele indicar que la cookie de +actualización no fue enviada o aceptada. Comprueba también que `ALLOWED_ORIGINS` +contenga exactamente el origen del navegador. + +La guía completa en inglés explica la +[autenticación](/self-hosting/authentication) y la +[resolución de cierres de sesión](/self-hosting/troubleshooting#unexpected-sign-outs). diff --git a/docs/fr/self-hosting/authentication.md b/docs/fr/self-hosting/authentication.md new file mode 100644 index 0000000..5f93dc1 --- /dev/null +++ b/docs/fr/self-hosting/authentication.md @@ -0,0 +1,46 @@ +# Sessions de compte + +Après une connexion locale ou OIDC, le jeton d'accès TypeType est valable pendant +une heure. Une session de rafraîchissement renouvelle automatiquement ce jeton, sans +demander une nouvelle connexion. + +## Durée de la session + +La session de rafraîchissement dure 30 jours par défaut. Vous pouvez choisir une +durée de 1 à 365 jours dans `.env` : + +```dotenv +AUTH_SESSION_TTL_DAYS=90 +``` + +La nouvelle durée s'applique aux sessions créées ou renouvelées après le changement. +Recréez Server pour appliquer la configuration : + +```sh +docker compose up -d --force-recreate typetype-server +``` + +## HTTPS et réseaux locaux + +Par défaut, le cookie de rafraîchissement est `HttpOnly`, `Secure` et +`SameSite=None`. Utilisez HTTPS pour toute instance publique. + +Sur un réseau local de confiance qui ne peut pas utiliser HTTPS, une option de +compatibilité permet au cookie de fonctionner en HTTP avec `SameSite=Lax` : + +```dotenv +AUTH_ALLOW_INSECURE_COOKIES=true +``` + +::: danger +N'activez pas cette option sur Internet ou sur un réseau non fiable. Le cookie peut +alors circuler dans une connexion HTTP non chiffrée. +::: + +Une déconnexion exactement après une heure indique généralement que le cookie de +rafraîchissement n'a pas été envoyé ou accepté. Vérifiez aussi que +`ALLOWED_ORIGINS` contient exactement l'origine du navigateur. + +Le guide complet en anglais détaille +[l'authentification](/self-hosting/authentication) et le +[dépannage des déconnexions](/self-hosting/troubleshooting#unexpected-sign-outs). diff --git a/docs/self-hosting/authentication.md b/docs/self-hosting/authentication.md index 0419036..adbd49b 100644 --- a/docs/self-hosting/authentication.md +++ b/docs/self-hosting/authentication.md @@ -95,8 +95,16 @@ reference and the current provider documentation for its exact schema. ## Session lifetime After local or OIDC login, the access token lasts one hour. The browser also receives -a rotating refresh cookie valid for 30 days, so normal access-token expiry should be -silent. There is no separate “remember me” duration setting. +a rotating refresh cookie, so normal access-token expiry should be silent. The refresh +session lasts 30 days by default. Set `AUTH_SESSION_TTL_DAYS` in `.env` to choose a +value from 1 to 365 days: + +```dotenv +AUTH_SESSION_TTL_DAYS=90 +``` + +This duration applies to newly issued and renewed sessions. Existing database rows +keep their current expiry until the next successful refresh or login. The refresh cookie is `HttpOnly`, `Secure`, and `SameSite=None`. A public deployment therefore needs HTTPS, the correct `ALLOWED_ORIGINS`, and proxy handling that keeps @@ -104,6 +112,24 @@ credentialed requests intact. See [Unexpected sign-outs](./troubleshooting#unexpected-sign-outs) if a user is logged out while active. +For a trusted local network that cannot use HTTPS, an explicit compatibility option +can issue the refresh cookie without `Secure` and with `SameSite=Lax`: + +```dotenv +AUTH_ALLOW_INSECURE_COOKIES=true +``` + +::: danger +Do not enable this option on a public or untrusted network. Account refresh cookies +can travel over unencrypted HTTP. HTTPS remains the supported default. +::: + +After changing either variable, recreate Server: + +```sh +docker compose up -d --force-recreate typetype-server +``` + This explanation follows the behavior questioned by [Toni-Vide in discussion #162](https://github.com/TypeType-Video/TypeType/discussions/162) and verified in the current authentication source. diff --git a/docs/self-hosting/configuration.md b/docs/self-hosting/configuration.md index 7a0efdf..f714e98 100644 --- a/docs/self-hosting/configuration.md +++ b/docs/self-hosting/configuration.md @@ -50,6 +50,27 @@ docker compose up -d --force-recreate typetype-server This diagnostic was confirmed through [hulmgulm's first-admin report](https://github.com/TypeType-Video/TypeType/discussions/151). +## Account sessions + +| Variable | Default | Purpose | +| --- | --- | --- | +| `AUTH_SESSION_TTL_DAYS` | `30` | Refresh-session lifetime in days, clamped to `1`–`365` | +| `AUTH_ALLOW_INSECURE_COOKIES` | `false` | Allows refresh cookies over plain HTTP with `SameSite=Lax` | + +Access tokens always last one hour. A valid refresh session renews them silently, so +`AUTH_SESSION_TTL_DAYS` controls how long an account can remain signed in without a +new login. + +Keep `AUTH_ALLOW_INSECURE_COOKIES=false` for HTTPS and every public deployment. Set +it to `true` only when a trusted local-only instance must run over plain HTTP. This +weakens transport security; see [Session lifetime](./authentication#session-lifetime). + +Recreate Server after changing either value: + +```sh +docker compose up -d --force-recreate typetype-server +``` + ## Database and cache The bundled PostgreSQL service uses these values: diff --git a/docs/self-hosting/troubleshooting.md b/docs/self-hosting/troubleshooting.md index bfd5bec..1a72755 100644 --- a/docs/self-hosting/troubleshooting.md +++ b/docs/self-hosting/troubleshooting.md @@ -92,13 +92,13 @@ original [community diagnosis](https://github.com/TypeType-Video/TypeType/discus ## Unexpected sign-outs {#unexpected-sign-outs} -An account access token lasts one hour, but the refresh session lasts 30 days. The -Frontend refreshes automatically when an authenticated request returns `401`, so a -sign-out at the one-hour mark is not expected normal behavior. +An account access token lasts one hour, but the refresh session lasts 30 days by +default. The Frontend refreshes automatically when an authenticated request returns +`401`, so a sign-out at the one-hour mark is not expected normal behavior. Check: -1. The page uses HTTPS on a public domain. The refresh cookie is `Secure`. +1. The page uses HTTPS. The refresh cookie is `Secure` by default. 2. `ALLOWED_ORIGINS` contains the exact browser origin. 3. Login and `/api/auth/refresh` requests include credentials and are not stripped by a custom proxy. @@ -110,9 +110,15 @@ sets `JWT_SECRET`. That invalidates the old one-hour access token, but the norma refresh flow should recover immediately when the PostgreSQL session and refresh cookie are still present. A restart alone should therefore not require a new login. -There is no admin setting that extends the 30-day lifetime. If the problem continues, -capture Server logs around `/auth/refresh`, the browser response status, and the -deployed revisions. Do not include the cookie or any bearer token. +For a trusted local-only instance that cannot use HTTPS, set +`AUTH_ALLOW_INSECURE_COOKIES=true` and recreate `typetype-server`. This deliberately +weakens cookie transport security and must not be used on a public or untrusted +network. `AUTH_SESSION_TTL_DAYS` can change the refresh lifetime from 1 to 365 days. +See [Session lifetime](./authentication#session-lifetime). + +If the problem continues, capture Server logs around `/auth/refresh`, the browser +response status, and the deployed revisions. Do not include the cookie or any bearer +token. This checklist follows the unexpected behavior reported by [Toni-Vide in discussion #162](https://github.com/TypeType-Video/TypeType/discussions/162).