Saltar al contenido

Autoalojamiento

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 (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.

Advertencia

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. En Notifuse Cloud la clave se gestiona por ti y el SSO está incluido en el plan Business: consulta En Notifuse Cloud.

Nota

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.

Nota

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 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

VariableDescripciónValor por defecto
OIDC_ENABLEDInterruptor general. Con false o sin definir, el SSO está desactivado y el botón oculto.false
OIDC_ISSUER_URLLa 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_IDEl client ID OAuth2 de tu IdP. Obligatorio con el SSO activado.-
OIDC_CLIENT_SECRETEl client secret OAuth2 (cliente confidencial). Se guarda cifrado y nunca se envía al navegador. Obligatorio con el SSO activado.-
OIDC_REDIRECT_URILa 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_SCOPESScopes separados por espacios. openid siempre se incluye, email es obligatorio y profile aporta el nombre visible opcional.openid email profile
OIDC_BUTTON_LABELTexto del botón de inicio de sesión.Sign in with SSO
OIDC_AUTO_CREATE_USERSAprovisionamiento just-in-time. Con true, requiere OIDC_ALLOWED_DOMAINS. Consulta Aprovisionamiento.false
OIDC_ALLOWED_DOMAINSLista 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_EMAILAcepta 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).false

Advertencia

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). 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:

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, 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:

ProveedorTiene autoridad cuando
GoogleLa 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 IDEl 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 proveedorEl 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.

Nota

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

Advertencia

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, 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:
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

Nota

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).

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:
OIDC_ENABLED=true
OIDC_ISSUER_URL=https://keycloak.example.com/realms/<your-realm>
OIDC_CLIENT_ID=notifuse
OIDC_CLIENT_SECRET=your-client-secret

Consejo

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íntomaCausa y solución
“El inicio de sesión único no está disponible temporalmente” al hacer clic en SSONotifuse 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), 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). Si no, el usuario acepta la invitación desde su enlace.
redirect_uri_mismatch / invalid_redirect_uri en el IdPLa 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 OIDCLa 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 trabajoEs 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.

Nota

¿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.