Desk Entrar

Arquitectura de autenticación (Folks SSO)

Documentación técnica Actualizado 24 jun 2026

Resumen

Folks emite JWT ES256 como access token en cookie HttpOnly zolski-session y refresh opaco en zolski-refresh, ambos scoped a .zolski.net para SSO cross-subdominio.

JWT ES256

  • Algoritmo: ECDSA P-256 (ES256).
  • Claims típicos: sub (user_id UUID), email, username, user_code, tier, exp.
  • Clave privada: ES256_PRIVATE_KEY (Folks). Apps consumidoras usan JWT_PUBLIC_KEY_B64.

Cookies

Cookie Tipo Atributos
zolski-session JWT access HttpOnly, Secure, SameSite=Lax, Domain=.zolski.net
zolski-refresh Opaque (tabla refresh_tokens) Idem

TTL configurables vía env (ACCESS_TOKEN_TTL, REFRESH_TOKEN_TTL).

Flujo login

  1. POST /api/auth/login → valida bcrypt.
  2. Emite access + refresh, Set-Cookie en response.
  3. Redirect o JSON según cliente.
  4. Apps hijas leen zolski-session en cada request.

Refresh rotation

POST /api/auth/refresh con cookie zolski-refresh emite nuevo par y rota el token en DB. Refresh inválido → 401, cliente redirige a login.

OAuth linking

Rutas /auth/link/* y callbacks Google/Microsoft. Scopes mínimos para Gmail/Drive o Graph/OneDrive. Refresh tokens OAuth almacenados cifrados (AES-256-GCM, HKDF per-sub).

Gates en Desk/Kalista

  • require_auth: JWT válido.
  • require_staff: tier staff o admin.
  • require_admin: tier admin exclusivo.

Invariantes

  • Nunca almacenar password en plaintext.
  • JWT private key solo en Folks.
  • Logout borra cookies y revoca refresh actual.

Ver también