Autenticación, MFA y OIDC

Cuentas locales

Las cuentas locales entran con email y contraseña. Las contraseñas tienen entre 12 y 1024 caracteres. Las cuentas creadas en Ajustes → Usuarios empiezan con una contraseña temporal válida durante 24 horas (TEMP_PASSWORD_TTL) que hay que cambiar al entrar por primera vez.

Sesiones

La sesión vive en la base de datos y el navegador solo guarda una cookie httpOnly llamada __Host-iw_session (Secure, SameSite=Strict). Cada escritura lleva además un token CSRF en la cabecera X-CSRF-Token.

Ajuste	Por defecto	Variable
Duración máxima de la sesión	12 horas	SESSION_TTL (de 300 s a 7 días)
Cierre por inactividad	2 horas	SESSION_IDLE_TTL
Intentos de login por IP	5 por minuto; después, bloqueo de un minuto	LOGIN_THROTTLE_LIMIT, LOGIN_THROTTLE_TTL
Logins fallidos por cuenta, desde cualquier IP	10 cada 5 minutos	LOGIN_ACCOUNT_THROTTLE_LIMIT, LOGIN_ACCOUNT_THROTTLE_TTL

El límite por cuenta no bloquea las redes desde las que la cuenta entró bien en los últimos 30 días, así que un atacante no puede dejar fuera a su dueño.

Cambiar la contraseña cierra tus otras sesiones y revoca tus tokens de API. Cuando un administrador restablece la contraseña de un usuario, también terminan las sesiones y los tokens de API de ese usuario.

Verificación en dos pasos

InfraWard admite TOTP (RFC 6238) con cualquier app de autenticación.

• Los administradores que entran con contraseña tienen que activarla. El primer acceso abre la pantalla de configuración y no deja hacer nada más hasta completarla.
• Los demás roles pueden activarla en Ajustes → Perfil → Seguridad.
• Al configurarla se muestran diez códigos de recuperación de un solo uso. El perfil indica cuántos quedan y permite generar otros.
• Un administrador puede restablecer el segundo factor de otro usuario desde Ajustes → Usuarios. Eso también cierra las sesiones de ese usuario.

Los códigos TOTP y de recuperación comparten el límite de intentos del login, aplicado por usuario.

Reautenticación para acciones sensibles

Algunas acciones piden confirmar de nuevo la identidad si la última confirmación tiene más de 10 minutos (REAUTH_MAX_AGE, de 60 a 3600 segundos): purgar assets, cambiar roles, desactivar usuarios, crear tokens con escritura, revelar una contraseña de la caja fuerte, dar acceso a la terminal, abrir una terminal y cambiar los canales de alertas. Quien tiene TOTP confirma con un código; los usuarios de OIDC vuelven a pasar por el proveedor, que tiene que pedirles las credenciales (InfraWard envía prompt=login y max_age=30).

Inicio de sesión único con OIDC

InfraWard funciona con cualquier proveedor OpenID Connect: Keycloak, Authentik, Microsoft Entra ID, Google, Zitadel y otros. Definir OIDC_ISSUER lo activa y añade un botón a la página de acceso.

1. Registra InfraWard en el proveedor

Crea un cliente confidencial (o un cliente público con PKCE) con:

• Redirect URI: https://infraward.example.com/api/auth/oidc/callback
• Scopes: openid email profile, más lo que necesite tu proveedor para incluir los grupos en el ID token o en userinfo.
• Un claim con los grupos o roles del usuario (por ejemplo groups, o realm_access.roles en Keycloak).

2. Guarda el secreto del cliente

El secreto del cliente nunca va en una variable de entorno. Guárdalo en el proveedor de secretos y pasa una referencia. Con la API en marcha:

printf '{"client_secret":"PEGA-AQUÍ-EL-SECRETO"}' \
  | docker compose exec -T api node dist/cli/secret-put.js secret://openbao/oidc/sso

El JSON se lee de la entrada estándar, así que el secreto no aparece en la lista de procesos ni en el historial del shell (la línea de printf sí; mejor léelo de un fichero o de un gestor de contraseñas). Sin OpenBao, usa secret://local/oidc/sso.

Con un cliente público con PKCE, sáltate este paso y deja OIDC_CLIENT_SECRET_REF sin definir.

3. Configura la API

Añade las variables a api en compose.override.yml (y añade el fichero a COMPOSE_FILE; consulta Instalar con Docker Compose):

compose.override.yml

services:
  api:
    environment:
      OIDC_ISSUER: https://sso.example.com/realms/main
      OIDC_CLIENT_ID: infraward
      OIDC_CLIENT_SECRET_REF: secret://openbao/oidc/sso#client_secret
      OIDC_REDIRECT_URI: https://infraward.example.com/api/auth/oidc/callback
      OIDC_PROVIDER_NAME: SSO de la empresa
      OIDC_GROUPS_CLAIM: groups
      OIDC_ROLE_MAPPING: infraward-admins=admin,infraward-editors=editor,infraward-ops=operator,infraward-audit=auditor,infraward-users=viewer
      OIDC_UNMAPPED: deny

docker compose up -d api

Variable	Por defecto	Qué hace
OIDC_ISSUER	sin definir	URL del emisor. Activa OIDC. Debe ser https en producción.
OIDC_CLIENT_ID	sin definir	ID del cliente. Obligatoria con OIDC_ISSUER.
OIDC_CLIENT_SECRET_REF	sin definir	Referencia secret://…#campo al secreto del cliente. Sin ella, cliente público con PKCE.
OIDC_REDIRECT_URI	sin definir	Debe ser <URL pública>/api/auth/oidc/callback.
OIDC_TOKEN_AUTH_METHOD	client_secret_basic	O client_secret_post.
OIDC_PROVIDER_NAME	OIDC	Texto del botón de acceso.
OIDC_SCOPES	openid email profile	Debe incluir openid.
OIDC_GROUPS_CLAIM	groups	Claim con los grupos. Admite rutas con puntos, como realm_access.roles.
OIDC_ROLE_MAPPING	sin definir	Pares grupo=rol separados por comas. Si coinciden varios grupos, gana el rol con más permisos.
OIDC_UNMAPPED	deny	Qué pasa con un usuario sin ningún grupo mapeado: deny rechaza el acceso y viewer le deja entrar como lector.
OIDC_ALLOW_UNVERIFIED_SIGNUP	false	Crear las cuentas aunque el proveedor no marque el email como verificado. Ver más abajo.

Cómo se crean y actualizan las cuentas

• El primer acceso por OIDC crea el usuario automáticamente con el rol mapeado, pero solo si el proveedor marca el email como verificado (email_verified: true). Si no, el acceso se rechaza y no se crea la cuenta: quien se registrara en el proveedor con el email de otra persona se quedaría con esa dirección en InfraWard.
• Microsoft Entra ID y otros proveedores que verifican los emails por su cuenta pero no envían email_verified necesitan OIDC_ALLOW_UNVERIFIED_SIGNUP: "true". Sin ella, los usuarios nuevos no pueden entrar. Actívala solo si todas las cuentas del proveedor tienen un email verificado por él.
• El rol se recalcula a partir de los grupos en cada acceso, así que los cambios de rol se hacen en el proveedor.
• Una cuenta local existente se enlaza con la identidad OIDC cuando el proveedor informa del mismo email como verificado. OIDC_ALLOW_UNVERIFIED_SIGNUP no cambia esto.
• Con OIDC activado, los usuarios no pueden cambiar su propio email; lo cambia un administrador.

Desactivar el login con contraseña

Cuando todo el mundo entre por el proveedor, desactiva el login con contraseña y conserva una cuenta local para emergencias:

      LOCAL_LOGIN: "false"
      LOCAL_LOGIN_EMERGENCY_EMAIL: [email protected]

Con LOCAL_LOGIN=false, solo la cuenta de emergencia puede usar contraseña. Guarda su contraseña y sus códigos de recuperación fuera de línea: es la forma de entrar si el proveedor falla.

Problemas al entrar

Consulta Solución de problemas.