SSO OIDC para organizaciones

Qué es SSO

El inicio de sesión único (SSO) permite que tu equipo entre en Capydox usando el proveedor de identidad corporativo (Microsoft Entra ID, Okta, Auth0, Google Workspace con OIDC, etc.) mediante OpenID Connect (OIDC).

Requisitos

• Plan Business (o el que habilite SSO en tu despliegue).
• En el IdP: aplicación confidencial (web con servidor / “regular web”), no solo un SPA público sin client_secret si tu proveedor lo exige para el intercambio de código.
• En Capydox: Issuer, Client ID, Client Secret, Redirect URI alineada con el despliegue y dominios permitidos si usas entrada por correo.

Flujo técnico (resumen)

1. El usuario inicia SSO desde Capydox (slug o correo corporativo).
2. El backend devuelve la URL de autorización del IdP (authorization_endpoint del discovery OIDC).
3. El IdP autentica y redirige al callback del backend con code y state.
4. El backend intercambia el código por tokens, identifica al usuario y redirige al frontend con la sesión establecida.

Endpoints habituales del API (prefijo /api): GET /api/auth/sso/oidc/start?slug=, GET /api/auth/sso/oidc/start-by-email?email=, GET /api/auth/sso/oidc/callback. Existen rutas equivalentes sin /api solo por compatibilidad con IdPs ya configurados.

Qué registrar en el IdP

Concepto	Qué hacer
Tipo de app	Aplicación web con servidor (nombre distinto según IdP: “Web”, “Regular Web”, confidencial, etc.).
Redirect URI	Exactamente la URL pública del callback, misma que en Capydox. Ruta canónica: {origen_del_API}/api/auth/sso/oidc/callback (mismo esquema, host, puerto y path; sin barra final de más si el IdP es estricto).
Issuer	La URL que indica la documentación OpenID de tu IdP (a veces incluye /v2.0 en Entra, u host de tenant en Auth0). Debe coincidir carácter a carácter con lo que pegas en Capydox.
Scopes	Recomendados: openid profile email (ajusta si tu IdP usa nombres distintos).
Secret	Guarda el Client Secret en Capydox; tras rotarlo en el IdP, vuelve a pegarlo y guardar en la organización.

Variables de entorno (API y frontend)

La Redirect URI que ves en la UI de organización se calcula a partir de NEXT_PUBLIC_API_URL en el frontend (p. ej. https://api.ejemplo.com/api → origen https://api.ejemplo.com + /api/auth/sso/oidc/callback).

En el backend, alinea el origen público del API con lo que registraste en el IdP:

Variable	Rol
PUBLIC_API_ORIGIN	Origen del API sin barra final (p. ej. https://api.ejemplo.com). Si en la organización dejas vacío el campo Redirect URI en base de datos, Capydox usa ${PUBLIC_API_ORIGIN}/api/auth/sso/oidc/callback. Por defecto local: http://localhost:8080.
FRONTEND_URL	Origen del frontend (p. ej. https://app.ejemplo.com) para redirecciones tras el callback; no debe ser el mismo host/puerto que el API en producción.

En producción, define siempre estas variables; no dependas solo de los valores por defecto de desarrollo.

Configuración en Capydox

En Organización → Configuración, activa OIDC y completa los campos. Los scopes por defecto suelen ser openid profile email.

Campos principales

Campo	Descripción
Issuer	URL del proveedor según su documentación OpenID (Entra, Okta, Auth0…).
Client ID	Identificador de la aplicación en el IdP.
Client Secret	Secreto confidencial; se almacena en servidor. Si lo rotas en el IdP, actualízalo aquí.
Redirect URI	Debe coincidir con la URL registrada en el IdP. Vacío en BD → se usa ${PUBLIC_API_ORIGIN}/api/auth/sso/oidc/callback.
Dominios permitidos	Dominios de correo separados por comas; necesarios para el flujo por correo corporativo.

Login por slug vs por correo

• Slug de organización: el usuario conoce el identificador corto de la org (p. ej. desde comunicación interna). No requiere que el dominio del correo esté en la lista si el flujo por slug es el usado.
• Correo corporativo: Capydox resuelve la organización por el dominio del email y la lista Dominios permitidos. Si varias organizaciones comparten el mismo dominio, el sistema puede rechazar el login por ambigüedad; en ese caso unifica dominios o usa slug.

Flujo en la app

Pestaña SSO corporativo en el login: introduce slug o correo según el modo y Continuar; tras volver del IdP, la sesión queda en Capydox.

Enforcement

Si SSO está obligatorio para la organización, los miembros no podrán usar solo correo y contraseña local: deben usar el proveedor.

Checklist antes de producción

• Issuer copiado exactamente como en el IdP (mayúsculas, https, paths /v2.0, etc.).
• Redirect URI idéntica en IdP y Capydox (y PUBLIC_API_ORIGIN / NEXT_PUBLIC_API_URL coherentes con la URL real).
• Tipo de aplicación admite intercambio de código con client secret donde aplique.
• Dominios permitidos revisados si usas login por correo.
• Prueba en ventana privada tras desplegar (caché y cookies limpias).
• FRONTEND_URL apunta al origen real del frontend.

Buenas prácticas

• Rota el Client Secret periódicamente.
• Revisa en el IdP los accesos y revoca tokens o apps obsoletas.
• Mantén actualizada la lista de dominios permitidos.

Guía relacionada: FAQ de seguridad SSO.