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

```json
{ "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

- [Roles personalizados y gobernanza (RBAC)](/hc/ajuda/articles/administration-custom-roles-governanca-rbac-es)
- [Registros de auditoría](/hc/ajuda/articles/administration-auditoria-es)
- [Inicio de sesión, perfil y verificación en dos pasos (2FA)](/hc/ajuda/articles/getting-started-login-perfil-2fa-es)
- [Visión general de Administración](/hc/ajuda/articles/administration-overview-es)