Saltar a contenido

Sistema de Identidad

Visión global del subsistema de identidad y autenticación de SmallCountry: cómo se gestionan usuarios, grupos, permisos y el flujo de inicio de sesión único (SSO) que protege todos los servicios.

Descripción general

La identidad en SmallCountry es centralizada y federada. Un solo proveedor —Authentik— gestiona todos los usuarios, grupos, políticas de acceso y segundo factor de autenticación (2FA). Ningún servicio maneja sus propios usuarios: todos delegan en Authentik vía OAuth2, OIDC o proxy forward-auth.

Esta decisión está documentada en el ADR-014. El principio rector es: una sola fuente de verdad para la identidad, una sola puerta para entrar.

Flujo de autenticación

sequenceDiagram
    actor Usuario as 👤 Persona
    participant Caddy as 🔒 Caddy (proxy TLS)
    participant Authentik as 🛡️ Authentik (IdP)
    participant Servicio as 📦 Servicio (Nextcloud, Immich...)

    Usuario->>Caddy: GET servicio.sc
    Caddy->>Caddy: ¿Requiere auth?

    alt No autenticado
        Caddy->>Authentik: forward_auth (sin sesión)
        Authentik->>Usuario: Redirige a login
        Usuario->>Authentik: Credenciales + 2FA
        Authentik->>Authentik: Valida credenciales y TOTP/WebAuthn
        Authentik->>Caddy: Token de sesión válido
    end

    Caddy->>Servicio: Proxy con cabeceras de autenticación
    Servicio->>Servicio: Autorización por grupo/perfil
    Servicio->>Usuario: Contenido del servicio

Estructura del directorio

Authentik organiza usuarios en grupos que reflejan los 18 roles de SmallCountry. Cada grupo tiene permisos específicos sobre qué servicios puede ver y usar.

Grupo Rol(es) Servicios con acceso
familia Vesta, Orfeo, Minerva Nextcloud, Immich, Jellyfin, Matrix, Joplin, Homepage
campo Deméter, Melissa, Fauno, Gea, Silvano farmOS, Grafana (dashboards de campo), Node-RED (lectura)
empresa Mercurio, Vulcano FacturaScripts, Mautic, Odoo, n8n (flujos de negocio)
salud Higía Joplin Server (cifrado E2E), Hermes Agent, n8n (flujos clínicos)
admin Jano, Argos, Hefesto, Hermes, Égida, Mnemósine, Terminus Proxmox, Grafana (admin), Semaphore, Forgejo, Portainer, Uptime Kuma
invitado Externos temporales Solo servicios designados con permiso explícito

Métodos de autenticación

Método Obligatorio para Descripción
Contraseña + TOTP Todos los usuarios Segundo factor con aplicación autenticadora (Aegis, Raivo)
WebAuthn / Passkeys admin Llave de seguridad física (YubiKey) como alternativa al TOTP
Proxy forward-auth Servicios sin soporte SSO Authentik actúa como intermediario. Caddy consulta a Authentik antes de enrutar
OAuth2 / OIDC Servicios con soporte nativo Integración estándar. Nextcloud, Immich, Grafana, Forgejo lo soportan
SAML Servicios enterprise Alternativa para Odoo y servicios que requieran SAML
Token de API Automatizaciones (n8n, Node-RED) Tokens de larga duración para flujos automatizados entre servicios

Mapeo de servicios

Servicio Método de auth Grupo(s) Ficha
Nextcloud OIDC familia, empresa, admin Ficha
Immich OAuth2 familia, admin Ficha
Grafana OAuth2 campo (lectura), admin (edición) Ficha
Forgejo OAuth2 admin Ficha
Matrix OIDC familia, admin Ficha
Joplin Server Forward-auth + E2E familia, salud, admin Ficha
farmOS OAuth2 campo, admin Ficha
Open WebUI OAuth2 familia, empresa, admin Ficha
Semaphore Forward-auth admin Ficha
Portainer OAuth2 admin Ficha
Uptime Kuma Forward-auth admin Ficha
Homepage Forward-auth todos (vista filtrada por grupo) Ficha
Hermes Agent Token API salud, admin Ficha
n8n OAuth2 empresa, admin Ficha
Node-RED Forward-auth campo (lectura), admin (edición) Ficha

Políticas de seguridad

Política Valor Aplica a
Longitud mínima de contraseña 16 caracteres Todos los usuarios
Rotación de contraseña 180 días (aviso), sin expiración forzada admin
Bloqueo por intentos fallidos 5 intentos → 15 min de bloqueo Todos los usuarios
2FA obligatorio Sí, sin excepción Todos los usuarios
Sesión máxima 24 horas (navegador), 7 días (apps) Todos los usuarios
IP allowlist para admin Solo desde vmbr2 (red de gestión) admin
Auditoría de accesos Logs en Victoria Logs con retención de 90 días Todos los accesos

Modo isla y degradación

En modo isla (sin internet), Authentik sigue funcionando completamente porque no depende de ningún servicio externo:

  • Las contraseñas se validan contra la base de datos local (PostgreSQL en vmbr1)
  • Los códigos TOTP se generan localmente (sin reloj externo, con tolerancia ampliada)
  • Los tokens OAuth2 emitidos antes del corte de internet siguen siendo válidos hasta su expiración
  • La IP allowlist de admin se mantiene porque los bridges de Proxmox son locales

El único escenario de riesgo es si Authentik mismo cae. En ese caso, los servicios protegidos por forward-auth dejan de ser accesibles. Es un punto único de fallo consciente, mitigado por el Protocolo de Mortalidad que define cómo recuperar Authentik desde cero en menos de 15 minutos.

Para el arquitecto

Configuración en Authentik

Provider Client ID Redirect URI Grupos
Nextcloud OIDC nextcloud https://nextcloud.sc/apps/oidc_login/oidc familia, empresa, admin
Immich OAuth2 immich https://fotos.sc/auth/login familia, admin
Grafana OAuth2 grafana https://grafana.sc/login/generic_oauth admin
Forgejo OAuth2 forgejo https://forgejo.sc/user/oauth2/authentik/callback admin
Matrix OIDC matrix https://matrix.sc/_matrix/client/v3/login/sso/redirect familia, admin

Mapeo de grupos a roles

familia       → Vesta, Orfeo, Minerva
campo         → Deméter, Melissa, Fauno, Gea, Silvano
empresa       → Mercurio, Vulcano
salud         → Higía
admin         → Jano, Argos, Hefesto, Hermes, Égida, Mnemósine, Terminus

Fichas relacionadas

  • Authentik — Proveedor de identidad y SSO
  • Caddy — Proxy inverso con forward-auth
  • Vaultwarden — Gestor de contraseñas
  • Pi-hole — DNS interno para .sc
  • Fail2Ban — Protección contra fuerza bruta
📋 Relacionado con
🔧 Operaciones