> ## Documentation Index
> Fetch the complete documentation index at: https://ai-kb.automationanywhere.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Solución de Problemas y Referencia de SSO

> Permisos, URLs de referencia rápida y orientación de solución de problemas para SAML SSO en su instancia on-premise de EKB.

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](/super-admin/sso/saml-sso-metadata-setup-guide).

## 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ón                                                                                   | Rol Requerido                                                                                           |
| ---------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------- |
| Ver la pestaña SSO Metadata                                                              | Super 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                                                                                             |

<Note>
  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.
</Note>

## Referencia Rápida

<CardGroup cols={2}>
  <Card title="Host de Backend" icon="server">
    `<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.**
  </Card>

  <Card title="Host de Frontend" icon="globe">
    `<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.**
  </Card>

  <Card title="URL de Metadatos SP" icon="link">
    ```
    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.
  </Card>

  <Card title="URL ACS" icon="arrow-right-to-bracket">
    ```
    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.
  </Card>

  <Card title="Punto de Entrada SP-Initiated SSO" icon="right-to-bracket">
    ```
    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.
  </Card>

  <Card title="Formato NameID Requerido" icon="id-card">
    ```
    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.
  </Card>
</CardGroup>

### Variables de Entorno del Modo SSO de Frontend

| Variable                    | Descripción                                                                                                              |
| --------------------------- | ------------------------------------------------------------------------------------------------------------------------ |
| `VITE_ALLOW_ONLY_SSO_LOGIN` | `true` para SSO de un solo clic, `false` (predeterminado) para SSO con modal de correo electrónico.                      |
| `VITE_SSO_ENTERPRISE_ID`    | Solo 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

<AccordionGroup>
  <Accordion title="Error &#x22;Please enter a valid domain&#x22;">
    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.
  </Accordion>

  <Accordion title="Error &#x22;File must be an XML file&#x22;">
    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**.
  </Accordion>

  <Accordion title="Error &#x22;Content does not appear to be valid XML&#x22;">
    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.
  </Accordion>

  <Accordion title="El inicio de sesión tiene éxito con el IdP pero EKB rechaza la afirmación">
    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.
  </Accordion>

  <Accordion title="El usuario inicia sesión exitosamente pero se le deniega el acceso">
    Esto lo controla **Super Admin → Access Controls**, no la pestaña SSO Metadata. Consulte la guía [**Controles de Acceso SAML**](/super-admin/sa-access-controls) para detalles sobre `Allow Any New Users` vs `Restrict to SAML Metadata` y las [reglas de asignación automatizada de equipo/proyecto](/super-admin/sa-automated-management).
  </Accordion>

  <Accordion title="El SSO iniciado por el IdP no funciona">
    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.
  </Accordion>

  <Accordion title="El IdP se configuró con el host de frontend en lugar del host de backend">
    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.
  </Accordion>

  <Accordion title="El botón de SSO de un solo clic no hace nada (o muestra &#x22;Could not determine domain for SSO login&#x22;)">
    `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.
  </Accordion>

  <Accordion title="El botón de SSO de un solo clic redirige pero SSO falla en el backend">
    `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).
  </Accordion>

  <Accordion title="SSO con modal de correo electrónico muestra &#x22;Your organization is not configured for SSO login&#x22;">
    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.
  </Accordion>

  <Accordion title="Los usuarios completan SSO pero aterrizan en la página incorrecta o obtienen un error de redirección">
    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.
  </Accordion>
</AccordionGroup>