Saltar al contenido principal
Este artículo cubre permisos, valores de referencia rápida y soluciones a problemas comunes de SSO. Para instrucciones de configuración, consulte la Guía de Configuración de Metadatos SSO.

​
Permisos

Todas las acciones de administración de metadatos SSO están restringidas a Super Admins, con una excepción: un administrador de equipo puede subir metadatos del IdP a través de archivo para el dominio de su propio equipo.
AcciónRol Requerido
Ver la pestaña SSO MetadataSuper Admin
Subir metadatos del IdP a través de archivo (POST /admin/saml-metadata/upload)Super Admin, o un administrador de equipo cuyo sso_domain coincida con el email_domain de su equipo
Subir metadatos del IdP a través de XML pegado (POST /admin/saml-metadata/upload-text)Solo Super Admin
Descargar metadatos almacenados (GET /admin/saml-metadata/download)Super Admin
Eliminar metadatos almacenados (DELETE /admin/saml-metadata/delete)Super Admin
El endpoint de metadatos SP en /saml/well-known/sp-metadata es público por diseño. No contiene secretos — solo el Entity ID SP, URL ACS, formato NameID y certificado de firma público.

​
Referencia Rápida

Host de Backend

<su-host-de-backend> (por ejemplo, ek-api.corp.acme.com)Maneja todo el tráfico SAML — metadatos SP, inicio de SSO y el endpoint ACS. Este es el único host que su IdP necesita conocer.

Host de Frontend

<su-host-de-frontend> (por ejemplo, ek.corp.acme.com)La interfaz web que abren sus usuarios. Configurado en el backend a través de FRONTEND_ROOT_URL. Nunca aparece en la configuración del IdP.

URL de Metadatos SP

https://<su-host-de-backend>/saml/well-known/sp-metadata
Comparta esto con el administrador de su IdP para registrar EKB como una aplicación SAML.

URL ACS

https://<su-host-de-backend>/user/generic/sso/saml/acs/admin
Donde su IdP envía por POST las respuestas SAML. Siempre el host de backend — nunca el frontend.

Punto de Entrada SP-Initiated SSO

https://<su-host-de-backend>/sso/login?enterprise_id=<dominio-email>
El endpoint del backend al que redirige el frontend cuando un usuario inicia SSO.

Formato NameID Requerido

urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress
Su IdP debe enviar la dirección de correo electrónico del usuario en este formato.

​
Variables de Entorno del Modo SSO de Frontend

VariableDescripción
VITE_ALLOW_ONLY_SSO_LOGINtrue para SSO de un solo clic, false (predeterminado) para SSO con modal de correo electrónico.
VITE_SSO_ENTERPRISE_IDSolo modo de un solo clic. Debe coincidir con un dominio que tenga metadatos del IdP subidos en la pestaña SSO Metadata.
  • ¿Dónde subir metadatos del IdP? Panel de Super Admin → pestaña SSO Metadata → Add Metadata / Update
  • Un documento por dominio. Re-subir reemplaza los metadatos existentes. Eliminar deshabilita SSO para ese dominio.
  • ¿Rol requerido? Super Admin para todas las acciones, excepto que los administradores de equipo pueden subir a través de archivo para el dominio de su propio equipo.

​
Solución de Problemas

El campo SSO Team Email Domain espera un dominio desnudo como acme.com o eu.acme.co.uk. Elimine cualquier @, https://, rutas o números de puerto antes de enviar.
El cargador de archivos solo acepta archivos con extensión .xml. Si su IdP proporcionó los metadatos como un archivo .txt o sin extensión, renómbralo a .xml o cambie a la opción Paste XML Content.
Al usar Paste XML Content, el contenido pegado debe comenzar con <?xml o < después de recortar espacios en blanco. Asegúrese de haber copiado el documento de metadatos completo y de que no se incluyó preámbulo ni comentario.
Casi siempre es causado por uno de los siguientes:
  • Desajuste de certificado — el certificado de firma del IdP en los metadatos subidos ya no coincide con el certificado que su IdP está usando realmente. Esto típicamente sucede después de una rotación de certificado del IdP. Obtenga metadatos nuevos del administrador de su IdP y use Update.
  • Formato NameID incorrecto — el IdP no está enviando la dirección de correo electrónico como el NameID. Confirme que el formato esté establecido a urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress del lado del IdP.
  • Desajuste de Entity ID — la audiencia o Entity ID configurada en su IdP no coincide con el Entity ID de su instancia de EKB. Vuelva a compartir el XML de metadatos SP de EKB y pida al administrador de su IdP que lo re-importe.
Esto lo controla Super Admin → Access Controls, no la pestaña SSO Metadata. Consulte la guía Controles de Acceso SAML para detalles sobre Allow Any New Users vs Restrict to SAML Metadata y las reglas de asignación automatizada de equipo/proyecto.
Por defecto, EKB solo acepta respuestas SAML iniciadas desde su propio endpoint /sso/login — lo que significa SSO iniciado por SP. Para habilitar SSO iniciado por IdP (no solicitado), el operador on-premite debe establecer ALLOW_IDP_INITIATED_SSO=true en el backend de EKB y reiniciar el servicio. Esta es una configuración a nivel de despliegue, no configurable en la pestaña SSO Metadata.
Si la aplicación del IdP se configuró con el hostname del frontend de EKB para la URL ACS o Entity ID, las respuestas SAML se enviarán al servicio incorrecto y la autenticación fallará silenciosamente — generalmente mostrando un 404 o una página de error genérica después de la pantalla de inicio de sesión del IdP.Pida al administrador de su IdP que confirme:
  • La URL ACS es https://<su-host-de-backend>/user/generic/sso/saml/acs/admin.
  • El Entity ID / Audience coincide con el entityID en https://<su-host-de-backend>/saml/well-known/sp-metadata.
El host de frontend nunca debería aparecer en la configuración de la aplicación SAML del IdP.
VITE_SSO_ENTERPRISE_ID no está establecido en el frontend. Establézcalo al dominio de correo electrónico para el que ha subido metadatos del IdP, luego vuelva a desplegar o reinicie el frontend para que el valor surta efecto.
VITE_SSO_ENTERPRISE_ID está establecido pero no coincide con ningún dominio con metadatos subidos en la pestaña SSO Metadata. Corrija esto ya sea:
  • Subiendo metadatos del IdP para el dominio actualmente en VITE_SSO_ENTERPRISE_ID — recomendado, ya que mantiene su configuración de frontend sin cambios.
  • Actualizando VITE_SSO_ENTERPRISE_ID para que coincida con un dominio que ya tenga metadatos subidos, luego volviendo a desplegar o reiniciando el frontend.
Los dos valores deben coincidir exactamente (sin distinción de mayúsculas/minúsculas).
El dominio de correo electrónico del usuario no tiene metadatos del IdP subidos en la pestaña SSO Metadata. Suba metadatos para ese dominio, o pida al usuario que inicie sesión usando correo electrónico/contraseña o OAuth.
Después de una respuesta SAML exitosa, EKB redirige al usuario a la URL del frontend definida por FRONTEND_ROOT_URL en el backend. Si esta variable no está establecida, apunta al host incorrecto o usa el esquema o puerto incorrecto, el usuario parecerá completar la autenticación pero terminará en una página rota.Pida a su operador on-premise que confirme que FRONTEND_ROOT_URL coincide exactamente con https://<su-host-de-frontend> — esquema correcto, puerto correcto, sin problemas de barra final.