> ## Documentation Index
> Fetch the complete documentation index at: https://www.notifuse.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Inicio de sesión único (OIDC)

> Permite que los usuarios inicien sesión en Notifuse con tu proveedor de identidad (Google Workspace, Keycloak, Okta, …) mediante OpenID Connect, además del inicio de sesión con código mágico.

Notifuse admite el **Inicio de sesión único (SSO)** mediante [OpenID Connect](https://openid.net/connect/) (OIDC), para que tu equipo inicie sesión con un proveedor de identidad (IdP) externo como Google Workspace, Keycloak, Okta, Microsoft Entra ID, Authentik o Dex.

El SSO funciona junto al inicio de sesión con código mágico integrado y no lo sustituye. Con el SSO activado, la página de inicio de sesión muestra un botón **"Iniciar sesión con SSO"** junto al formulario de correo. Con cualquiera de los dos métodos, el usuario entra en la misma cuenta.

> [!WARNING]
>
> **El SSO necesita una licencia que lo incluya** (el nivel Enterprise). En una instalación sin ella, el botón **Iniciar sesión con SSO** no aparece, sea cual sea la configuración del SSO, y todo el mundo inicia sesión con un código. Nadie se queda sin acceso: cada cuenta SSO tiene una dirección de correo verificada, el inicio de sesión con código siempre funciona y las sesiones ya abiertas no se ven afectadas. En ese caso, el registro de arranque indica `sso_gated=true` y **Configuración → Sistema** lo señala junto al interruptor. Al instalar una licencia que incluya el SSO, el botón vuelve al instante, sin reiniciar. Consulta [Claves de licencia](https://www.notifuse.com/es/docs/self-hosting/licence.md). En Notifuse Cloud la clave se gestiona por ti y el SSO está incluido en el plan Business: consulta [En Notifuse Cloud](https://www.notifuse.com/es/docs/self-hosting/licence.md#on-notifuse-cloud).

> [!NOTE]
>
> El SSO está desactivado por defecto. En los despliegues existentes que no lo configuran no cambia nada: la página de inicio de sesión sigue exactamente igual, solo con el formulario de código mágico.

## Cómo funciona

Notifuse actúa como _Relying Party_ OIDC con el **flujo Authorization Code con PKCE**:

1. El usuario hace clic en **Iniciar sesión con SSO** y Notifuse lo redirige a tu IdP.
2. El usuario se autentica en el IdP (con el MFA y las políticas que apliques allí).
3. El IdP lo redirige de vuelta a `…/api/user.oidc.callback`. Notifuse verifica el token de ID en el servidor (firma, emisor, audiencia, nonce, caducidad) e inicia la sesión del usuario.

Los tokens del IdP se intercambian y se verifican por completo en el servidor: al navegador solo llega el token de sesión propio de Notifuse. PKCE está siempre activado y el secreto de cliente nunca se expone al frontend.

> [!NOTE]
>
> **Iniciar sesión no da acceso a un espacio de trabajo.** Un inicio de sesión SSO correcto autentica al _usuario_, pero no le da acceso a ningún espacio de trabajo. Los usuarios SSO siguen necesitando una invitación a un espacio de trabajo (o ser un `ROOT_EMAIL`) para poder hacer algo. Consulta [Aprovisionamiento](#provisioning) más abajo.

## Configuración

OIDC se puede configurar de tres formas, en este orden de prioridad:

1. **Variables de entorno** (`OIDC_*`): recomendadas en producción, y siempre tienen prioridad.
2. **Asistente de configuración**: una sección opcional **Inicio de sesión único** en el primer arranque, con la URI de redirección que debes registrar en tu IdP y los scopes.
3. **Configuración del sistema** → **SSO (OpenID Connect)**: el panel de administración del selector de espacios de trabajo en la consola después de la instalación.

Cuando un valor viene de una variable de entorno, el campo correspondiente aparece en solo lectura en el asistente o en la configuración. En el asistente, definir `OIDC_ENABLED`, `OIDC_ISSUER_URL` o `OIDC_CLIENT_ID` bloquea toda la sección, que entonces muestra las variables definidas. Al guardar la configuración OIDC desde la interfaz, el servidor se reinicia de forma ordenada para recargarla (igual que con la configuración SMTP). El secreto de cliente se guarda cifrado en la base de datos.

### Variables de entorno

| Variable                      | Descripción                                                                                                                                                                                                                                                                                                                                                                                                                                  | Valor por defecto          |
| ----------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------- |
| `OIDC_ENABLED`                | Interruptor general. Con `false` o sin definir, el SSO está desactivado y el botón oculto.                                                                                                                                                                                                                                                                                                                                                   | `false`                    |
| `OIDC_ISSUER_URL`             | La URL del emisor de tu IdP (debe ser **https**). Notifuse descubre el resto en `<issuer>/.well-known/openid-configuration`. Obligatoria con el SSO activado.                                                                                                                                                                                                                                                                                | -                          |
| `OIDC_CLIENT_ID`              | El client ID OAuth2 de tu IdP. Obligatorio con el SSO activado.                                                                                                                                                                                                                                                                                                                                                                              | -                          |
| `OIDC_CLIENT_SECRET`          | El client secret OAuth2 (cliente confidencial). Se guarda cifrado y nunca se envía al navegador. Obligatorio con el SSO activado.                                                                                                                                                                                                                                                                                                            | -                          |
| `OIDC_REDIRECT_URI`           | La URL de callback registrada en tu IdP. Si está vacía, se deriva como `<API_ENDPOINT>/api/user.oidc.callback`.                                                                                                                                                                                                                                                                                                                              | derivada de `API_ENDPOINT` |
| `OIDC_SCOPES`                 | Scopes separados por espacios. `openid` siempre se incluye, `email` es obligatorio y `profile` aporta el nombre visible opcional.                                                                                                                                                                                                                                                                                                            | `openid email profile`     |
| `OIDC_BUTTON_LABEL`           | Texto del botón de inicio de sesión.                                                                                                                                                                                                                                                                                                                                                                                                         | `Sign in with SSO`         |
| `OIDC_AUTO_CREATE_USERS`      | Aprovisionamiento just-in-time. Con `true`, requiere `OIDC_ALLOWED_DOMAINS`. Consulta [Aprovisionamiento](#provisioning).                                                                                                                                                                                                                                                                                                                    | `false`                    |
| `OIDC_ALLOWED_DOMAINS`        | Lista de dominios de correo permitidos, separados por comas, punto y coma o espacios, que limita la creación automática. **Obligatoria** con `OIDC_AUTO_CREATE_USERS=true` (si no, el servidor no arranca).                                                                                                                                                                                                                                  | -                          |
| `OIDC_ALLOW_UNVERIFIED_EMAIL` | Acepta un token de ID sin claim `email_verified`, para los proveedores que nunca lo envían (Microsoft Entra ID, Cloudflare Access). En un primer inicio de sesión, un token con `email_verified: false` se rechaza. Una identidad ya vinculada a una cuenta inicia sesión por su subject y no se vuelve a comprobar. Una dirección no verificada nunca cuenta para una invitación pendiente (consulta [Usuarios invitados](#invited-users)). | `false`                    |

> [!WARNING]
>
> Con `OIDC_ENABLED=true`, el servidor valida la configuración al arrancar y se detiene de inmediato si no es válida (falta el emisor, el cliente o el secreto, el emisor no es https, o la creación automática está activada sin lista de dominios). La misma validación se hace antes de guardar desde el panel de configuración, así que una configuración incorrecta se rechaza con un error en lugar de guardarse.

## Aprovisionamiento

Por defecto, el SSO es **solo para usuarios invitados**: un usuario puede iniciar sesión con SSO solo si ya tiene una cuenta de Notifuse o lo han invitado a un espacio de trabajo (consulta [Usuarios invitados](#invited-users)). Un inicio de sesión SSO con una dirección que nadie invitó se rechaza con un mensaje de "sin cuenta". Así se mantiene el modelo de Notifuse, en el que nadie se registra por su cuenta.

Para que los usuarios nuevos se creen automáticamente en su primer inicio de sesión SSO, define:

```bash
OIDC_AUTO_CREATE_USERS=true
OIDC_ALLOWED_DOMAINS=yourcompany.com
```

Con la creación automática activada, se crea una cuenta en el primer inicio de sesión cuando el IdP declara un correo verificado **y** su dominio está en `OIDC_ALLOWED_DOMAINS`. Aun así, el nuevo usuario no tiene acceso a ningún espacio de trabajo hasta que lo inviten. Una dirección con una invitación pendiente sigue en cambio las reglas de [Usuarios invitados](#invited-users), en los dos sentidos: la invitación puede crear la cuenta fuera de la lista de dominios, y un proveedor que no tiene autoridad sobre la dirección no crea ninguna.

### Usuarios invitados

Un invitado no necesita abrir el enlace del correo antes de iniciar sesión con SSO. En su primer inicio de sesión SSO, una invitación pendiente a su dirección crea su cuenta. Esto vale en el modo solo para invitados, e incluso cuando su dominio no está en `OIDC_ALLOWED_DOMAINS`, ya que una invitación es la elección explícita de esa dirección concreta por parte de un propietario. La invitación no se acepta en su nombre: el usuario llega a la lista de espacios de trabajo, en **Invitaciones pendientes**, y hace clic en **Unirse**.

Esto solo ocurre cuando tu proveedor de identidad tiene autoridad sobre la dirección, porque unirse desde la consola se basa en la dirección que declara el proveedor:

| Proveedor                | Tiene autoridad cuando                                                                                                                                                                                                                                                                                                                                                   |
| ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Google                   | La dirección termina en `@gmail.com` o pertenece a una cuenta de Google Workspace (el claim `hd`). Google no responde de una cuenta personal de Google registrada con una dirección de otro dominio.                                                                                                                                                                     |
| Microsoft Entra ID       | El usuario es miembro de tu tenant y el token de ID lleva el claim opcional `xms_edov` con valor true. Añádelo en el registro de tu aplicación en **Token configuration → Add optional claim → ID**. Los invitados que inician sesión con una cuenta personal de Microsoft o de Google, o con un código de un solo uso, no cuentan: Entra también les asigna `xms_edov`. |
| Cualquier otro proveedor | El token de ID lleva `email_verified: true`. Un proveedor que hace de intermediario de otros (Keycloak, Dex, las conexiones sociales de Auth0) responde de sus direcciones con su propio `email_verified`, así que transmítelo solo para direcciones en las que confíes.                                                                                                 |

Cuando el proveedor no tiene autoridad, el SSO no crea ninguna cuenta para una dirección invitada (ni siquiera con `OIDC_AUTO_CREATE_USERS`), y el invitado abre el enlace de su correo de invitación. Una vez que la acepta, puede usar el SSO desde ese momento.

> [!NOTE]
>
> Los usuarios se identifican por el par duradero `(issuer, subject)` del IdP, no por el correo, así que un usuario conserva la misma cuenta aunque su correo cambie en el IdP. El correo solo se usa en el primer inicio de sesión: para vincular una identidad SSO a una cuenta existente o para encontrar las invitaciones pendientes para esa dirección. Una cuenta `ROOT_EMAIL` nunca se puede vincular automáticamente a una identidad externa (una protección contra la toma de control de la administración de la plataforma).

## Configuración del proveedor de identidad

La URL de callback o de redirección que hay que registrar en cada proveedor es:

```
https://<your-notifuse-domain>/api/user.oidc.callback
```

> [!WARNING]
>
> La URI de redirección debe coincidir **byte a byte** entre tu IdP y Notifuse. Si usas un proxy inverso que reescribe el esquema o el host, define `OIDC_REDIRECT_URI` explícitamente con la URL visible desde fuera. Si no, el IdP devuelve un error `redirect_uri_mismatch`.

### Google Workspace

1. En la [Google Cloud Console](https://console.cloud.google.com/apis/credentials), ve a **APIs & Services → Credentials → Create credentials → OAuth client ID**.
2. Elige **Web application**.
3. En **Authorized redirect URIs**, añade `https://<your-notifuse-domain>/api/user.oidc.callback`.
4. Copia el **Client ID** y el **Client secret**.
5. Configura Notifuse:

```bash
OIDC_ENABLED=true
OIDC_ISSUER_URL=https://accounts.google.com
OIDC_CLIENT_ID=xxxxxxxx.apps.googleusercontent.com
OIDC_CLIENT_SECRET=your-client-secret
# Restrict to your organization's domain:
OIDC_ALLOWED_DOMAINS=yourcompany.com
```

> [!NOTE]
>
> Las cuentas personales `@gmail.com` y las cuentas de tu Workspace comparten el emisor `accounts.google.com`. Usa `OIDC_ALLOWED_DOMAINS` (o mantén el modo por defecto, solo para invitados) para limitar el inicio de sesión a tu organización. Una dirección `@gmail.com` que hayas invitado puede seguir iniciando sesión (consulta [Usuarios invitados](#invited-users)).

### Keycloak

1. En tu realm, crea un cliente: **Client type** OpenID Connect, **Client authentication** ON (confidencial), **Standard flow** activado.
2. Define **Valid redirect URIs** como `https://<your-notifuse-domain>/api/user.oidc.callback`.
3. Copia el secreto de la pestaña **Credentials** del cliente.
4. Configura Notifuse:

```bash
OIDC_ENABLED=true
OIDC_ISSUER_URL=https://keycloak.example.com/realms/<your-realm>
OIDC_CLIENT_ID=notifuse
OIDC_CLIENT_SECRET=your-client-secret
```

> [!TIP]
>
> Los client scopes por defecto de Keycloak ya emiten `email`, `email_verified`, `name` y `sub`. Si alguien ha quitado el mapper de correo de tu cliente, los inicios de sesión SSO se rechazan (sin claim de correo): vuelve a añadir el scope integrado `email`.

### Otros proveedores

Cualquier proveedor certificado OpenID Connect funciona igual: define `OIDC_ISSUER_URL` con el emisor del proveedor, registra la URI de redirección e indica el client ID y el secreto. Esto incluye Okta, Microsoft Entra ID (Azure AD), Authentik y Dex.

## Notas de seguridad

- Solo dos valores no secretos llegan al navegador: `window.OIDC_ENABLED` y el texto del botón. El client ID, el client secret y la URL del emisor nunca se exponen en la página.
- Los tokens de ID se verifican con las claves publicadas por el emisor (rotadas automáticamente mediante JWKS). Se comprueban la firma, el emisor, la audiencia, el nonce y la caducidad, y solo se aceptan algoritmos asimétricos (RS256/ES256).
- El estado CSRF, nonce y PKCE del flujo se guarda en una cookie `HttpOnly` cifrada y de corta duración.
- Las llamadas HTTP de OIDC (descubrimiento, obtención de claves, intercambio de tokens) tienen un tiempo límite, así que un emisor lento o inaccesible no puede bloquear el inicio de sesión. El inicio de sesión con código mágico no se ve afectado.

## Solución de problemas

| Síntoma                                                                                                        | Causa y solución                                                                                                                                                                                                                                                                                                                                                                            |
| -------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **"El inicio de sesión único no está disponible temporalmente"** al hacer clic en SSO                          | Notifuse no puede llegar al emisor ni descubrirlo. Comprueba que `OIDC_ISSUER_URL` es correcta, que el servidor puede llegar a ella y que sirve un documento de descubrimiento. Notifuse vuelve a intentarlo automáticamente cuando el emisor está de nuevo disponible.                                                                                                                     |
| **"Ninguna cuenta de Notifuse está vinculada… Si te han invitado, abre el enlace de tu correo de invitación"** | La dirección no tiene cuenta y el SSO no tiene nada a partir de lo cual crearla. O bien nadie la invitó (invita al usuario, o activa `OIDC_AUTO_CREATE_USERS` con una lista de dominios), o bien tiene una invitación pendiente pero tu proveedor no tiene autoridad sobre la dirección (consulta [Usuarios invitados](#invited-users)), y el usuario acepta la invitación desde su enlace. |
| **"El inicio de sesión único no puede crear una cuenta para tu dominio de correo"**                            | La creación automática está activada y la dirección está fuera de `OIDC_ALLOWED_DOMAINS`. Añade el dominio o invita al usuario: una invitación anula la lista de dominios para esa dirección cuando tu proveedor tiene autoridad sobre ella (consulta [Usuarios invitados](#invited-users)). Si no, el usuario acepta la invitación desde su enlace.                                        |
| **`redirect_uri_mismatch` / `invalid_redirect_uri` en el IdP**                                                 | La URI de redirección registrada en el IdP no coincide exactamente con la que envía Notifuse. Registra `…/api/user.oidc.callback` y define `OIDC_REDIRECT_URI` si estás detrás de un proxy que reescribe el esquema o el host.                                                                                                                                                              |
| **El servidor no arranca después de activar OIDC**                                                             | La validación de la configuración falló. Comprueba que `OIDC_ISSUER_URL` es https, que `OIDC_CLIENT_ID` y `OIDC_CLIENT_SECRET` están definidos y que `OIDC_ALLOWED_DOMAINS` no está vacía con `OIDC_AUTO_CREATE_USERS=true`.                                                                                                                                                                |
| **Un usuario puede iniciar sesión pero no accede a ningún espacio de trabajo**                                 | Es lo esperado: iniciar sesión no es una autorización. Invita al usuario al espacio de trabajo correspondiente (o añádelo a `ROOT_EMAIL`). Una invitación pendiente aparece en su lista de espacios de trabajo con un botón **Unirse**.                                                                                                                                                     |

> [!NOTE]
>
> ¿Ejecutas varias réplicas de Notifuse detrás de un balanceador de carga? El código de un solo uso que completa el traspaso del SSO se guarda en cada instancia, así que activa las **sesiones persistentes** (sticky sessions) para que el SSO funcione bien entre réplicas. Los despliegues de una sola instancia no necesitan ninguna configuración adicional.
