Guía de Configuración de Metadatos SSO

Nota

Esta guía está escrita para administradores de TI e identidad que gestionan una instancia on-premise de EKB. Cualquier referencia a "su IdP", "su administrador del IdP" o "su dominio de correo electrónico" se refiere a la infraestructura de su propia organización — no a lo que gestione Automation Anywhere.

Esta guía acompaña a un Super Admin en el proceso de dos partes para habilitar SAML SSO para un dominio de correo electrónico: compartir los metadatos SP de EKB con su IdP, luego subir los metadatos de su IdP de vuelta a EKB.

¿No familiarizado con cómo funciona el SAML SSO de EKB internamente? Comience con la Vista General de SAML SSO.

Prerrequisitos

Antes de comenzar, confirme lo siguiente:

• Su implementación on-premise de EKB está ejecutándose con tanto el backend (<su-host-de-backend>) como el frontend (<su-host-de-frontend>) alcanzables desde el navegador del usuario. El IdP solo necesita recibir respuestas SAML HTTP-POST en <su-host-de-backend>/user/generic/sso/saml/acs/admin — no necesita conectividad de salida directa a su backend si proporciona los metadatos SP como un archivo descargado.
• Ha iniciado sesión en EKB como Super Admin. La pestaña SSO Metadata y todos sus endpoints subyacentes están restringidos a Super Admins.
• Su IdP es compatible con SAML 2.0 y puede consumir un XML/URL de metadatos SP, o configurarse manualmente con un Entity ID SP y una URL ACS.
• Su IdP está configurado para enviar la dirección de correo electrónico del usuario como el NameID SAML, usando el formato urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress. EKB usa el NameID para buscar o provisionar cuentas de usuario.
• Conoce el dominio de correo electrónico para el que desea habilitar SSO (por ejemplo, acme.com). SSO se basa en dominios, por lo que todos los usuarios que compartan ese dominio — alice@acme.com, bob@acme.com, etc. — serán enrutados al mismo IdP.
• Conoce qué modo SSO de frontend está ejecutando su implementación. Esto se controla con la variable de entorno VITE_ALLOW_ONLY_SSO_LOGIN en el frontend:
  • true — SSO de un solo clic. El dominio está codificado a través de VITE_SSO_ENTERPRISE_ID y debe coincidir exactamente con el dominio para el que sube metadatos.
  • false (predeterminado) — SSO con modal de correo electrónico. El dominio se deriva del correo electrónico del usuario al iniciar sesión. Múltiples dominios pueden tener cada uno sus propios metadatos subidos.

Parte 1 — Proporcionar Metadatos SP a su IdP

El administrador de su IdP necesita registrar EKB como una aplicación SAML en su IdP antes de que pueda subir metadatos del IdP. EKB hace esto sencillo publicando sus metadatos SP a través de un endpoint público y conocido — no se necesita copiar campos manualmente.

El Endpoint de Metadatos SP

El backend de EKB publica sus metadatos SP en:

https://<su-host-de-backend>/saml/well-known/sp-metadata

La respuesta es un EntityDescriptor SAML 2.0 compatible con estándares que contiene el Entity ID de su instancia, la URL ACS, el formato NameID requerido y el certificado de firma SP (cuando está configurado). El endpoint está sin autenticación por diseño para que su IdP pueda obtenerlo directamente.

Consejo

Para la referencia completa — comportamiento del endpoint, XML de ejemplo, componentes garantizados vs. opcionales, y las variables de entorno del backend (CUSTOM_ENTITY_ID_FOR_GENERIC_SSO, SAML_SP_CERT_FILE, SAML_SP_KEY_FILE) que un operador on-premise puede ajustar en el momento del despliegue — consulte Endpoint de Metadatos SP.

Cómo Compartir los Metadatos SP

Opción A — Proporcionar la URL

Si su IdP puede alcanzar el host de backend de EKB, envíe directamente al administrador de su IdP la URL conocida:

https://<su-host-de-backend>/saml/well-known/sp-metadata

La mayoría de los IdPs modernos (Okta, Entra ID, Ping, OneLogin, Auth0, etc.) pueden importar metadatos SP desde una URL y autocompletarán la configuración SP — Entity ID, URL ACS, formato NameID y certificado de firma — a partir de ella.

Opción B — Descargar y Entregar el Archivo

Si su IdP no puede alcanzar el host de backend directamente — común en redes segmentadas, entornos desconectados o cuando su IdP es un SaaS fuera de su perímetro corporativo — descargue el XML y páselo al administrador de su IdP por fuera de banda:

curl -o ek_sp_metadata.xml https://<su-host-de-backend>/saml/well-known/sp-metadata

El administrador de su IdP sube ek_sp_metadata.xml en la pantalla de configuración de la aplicación SAML del IdP. Solo necesita re-exportar y re-subir cuando cambia la configuración SP — típicamente un cambio de hostname de backend, rotación de certificado de firma SP o cambio en la anulación del Entity ID.

Configuración Manual (Cuando el IdP No Puede Consumir Metadatos)

Si su IdP requiere que se ingresen campos manualmente, use los valores del XML de metadatos SP. Los campos más comúnmente requeridos son:

Campo	Valor
Entity ID / Audience	El atributo entityID en <md:EntityDescriptor> en la respuesta de metadatos SP. Se predetermina a la URL ACS; puede ser anulado en el momento del despliegue a través de CUSTOM_ENTITY_ID_FOR_GENERIC_SSO.
ACS URL / Reply URL / Single Sign-On URL	https://<su-host-de-backend>/user/generic/sso/saml/acs/admin — siempre el host de backend, nunca el frontend.
Binding	HTTP-POST
NameID format	urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress
Sign AuthnRequests	true si su implementación de EKB tiene un certificado SP configurado (anunciado en los metadatos como AuthnRequestsSigned); de lo contrario, false.
Want Assertions Signed	true — siempre. EKB requiere afirmaciones firmadas.

aviso

El IdP debe enviar la dirección de correo electrónico del usuario como el NameID SAML. Si el IdP envía un ID interno opaco en su lugar, el inicio de sesión fallará o creará cuentas con clave incorrecta.

Lo Que el Administrador de su IdP Necesita Devolver

Una vez que se crea la aplicación SAML en su IdP, pida al administrador de su IdP el XML de metadatos del IdP SAML. Este es el archivo que subirá en la Parte 2.

Casi todos los IdPs pueden generar este archivo. Nombres comunes en las interfaces de los IdPs:

IdP	Dónde Encontrarlo
Okta	Enlace "Identity Provider metadata" en la pestaña Sign On de la aplicación
Entra ID / Azure AD	Descarga "Federation Metadata XML" bajo el blade de SSO
Ping / OneLogin / Auth0 / ADFS / Keycloak	Generalmente etiquetado como "Metadata" o "SAML Metadata", descargable como XML

El XML debe ser un EntityDescriptor SAML 2.0 válido que contenga un IDPSSODescriptor con al menos el entityID del IdP, una ubicación y enlazamiento de SingleSignOnService, y el certificado de firma del IdP para que EKB pueda verificar las afirmaciones.

Parte 2 — Subir los Metadatos del IdP

Con el XML de metadatos del IdP en mano, puede registrarlo contra un dominio de correo electrónico en su instancia de EKB.

Abrir la Pestaña SSO Metadata

1. Iniciar sesión en EKB

   Inicie sesión en EKB como Super Admin.

2. Abrir el Panel de Super Admin

   Vaya a su menú de cuenta en la esquina superior derecha y haga clic en Super Admin Dashboard.

3. Ir a la pestaña SSO Metadata

   Cambie a la pestaña SSO Metadata. Verá una tabla de mapeos existentes dominio → metadatos con tres columnas:

   • SSO Domain — el dominio de correo electrónico contra el que se registran los metadatos (por ejemplo, acme.com).
   • Updated — la última vez que se subieron o reemplazaron los metadatos para ese dominio.
   • Actions — controles para descargar, actualizar o eliminar los metadatos almacenados de esa fila.

   Use el cuadro de búsqueda en la esquina superior derecha para filtrar por dominio. La tabla es ordenable por SSO Domain o Updated.

Agregar Metadatos para un Nuevo Dominio

1. Abrir el diálogo Agregar Metadatos

   Haga clic en Add Metadata en la esquina superior derecha de la pestaña SSO Metadata. Si aún no hay dominios configurados, también puede hacer clic en él desde la tarjeta de estado vacío.
   

2. Ingresar el dominio de correo electrónico

   En el campo SSO Team Email Domain, ingrese el dominio al que debe aplicarse SSO — por ejemplo acme.com. Use solo la parte del dominio de la dirección de correo electrónico: sin @, sin ruta, sin esquema. El valor se normaliza a minúsculas al guardar.

   aviso

   Si su implementación ejecuta en modo SSO de un solo clic (VITE_ALLOW_ONLY_SSO_LOGIN=true), este valor debe coincidir exactamente con VITE_SSO_ENTERPRISE_ID. Un desajuste significa que el botón de SSO redirigirá a los usuarios a un dominio sin metadatos subidos, y la autenticación fallará en el backend.

3. Elija su método de subida y proporcione el XML
   Subir Archivo

   Seleccione el archivo .xml que proporcionó el administrador de su IdP. Solo se aceptan archivos con extensión .xml.

   Pegar Contenido XML

   Pegue el XML completo de metadatos del IdP directamente en el área de texto. El contenido debe comenzar con <?xml ...?> o <EntityDescriptor ...>.

4. Enviar

   Haga clic en Upload Metadata. El diálogo se cierra, una notificación toast confirma la subida, y el nuevo dominio aparece en la tabla.

Nota

Cada dominio puede tener como máximo un documento de metadatos del IdP activo a la vez. Re-subir para el mismo dominio reemplaza los metadatos existentes — vea Actualizar Metadatos para un Dominio Existente más adelante.

Actualizar Metadatos para un Dominio Existente

Los IdPs rotan certificados de firma y ocasionalmente cambian endpoints. Cuando esto suceda, coordine con el administrador de su IdP para que el nuevo XML se suba a EKB antes de que el IdP comience a firmar afirmaciones con la nueva clave.

1. Encontrar la fila del dominio

   Ubique el dominio en la tabla SSO Metadata.

2. Hacer clic en Update

   Haga clic en Update en la columna Actions de la fila.

3. Proporcionar el nuevo XML

   Se abre el diálogo Update SSO Metadata con el dominio pre-rellenado y bloqueado. No puede cambiar el dominio en una actualización — si necesita reutilizar la entrada, elimínela y vuelva a agregarla. Elija su método de subida y proporcione el nuevo XML como lo haría para un nuevo dominio.

4. Enviar

   Haga clic en Update Metadata. El reemplazo surte efecto inmediatamente — el próximo inicio de sesión SSO para ese dominio usará los nuevos metadatos.

Descargar los Metadatos Almacenados Actualmente

Haga clic en el icono de descarga en la columna Actions de la fila. El archivo se guarda como <dominio>_saml_metadata.xml.

Útil para:

• Confirmar qué metadatos del IdP están actualmente activos en esta instancia de EKB.
• Proporcionar una copia a su equipo de seguridad o cumplimiento para auditoría.
• Realizar una copia de seguridad antes de realizar una actualización.

Eliminar Metadatos para un Dominio

1. Hacer clic en Delete

   Haga clic en Delete en la columna Actions de la fila.

2. Confirmar

   En el diálogo de confirmación, lea la advertencia, marque la casilla de verificación de aceptación — "I understand this will disable SSO for all users in this domain" — y haga clic en Delete.

Peligro

La eliminación es irreversible. Después de eliminar:

• EKB ya no tiene metadatos del IdP en archivo para ese dominio.
• Cualquier nuevo intento de inicio de sesión SSO de usuarios @<dominio> fallará.
• Las cuentas existentes — correo electrónico/contraseña, Google OAuth o cuentas provisionadas por inicios de sesión SSO anteriores — no se eliminan, pero esos usuarios ya no podrán iniciar sesión a través de SSO.

Para restaurar SSO para el dominio, necesitará subir el XML de metadatos del IdP nuevamente.

Lista de Verificación de Extremo a Extremo

Use esto como libro de operaciones al habilitar SAML SSO para un nuevo dominio de correo electrónico en su instancia on-premise de EKB.

1. Compartir los metadatos SP de EKB con el administrador de su IdP

   Proporcione al administrador de su IdP los metadatos SP del backend de EKB — no del host de frontend.

   • Si su IdP puede alcanzar el backend directamente, diríjalos a:

     https://<su-host-de-backend>/saml/well-known/sp-metadata

   • De lo contrario, descargue el XML y páselo por fuera de banda:

     curl -o ek_sp_metadata.xml https://<su-host-de-backend>/saml/well-known/sp-metadata

2. El administrador de su IdP crea la aplicación SAML

   Una vez que tenga los metadatos SP, el administrador de su IdP registra EKB como una aplicación SAML en su IdP. Confirme con ellos que:

   • El NameID está establecido a la dirección de correo electrónico del usuario.
   • Las afirmaciones están firmadas.
   • La audiencia / Entity ID coincide con el valor en los metadatos SP de EKB.
3. Recibir el XML de metadatos del IdP

   Pida al administrador de su IdP el XML de metadatos del IdP una vez que se haya creado la aplicación. Este es el archivo que subirá en el siguiente paso.

4. Subir los metadatos del IdP a EKB

   Inicie sesión en EKB como Super Admin, abra Super Admin Dashboard → SSO Metadata y haga clic en Add Metadata. Ingrese el dominio de correo electrónico y suba el XML.

5. Probar el inicio de sesión

   Pruebe con un usuario real @<dominio>. Si el usuario se autentica exitosamente pero se le deniega el acceso, verifique su configuración de Controles de Acceso SAML — consulte la guía Controles de Acceso SAML.

6. Documentar el cambio

   Registre lo siguiente en su sistema interno de gestión de cambios: el dominio, el tipo de IdP, la fecha de subida y qué Super Admin realizó la subida.

7. Programar una actualización de metadatos

   Anote cuándo vence el certificado de firma de su IdP y establezca un recordatorio para subir metadatos actualizados antes de esa fecha. Use la acción Update en la pestaña SSO Metadata cuando haya nuevos metadatos disponibles.

---

¿Tiene problemas? Consulte la guía Solución de Problemas y Referencia de SSO.