SAML 2.0 SSO

cside te permite conectar cualquier proveedor de identidad (IdP) SAML 2.0 y usarlo para autenticar usuarios en tu organización de cside. Una sola configuración genérica cubre todos los proveedores compatibles con SAML, así que los pasos son los mismos si usas Okta, Microsoft Entra ID, OneLogin, JumpCloud, Ping, Keycloak o un IdP propio.

Cuando habilitas SAML SSO, cualquier persona con el dominio de correo electrónico de tu empresa será redirigida para autenticarse con tu IdP. Esto significa que puedes usar tu IdP para controlar quién puede acceder a cside, y cuando permites a alguien, será automáticamente agregado a tu organización de cside sin permisos.

Requisitos:

• Plan Enterprise de cside
• Rol de administrador de organización en cside
• SAML 2.0 SSO habilitado para tu organización por cside
• Una organización de cside ya configurada - el administrador inicial (tú) será el primer usuario y será convertido a SSO tras la migración
• Acceso de administrador a un proveedor de identidad SAML 2.0 que pueda firmar aserciones y publicar sus metadatos

Si prefieres OIDC, consulta las guías de Okta, Duo o Microsoft Entra ID. Una organización puede tener una configuración OIDC y una SAML al mismo tiempo, siempre que cada dominio de correo esté reclamado por solo una de ellas.

Navegar a la configuración de SSO

Puedes abrir la configuración de tu organización directamente, o navegar manualmente:

1. Haz clic en tu cuenta en la esquina inferior izquierda del panel
2. Selecciona View organization

3. Selecciona Settings

4. Navega a la pestaña SSO
5. Haz clic en Select Provider (o Change Provider si ya tienes SSO configurado) y selecciona SAML 2.0

Agregar cside a tu proveedor de identidad

La parte superior de la sección SAML 2.0 muestra los dos valores que necesita tu IdP. Cópialos desde el panel a la aplicación SAML que crees en tu IdP:

Valor mostrado en cside	Dónde va en tu IdP	Valor actual
Assertion Consumer Service (ACS) URL	ACS URL, Reply URL o Single sign-on URL	https://gql.cside.com/v1/auth/saml/acs
Service provider entity ID (Audience)	Entity ID, Audience URI o Identifier	https://cside.dev/saml/sp

Si tu IdP prefiere importar un documento de metadatos del proveedor de servicios, apúntalo a https://gql.cside.com/v1/auth/saml/metadata.

Luego configura la aplicación de la siguiente manera. Los nombres exactos de los campos varían según el IdP, pero todos los proveedores SAML 2.0 exponen estos ajustes:

1. Name ID: Establece el formato en emailAddress (urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress) y asígnalo a la dirección de correo principal del usuario. cside usa este valor para identificar al usuario.
2. Atributos (opcional): Agrega un atributo de nombre para mostrar. cside reconoce displayName, name, urn:oid:2.16.840.1.113730.3.1.241, urn:oid:2.5.4.3 y el claim http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name. Sin este atributo, se usa la dirección de correo del usuario como su nombre.
3. Firma: Firma la aserción. Firmar también la respuesta completa está bien, pero una aserción sin firmar dentro de una respuesta firmada es rechazada. Usa SHA-256.
4. Cifrado: Deja el cifrado de aserciones desactivado. cside no publica un certificado de cifrado, así que las aserciones cifradas no pueden leerse.
5. Solicitudes firmadas: No exijas solicitudes de autenticación firmadas. cside envía solicitudes SAML sin firmar.
6. Binding: El endpoint de inicio de sesión único de tu IdP debe admitir el binding HTTP-Redirect. cside envía al usuario allí y recibe la respuesta en la ACS URL mediante HTTP-POST.
7. Asignaciones: Asigna los usuarios o grupos que deben poder acceder a cside. Piénsalo con cuidado: cualquier persona que tu IdP deje pasar se agrega a tu organización.

Si el Name ID no puede ser una dirección de correo en tu IdP, cside recurre a un atributo de correo llamado email, mail, emailAddress, urn:oid:0.9.2342.19200300.100.1.3 o al claim http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress.

Obtener los datos necesarios

Necesitarás los metadatos SAML de tu IdP. Todos los IdP los ofrecen en una de dos formas:

1. Metadata URL: Un enlace público https:// al XML de metadatos (preferido)
2. Metadata XML: Un documento de metadatos descargable

cside lee tres cosas de los metadatos: el entity ID del IdP, la URL de inicio de sesión único HTTP-Redirect y los certificados de firma. No los introduces a mano.

Configurar SSO en cside

1. Ve al panel de cside y abre la sección SAML 2.0 como se describe en Navegar a la configuración de SSO.
2. Completa los campos requeridos:
   • Email domain: El dominio de correo electrónico de tu empresa (por ejemplo, example.com). Separa varios dominios con comas. Un dominio solo puede ser reclamado por una configuración de SSO, en todas las organizaciones de cside.
   • Metadata URL o Paste metadata XML: Elige la fuente que coincida con lo que te dio tu IdP y pega la URL en Identity provider metadata URL o el documento en Identity provider metadata XML.
3. Haz clic en Save SAML configuration.

cside descarga o analiza los metadatos, los comprueba y guarda la configuración. La URL de metadatos debe usar https://, ser accesible públicamente, devolver el documento directamente sin redirecciones y pesar menos de 512 KB.

Una vez guardada, la sección muestra el entity ID del Identity provider, la Sign-on URL y el número de Active signing certificates, junto con dos botones adicionales:

• Refresh certificates: Vuelve a leer la URL de metadatos y reemplaza los certificados de firma guardados. Solo se muestra en configuraciones creadas a partir de una URL de metadatos.
• Remove SAML: Elimina la configuración. Los usuarios de los dominios configurados vuelven al inicio de sesión con contraseña.

Probar tu configuración

No hay una ventana de verificación separada para SAML: al guardar la configuración, esta se activa de inmediato. Pruébala antes de avisar a tu equipo:

1. Abriendo una nueva ventana de navegador en modo incógnito/privado
2. Navegando a dash.cside.com
3. Ingresando una dirección de correo electrónico con tu dominio configurado
4. Deberías ser redirigido a tu proveedor de identidad para autenticarte y volver al panel de cside con la sesión iniciada

Iniciar sesión desde el mosaico de la aplicación en tu IdP también funciona. cside no acepta directamente la aserción no solicitada. Redirige al usuario a través de una solicitud iniciada por cside al mismo IdP, lo que normalmente se completa sin que el usuario lo note.

Rotar certificados de firma

cside acepta todos los certificados de firma listados en tus metadatos, así que puedes publicar el certificado nuevo junto al antiguo, cambiar tu IdP y retirar el antiguo sin interrupciones:

• Metadata URL: Haz clic en Refresh certificates en la sección SAML 2.0 después de cada cambio en tu IdP.
• XML pegado: Descarga los metadatos actualizados, pégalos en Identity provider metadata XML y haz clic en Save SAML configuration.

Resolución de problemas

Errores al guardar

Mensaje	Qué significa
SAML SSO is not enabled for this organization.	cside aún no ha habilitado SAML 2.0 para tu organización. Contacta a tu representante de cside.
The email domain ”…” is already used by an OIDC integration.	El dominio está reclamado por otra configuración de SSO, en tu organización o en otra. Elimínalo allí primero. Lo mismo aplica cuando el mensaje menciona una integración SAML.
This identity provider is already configured by another organization.	El entity ID de los metadatos pertenece a un IdP que otra organización de cside ya usa. Comprueba que pegaste tus propios metadatos.
This metadata has no entityID.	El documento no es un archivo de metadatos de IdP completo. Copia el EntityDescriptor completo.
This metadata has no HTTP-Redirect single sign-on URL.	Tu IdP solo anuncia un endpoint HTTP-POST. Habilita el binding HTTP-Redirect para la aplicación.
This metadata has no signing certificate.	A los metadatos les falta un KeyDescriptor de firma. Habilita la firma de aserciones y descarga los metadatos de nuevo.
The single sign-on URL must use https.	El endpoint de inicio de sesión de tu IdP se sirve por HTTP sin cifrar.
The metadata URL redirects.	Apunta el campo al documento de metadatos final, no a un enlace que redirige.
The metadata URL returned 404.	El enlace es incorrecto o los metadatos requieren autenticación. Cualquier estado distinto de 200 se reporta de esta forma.
Could not reach the metadata URL. / The metadata URL timed out.	Los servidores de cside no pueden alcanzar la URL en 10 segundos. Comprueba que sea pública.
The metadata URL must resolve to a public address.	El nombre de host apunta a una IP privada o interna. Usa la opción de XML pegado para un IdP interno.
The metadata document is too large.	El documento supera los 512 KB. Recorta descriptores no relacionados o usa la opción de XML pegado.
This SAML integration was configured with pasted metadata, so there is no URL to refresh from.	Refresh certificates solo funciona en configuraciones basadas en URL. Pega el XML actualizado en su lugar.

Errores al iniciar sesión

Mensaje	Qué significa
Unknown SAML identity provider	El emisor de la respuesta SAML no coincide con ninguna integración configurada, o SAML SSO se ha deshabilitado para la organización. Confirma que los metadatos del IdP en cside están actualizados.
This sign-in request could not be verified.	cside rechazó la aserción. La razón exacta se guarda en los registros de cside, así que revisa las causas indicadas abajo.
Signing in with SAML is not yet available for accounts whose only two-factor method is a security key.	La cuenta solo tiene una llave de seguridad registrada para MFA. Inicia sesión desde la página de inicio de sesión de cside o agrega una aplicación de autenticación.
This email is not enrolled for cside SAML SSO	El dominio de correo no está en una configuración SAML, o SAML SSO está deshabilitado para la organización.

Causas comunes de This sign-in request could not be verified:

• La aserción no está firmada, o solo está firmado el sobre de la respuesta
• La aserción está cifrada
• El Audience de la aserción no es https://cside.dev/saml/sp
• El Destination no es la ACS URL que se muestra en cside
• El IdP firmó con un certificado que no está en los metadatos guardados (rota con Refresh certificates o pega el XML nuevo)
• La dirección de correo del usuario falta tanto en el Name ID como en los atributos de correo
• El dominio de correo del usuario no es uno de los dominios configurados
• El reloj del IdP está desfasado más de cinco minutos
• La misma respuesta se envió dos veces (las aserciones son de un solo uso)