# Autenticación, MFA y OIDC

> Cuentas locales, sesiones, verificación en dos pasos, reautenticación e inicio de sesión único con un proveedor 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:

```bash
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](/es/docs/installation.md#añade-ajustes-que-no-están-en-env)):

```yaml title="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
```

```bash
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:

```yaml
      LOCAL_LOGIN: "false"
      LOCAL_LOGIN_EMERGENCY_EMAIL: emergencia@example.com
```

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](/es/docs/troubleshooting.md#acceso-y-sesiones).

---

Página HTML: https://infraward.net/es/docs/authentication/