Skip to main content

Documentation Index

Fetch the complete documentation index at: https://woku.app/docs/llms.txt

Use this file to discover all available pages before exploring further.

Disponible en el plan Corporate. Esta funcionalidad forma parte de las capacidades empresariales de woku. Conversa con nuestro equipo comercial.
Woku soporta SSO empresarial (SAML 2.0 + OpenID Connect) para que los usuarios de una empresa puedan iniciar sesión con el proveedor de identidad (IdP) que ya usan internamente: Azure AD / Microsoft Entra, Okta, OneLogin, Google Workspace, ADFS, etc. El intermediario técnico es Stytch B2B: Stytch hospeda las conexiones SAML/OIDC y nos entrega un token verificable cuando la autenticación del IdP termina exitosamente.
Caso de referencia. RE/MAX Chile utiliza SSO con woku integrando su Active Directory de Microsoft Azure AD (Entra ID).

​
Modelo

  • Una empresa Woku ↔ una Organization Stytch. Cada empresa que habilita SSO se vincula a una organización en Stytch.
  • Una organización Stytch ↔ una o más conexiones SAML/OIDC. Las conexiones se configuran en el dashboard de Stytch (XML metadata del IdP, attribute mapping, certificados, etc.).
  • Lista blanca de dominios. Cada empresa que habilita SSO declara qué dominios de correo pueden usar SSO contra esa organización. Esto evita ataques de impersonación cross-tenant.
  • Identidad escopada por organización + miembro Stytch. Una vez que un usuario Woku entra por SSO, lo vinculamos a la tupla (stytchOrganizationId, stytchMemberId). Los logins siguientes resuelven por esa tupla, no por email, lo que cierra la ventana de impersonación incluso si el email cambia o se reutiliza.
  • Opt-in per-empresa. Por defecto SSO está apagado y los usuarios inician sesión con email + contraseña + (opcional) MFA TOTP.

​
Activar SSO en tu empresa

Pre-requisitos:
  1. Tener una organización Stytch creada (la primera vez la creamos nosotros para ti).
  2. Tener al menos una conexión SAML u OIDC configurada en esa organización contra tu IdP.
Luego, desde Woku:
  1. Ve a Empresa → Seguridad → SSO.
  2. Marca Habilitado e ingresa lo que te entrega Stytch:
    • Stytch Organization ID (formato organization-prod-...).
    • Stytch Connection ID (formato saml-connection-prod-... u oidc-connection-prod-...).
  3. Agrega al menos un dominio de correo permitido (por ejemplo acme.com). Solo los usuarios cuyo email termine en alguno de esos dominios podrán completar el SSO contra esta empresa.
  4. Guarda.
El backend rechaza activar SSO sin Organization ID, Connection ID y al menos un dominio permitido (400 BadRequest). Esto evita dejar la empresa con SSO habilitado pero sin destino ni control de quién puede entrar.

​
Por qué la lista de dominios

Sin esta lista, un IdP malicioso (o mal configurado) podría afirmar un correo de otra empresa (alguien@otra-empresa.com) y obtener acceso al tenant equivocado. Con la lista, el backend rechaza con 403 cualquier aserción SSO cuyo dominio de correo no figure entre los autorizados de la empresa.

​
Cómo es el flujo de login (SP-initiated)

Vista desde el usuario:
  1. El usuario abre la página de login del admin y escribe su correo. Hace clic en Continuar.
  2. El admin consulta el servicio de descubrimiento para resolver qué método mostrar:
    • Si el dominio del correo está en alguna empresa con SSO habilitado, aparece el botón Continuar con SSO.
    • En caso contrario, aparece el campo Contraseña.
  3. Si fue SSO: el navegador es redirigido a Stytch, Stytch al IdP, el IdP de vuelta a Stytch, y Stytch a nuestro callback. Después de intercambiar el token, redirige al admin con los tokens Woku en el fragmento de URL y la sesión queda iniciada.
Vista desde el backend:
  1. El descubrimiento resuelve si el dominio del correo pertenece a alguna empresa con SSO activo. La respuesta indica el modo (sso o password) y tiene forma estable independiente de si el usuario existe en Woku, para no filtrar datos de enumeración.
  2. Cuando el usuario aprieta Continuar con SSO, el backend valida que la empresa tenga SSO habilitado y responde con un 302 redirect a la URL pública de Stytch.
  3. Stytch redirige al IdP donde el usuario se autentica.
  4. El IdP redirige de vuelta a Stytch, que valida la aserción y redirige al callback de Woku.
  5. Woku intercambia el token (stytch.sso.authenticate), resuelve la empresa por organization_id, verifica que el dominio del correo afirmado esté en ssoEmailDomains, busca al usuario primero por (stytchOrganizationId, stytchMemberId) y, si es la primera vez, hace JIT provisioning + registra la identidad. Finalmente asegura la membresía UserCompany, emite un par de tokens Woku (access + refresh) y redirige al admin con los tokens en el fragmento de URL.
  6. La página de callback del admin lee el fragmento, persiste el token en el store de autenticación, abre el canal de tiempo real y limpia el fragmento del historial antes de redirigir al usuario al dashboard.
V1 soporta solo el flujo SP-initiated (el usuario empieza en Woku). IdP-initiated llega en una iteración posterior.

​
Just-In-Time provisioning

Cuando un usuario inicia sesión por SSO por primera vez:
  1. Resolución por identidad scopeada. Primero buscamos un usuario Woku que ya tenga registrada la identidad (stytchOrganizationId, stytchMemberId). Si existe, lo usamos.
  2. Fallback por email. Si no había identidad registrada, buscamos por email normalizado. Si el usuario existe lo vinculamos a la nueva identidad para los siguientes logins.
  3. JIT. Si tampoco existe el email, lo creamos automáticamente con un username derivado del email y una contraseña aleatoria (que el usuario nunca usa). Marcamos la cuenta como confirmada.
  4. Membresía. En todos los casos aseguramos que el usuario tenga membresía UserCompany en la empresa correspondiente. El rol por defecto es member. Si necesitas que los usuarios SSO entren con rol admin, contacta a soporte (UI de mapeo de roles está en backlog).
Cada login SSO queda registrado en el registro de auditoría como auth.sso.login con actorEmail, companyId, stytchOrganizationId, stytchMemberId, newlyLinked (true cuando recién se registró la identidad) e IP.

​
Garantías

  • El secreto de Stytch nunca toca el cliente. Solo el STYTCH_PUBLIC_TOKEN (público por diseño) se incluye en la URL de start; el STYTCH_SECRET vive solo en el backend.
  • Validación server-side. La sesión Woku se emite únicamente después de que Stytch confirma la autenticación. El token de Stytch es de un solo uso.
  • Aislamiento per-empresa. El callback rechaza con 403 si la organización Stytch no está vinculada a ninguna empresa Woku.
  • Anti-impersonación cross-tenant. El callback rechaza con 403 si el dominio del correo afirmado por el IdP no figura en ssoEmailDomains, y la identidad Woku se resuelve por la tupla (stytchOrganizationId, stytchMemberId) antes que por email.
  • No enumeración. La respuesta del descubrimiento no depende de si el usuario existe en Woku; solo del dominio del correo. Está rate-limitada para desincentivar barridos.
  • Auditable. Todos los pasos quedan registrados.

​
Limitaciones conocidas (V1)

  • La configuración detallada de SAML/OIDC (XML metadata, attribute mapping, certificados) se hace en el dashboard de Stytch, no en el panel de Woku. Solo los IDs y los dominios viven en Woku.
  • Solo SP-initiated. IdP-initiated requiere endpoint adicional; llega en la siguiente iteración.
  • Sin mapeo de roles automático: todos los usuarios SSO entran como member por defecto. Los upgrades a admin/owner se hacen manualmente desde Empresa → Miembros.
  • El add-on de SSO es opt-in y monetizable: el modelo comercial (precio del add-on) se documenta aparte. Mientras tanto el flag ssoEnabled se enciende manualmente.

​
Pérdida de acceso

Si la conexión SAML/OIDC del IdP se rompe, si el dominio del email del usuario cambia, o si necesitas agregar/quitar un dominio permitido sin acceso al panel, contacta a soporte (team@woku.app) para deshabilitar SSO temporalmente o reasignar la membresía manualmente.