Centro de Ayuda ConversaLabs
es
Idioma
pt_BR Portuguese (Brazil) en English es Spanish

Inicio de sesión único (SSO) con SAML

Abrir en
Ver como Markdown Abrir en ChatGPT Abrir en Claude

Conversa Labs

Última actualización el 7 de sep de 2026

Visión general

El inicio de sesión único (SSO) con SAML permite que los agentes accedan a ConversaLabs usando el proveedor de identidad (IdP) de tu empresa — como Okta, Azure AD / Microsoft Entra o Google Workspace. En lugar de que cada persona mantenga una contraseña aparte en la plataforma, la autenticación se delega al IdP: tu directorio corporativo controla quién entra y quién pierde el acceso.

Es una función premium (habilitada por plan y por tipo de instalación — Cloud o Enterprise) y se encuentra en Configuración > Seguridad.

Requisitos previos

  • Perfil de Administrador para configurar el SSO.
  • Un plan con la función SAML habilitada para la cuenta (premium/opcional). Si no está activa, el área de Seguridad muestra un aviso de no disponibilidad o una pantalla de actualización.
  • Tipo de instalación Cloud o Enterprise (el SSO con SAML no aparece en otros tipos).
  • El método de inicio de sesión SAML habilitado para la cuenta (forma parte de la configuración de la plataforma).
  • Un IdP compatible con SAML 2.0 (Okta, Azure AD / Entra, Google Workspace o equivalente) donde puedas registrar ConversaLabs como aplicación de servicio.

Paso a paso

  1. Abre Configuración > Seguridad.
  2. Activa el SSO con SAML con el interruptor de la sección (la función llega como Beta).
  3. Completa los campos con los datos de tu IdP:
    • SSO URL — la URL de inicio de sesión (sign-on) del IdP.
    • Entity ID del IdP — el identificador (Entity ID / Issuer) de tu proveedor.
    • Certificado — el certificado público X.509 del IdP (pega su contenido en el campo).
  4. Guarda. La plataforma valida los datos y luego muestra los valores del lado del servicio (ver Valores del proveedor de servicio (SP) más abajo).
  5. En tu IdP, registra ConversaLabs como aplicación usando la ACS URL y el SP Entity ID que se muestran en la pantalla, y otorga acceso a los agentes que deban usarlo.

Flujo de inicio de sesión (cómo entran los agentes vía IdP)

Con el SSO activo, la pantalla de inicio de sesión ofrece el acceso vía SAML. Al elegir esa opción, el agente es llevado al IdP, se autentica allí (con las políticas y el segundo factor de la empresa) y vuelve a la plataforma ya autenticado. En el primer acceso de un agente nuevo, la cuenta se aprovisiona automáticamente a partir de los atributos que envía el IdP.

Configuración y opciones

  • Interruptor de activación — enciende o apaga el SSO con SAML. Apagarlo (o borrar los campos y guardar) elimina la configuración SAML de la cuenta.
  • SSO URL, Entity ID del IdP y Certificado — los tres campos obligatorios que describen tu proveedor de identidad.

Mapeo de atributos y roles

Para aprovisionar al agente correctamente, el IdP debe enviar los atributos que la plataforma espera:

  • email
  • first_name
  • last_name

La sección Mapeo de atributos (desplegable) en la pantalla de Seguridad lista estos atributos. Configura tu IdP para enviarlos en la aserción SAML. La asociación de roles/funciones (qué rol recibe el agente al entrar) la gestiona la gobernanza de acceso de la cuenta — combina el SSO con roles bien definidos para controlar qué puede ver y hacer cada persona.

Un usuario solo puede pertenecer a una cuenta

Con SAML activo, la plataforma exige que cada persona exista en una sola cuenta. La regla aplica en los dos sentidos:

  • En la invitación. Invitar un correo que ya pertenece a otra cuenta se rechaza con el mensaje "No se pueden agregar usuarios asociados a otra cuenta mientras SAML esté habilitado". El agente no se crea.
  • En el inicio de sesión. Si la persona pertenece a esta cuenta y también a otra, la entrada vía IdP falla con "Autenticación fallida. Por favor, verifique sus credenciales e inténtelo de nuevo."

El motivo es la identidad: una persona en varias cuentas tendría un único registro de inicio de sesión, y el método de autenticación se guarda en ese registro — no puede ser SAML en una cuenta y contraseña en otra al mismo tiempo.

Por la misma razón, al activar SAML la plataforma convierte al método SAML solo a los usuarios que pertenecen únicamente a esta cuenta; quien también está en otra cuenta conserva el inicio de sesión con correo y contraseña. Al eliminar la configuración SAML, el camino de vuelta es simétrico: el método regresa a correo, excepto para quien todavía tiene SAML activo en otra cuenta. Un agente creado mientras SAML está activo nace ya en el método SAML.

Mapeo de grupos a funciones (role_mappings)

Además de los tres atributos de identidad, la configuración acepta un mapa de grupo del IdP → función. Los grupos se leen de la aserción en los atributos groups, Group o memberOf — el primero que exista. El primer grupo con mapeo definido gana, y puede apuntar a:

  • una función predeterminada (administrator o agent); o
  • un custom role — pero esa rama solo se aplica si la función Custom Roles está habilitada en la cuenta (consulta Funciones y Accesos y gobernanza).

Sin mapa, o sin grupo coincidente, el agente entra como Agente.

El mapa no tiene un campo propio en la pantalla de Seguridad — se guarda por la API, en el campo role_mappings de la configuración de SAML:

{ "Administrators": { "role": "administrator" }, "Soporte": { "custom_role_id": 7 } }

Atención: el formulario de la pantalla de Seguridad envía role_mappings vacío cada vez que alguien guarda. Si configuraste el mapa por la API y después alguien guarda la configuración desde la pantalla, el mapa se borra — vuelve a aplicarlo por la API.

Valores del proveedor de servicio (SP)

Después de guardar, la plataforma muestra los valores del lado del servicio (Service Provider) que tú informas a tu IdP:

  • ACS URL — la dirección a la que el IdP envía la respuesta SAML, con el formato https://<dirección de la plataforma>/omniauth/saml/callback?account_id=<id de la cuenta>. Se muestra siempre.
  • SP Entity ID — el identificador de ConversaLabs como aplicación en tu IdP.
  • Fingerprint — la huella SHA-1 del certificado, útil para verificación.

Dos llaves de disponibilidad

El formulario solo aparece cuando ambas están liberadas, y cada una tiene su propio mensaje:

  • La función saml en la cuenta — sin ella, la API responde 403 con "La función SAML no está habilitada para esta cuenta".
  • SSO vía SAML en la instalación (ENABLE_SAML_SSO_LOGIN, activado por defecto) — apagado, la API responde 403 con "El SSO de SAML no está habilitado en esta instalación". Esa llave es del operador de la instalación, no de la cuenta.

La comprobación de la instalación se ejecuta primero: con ambas apagadas, el mensaje que aparece es el de la instalación.

Casos de uso

  • Centralizar el acceso: la empresa controla los inicios de sesión y las bajas desde el directorio corporativo.
  • Reforzar la seguridad: aplicar las políticas de contraseña y el segundo factor (MFA) del propio IdP.
  • Alta/baja ágil: otorgar o revocar el acceso de un agente directamente en el IdP, sin tocar cuenta por cuenta en la plataforma.

Consejos, límites y buenas prácticas

  • Mantén el certificado del IdP actualizado — los certificados caducan y rompen el inicio de sesión cuando vencen.
  • Combina el SSO con roles bien definidos (RBAC) y con registros de auditoría para una gobernanza completa.
  • Prueba con un agente antes de exigir SAML a todo el equipo.

Disponibilidad y paywall

  • El SSO con SAML es premium: si no está en tu plan, el área de Seguridad muestra una pantalla de actualización (en Cloud, con un camino hacia la facturación) en lugar del formulario.
  • Disponible solo en instalaciones Cloud y Enterprise, y únicamente cuando el método de inicio de sesión SAML está habilitado para la cuenta.

Solución de problemas

  • El inicio de sesión falla o entra en bucle: revisa la SSO URL, el Entity ID del IdP y el Certificado — un valor que difiera entre la plataforma y el IdP impide la autenticación.

  • Falta el atributo de rol / agente sin permiso: comprueba que el IdP envía email, first_name y last_name, y revisa el rol asignado en la gobernanza de acceso.

  • Certificado caducado: genera un nuevo certificado en el IdP y actualiza el campo Certificado.

  • Usuario no aprovisionado: la cuenta se crea en el primer acceso solo si llegan los atributos esperados — confirma el mapeo de atributos en el IdP.

  • No veo la configuración de SAML: la función premium puede no estar habilitada, o la instalación no es Cloud/Enterprise, o el método de inicio de sesión SAML no está habilitado para la cuenta.

  • No puedo invitar a alguien que ya usa la plataforma en otra cuenta: es la regla de cuenta única de SAML. La persona debe salir de la otra cuenta antes de ser invitada, o dejas la invitación para después de apagar SAML.

  • El agente no puede restablecer su contraseña: esperado. Una cuenta de inicio de sesión en el método SAML recibe "Esta cuenta utiliza autenticación SAML. El restablecimiento de contraseña no está disponible. Comuníquese con su administrador." La contraseña pasa a gestionarse en el IdP.

  • El inicio de sesión con correo y contraseña es rechazado: también esperado. La respuesta es "Esta cuenta utiliza autenticación SAML. Por favor, inicie sesión a través del proveedor SAML de su organización."

  • El certificado es rechazado al guardar: el campo exige un certificado X.509 válido en formato PEM. Pega el contenido completo, incluidas las líneas de inicio y fin.

  • Activé SAML y parte del equipo sigue entrando con contraseña: son las personas que también pertenecen a otra cuenta — quedan fuera de la conversión a propósito.

Ver también