1. A quién va dirigida esta guía
La plataforma Cyber Guru se integra con cualquier Identity Provider que soporte SAML 2.0. Para Microsoft Entra ID y Google Workspace existen guías específicas con capturas de pantalla de sus respectivas consolas:
Esta guía es para todos los demás casos: Okta, Microsoft ADFS, Shibboleth, Oracle, ForgeRock, IBM, AWS, WSO2, PingFederate o una solución desarrollada internamente.
No encontrarás capturas de pantalla: cada consola tiene su propia interfaz y las opciones pueden variar según la versión. En cambio, aquí tienes todo lo que tu Identity Provider debe hacer y los valores exactos a intercambiar, para que quien conozca tu sistema pueda configurarlo sin dudas.
| 💡 | La configuración de tu Identity Provider es responsabilidad de tu organización, ya sea con recursos internos o con el soporte del proveedor de la plataforma de identidad. Cyber Guru configura su parte y proporciona todos los valores necesarios. |
2. Cómo funciona la integración
Cyber Guru actúa como Service Provider (SP) y tu sistema como Identity Provider (IdP). Para que el protocolo funcione, ambos deben tener los componentes SAML 2.0 y configurar la confianza mutua (el llamado circle of trust) mediante el intercambio de metadatos.
El flujo previsto es SP-initiated: el usuario accede desde la dirección de la plataforma, es redirigido a tu Identity Provider para autenticarse y vuelve a la plataforma con una aserción SAML. (El acceso iniciado desde el portal del IdP — IdP-initiated — es posible pero requiere una configuración adicional: consulta Escenarios avanzados de SSO.)
3. Requisitos previos y decisiones antes de empezar
| Elemento | Quién lo proporciona | Notas |
|---|---|---|
| Identity Provider con soporte SAML 2.0 | Cliente | No se admiten otros protocolos. |
| Privilegios administrativos en el IdP | Cliente | Es necesario poder crear una nueva aplicación/relying party y definir los atributos que se envían. |
Campo a usar como username
|
Cliente |
La decisión más importante de la configuración. Debe ser un atributo inmutable: es la clave con la que la plataforma reconoce al usuario y no puede modificarse una vez iniciado el proyecto. En Active Directory suele ser el ObjectGUID; en otros sistemas, un identificador equivalente (por ejemplo, un número de empleado). Evita email y UPN si pueden cambiar con el tiempo. |
| Atributos obligatorios presentes en los perfiles | Cliente | Son cuatro: username, email, firstName, lastName. |
| Organizaciones a enviar | Cliente + Cyber Guru | Opcionales, en la forma org_{NOMBRE_ORG}. Son necesarias si la empresa opera sin precarga o si alguna debe usarse como Team para estadísticas y gamificación. |
| Metadatos del IdP | Cliente | URL pública accesible desde internet, o archivo XML. |
| Política de acceso a la aplicación | Cliente | Usa un grupo dedicado: solo los usuarios autorizados a la aplicación podrán acceder. |
| Modo de carga de usuarios | Cliente + Cyber Guru | Con precarga (recomendado) o sin ella: consulta Procedimiento general SSO. |
| Usuarios de prueba | Cliente | 2-3 usuarios para pruebas, autorizados en la aplicación. |
| Subdominio de la plataforma y metadatos SP | Cyber Guru | Se proporcionan tras el intercambio de información. |
4. Configuración paso a paso
Paso 1 — Crea la aplicación SAML en tu Identity Provider
Crea una nueva aplicación (según el sistema puede llamarse application, relying party trust, service provider, client) de tipo SAML 2.0. No uses plantillas de catálogo para otros productos: se necesita una integración genérica.
Paso 2 — Envía los metadatos del IdP a Cyber Guru
Envía a Cyber Guru la URL pública de los metadatos de tu Identity Provider (preferible) o el archivo XML de los metadatos.
Los metadatos deben contener: el entityID del IdP, el endpoint de Single Sign-On Service y el certificado público de firma.
| ⚠️ | Si tu Identity Provider solo es accesible desde la red interna, los metadatos igualmente deben estar disponibles en una URL pública o enviarse como archivo. Un endpoint no accesible desde internet no puede usarse para autenticar usuarios externos. |
Paso 3 — Recibe los metadatos SP de Cyber Guru y configura la aplicación
Cyber Guru completa la configuración de su lado y te envía la URL de los metadatos SP. Si tu sistema permite la importación automática de metadatos, úsala: es la forma más segura. Si no, abre la URL en un navegador y extrae los valores del archivo XML:
| Valor a configurar | Dónde encontrarlo en el archivo XML de metadatos SP |
|---|---|
| Entity ID (audience / identificador SP) | atributo entityID del elemento raíz <md:EntityDescriptor>
|
| ACS URL (Assertion Consumer Service, reply URL, destination) | atributo Location del elemento <md:AssertionConsumerService> con binding HTTP-POST |
| ⚠️ | Copia los valores de tu archivo de metadatos, carácter por carácter. No los reconstruyas manualmente ni los copies de otras guías o configuraciones de otras organizaciones: la dirección depende del entorno donde está alojada tu empresa. |
Paso 4 — Requisitos técnicos de la aserción
| Parámetro | Valor requerido |
|---|---|
| Versión del protocolo | SAML 2.0 |
| Binding de la respuesta | HTTP-POST hacia el ACS URL |
| Firma | La aserción (o la respuesta) debe estar firmada con la clave privada del IdP; el certificado público correspondiente debe estar en los metadatos enviados |
| Cifrado de la aserción | No requerido. Si tu IdP lo exige, avísalo antes de la configuración |
| Formato del Name ID | Configúralo según la indicación que recibas de Cyber Guru junto con los metadatos SP |
| Single Logout | Opcional. Si tu IdP realiza el logout con binding HTTP-POST, avísalo: requiere una configuración adicional en Cyber Guru |
Paso 5 — Configura los atributos enviados
La aserción debe contener cuatro atributos obligatorios, con estos nombres exactos:
| Nombre del atributo | Contenido |
|---|---|
username |
El identificador inmutable elegido en los requisitos previos |
email |
Dirección de correo electrónico del usuario |
firstName |
Nombre |
lastName |
Apellido |
Opcionales: locale (código de idioma ISO de dos letras minúsculas), country (código de país ISO de dos letras mayúsculas) y las organizaciones en la forma org_{NOMBRE_ORG}.
| 🛑 |
Dos reglas que aplican en cualquier Identity Provider: 1. Los nombres de los atributos distinguen entre mayúsculas y minúsculas. firstName y lastName deben escribirse exactamente así, en camelCase.2. Los nombres no deben tener prefijos de namespace. Muchos Identity Provider — especialmente ADFS y Microsoft Entra ID — envían los atributos con un prefijo como http://schemas.xmlsoap.org/ws/2005/05/identity/claims: ese prefijo debe eliminarse, de lo contrario el atributo no será reconocido. |
La referencia completa sobre los atributos — obligatorios, opcionales, organizaciones y Team, frecuencia de actualización — está en Atributos Identity Provider SSO. Los atributos que no estén en esa lista deben acordarse previamente con Cyber Guru.
Un ejemplo de cómo debe llegar la parte de atributos de la aserción:
<saml2:AttributeStatement>
<saml2:Attribute Name="username">
<saml2:AttributeValue>a1b2c3d4-0000-1111-2222-33445566778</saml2:AttributeValue>
</saml2:Attribute>
<saml2:Attribute Name="email">
<saml2:AttributeValue>mario.rossi@esempio.it</saml2:AttributeValue>
</saml2:Attribute>
<saml2:Attribute Name="firstName">
<saml2:AttributeValue>Mario</saml2:AttributeValue>
</saml2:Attribute>
<saml2:Attribute Name="lastName">
<saml2:AttributeValue>Rossi</saml2:AttributeValue>
</saml2:Attribute>
</saml2:AttributeStatement>Paso 6 — Autoriza a los usuarios
Asigna a la aplicación el grupo que contiene los usuarios autorizados. Quien no esté autorizado en la aplicación recibirá un error al intentar acceder, aunque todo lo demás esté correctamente configurado. Para las pruebas, autoriza solo los usuarios de test.
Paso 7 — Documenta la configuración
Guarda los valores introducidos (Entity ID, ACS URL, nombres de los atributos, grupo autorizado) y el archivo de metadatos: los necesitarás para la renovación del certificado.
5. Pruebas y confirmación
- Verifica que el usuario de prueba esté autorizado en la aplicación en el Identity Provider.
- Si la empresa está configurada con precarga, comprueba que ese usuario ya esté presente en la plataforma con el mismo username que el valor enviado en el atributo
username. Si no está precargado, el acceso será rechazado. - Abre una ventana del navegador en modo incógnito.
- Ve a
https://<subdominio>.platform.cyberguru.euy haz clic en el botón de acceso SSO. - Autentícate en tu Identity Provider: si todo funciona, llegarás a la página de bienvenida de Cyber Guru sin tener que introducir más credenciales.
- Verifica en la plataforma que el nombre, apellido y correo electrónico sean correctos: si están vacíos o incorrectos, el problema está en los atributos enviados.
6. Si algo no funciona
La primera herramienta es un SAML tracer en el navegador: captura la respuesta SAML y verifica los nombres exactos de los atributos (incluyendo mayúsculas), la ausencia de prefijos de namespace, el valor de username y la presencia de los cuatro atributos obligatorios.
Luego, comprueba que el Entity ID y el ACS URL configurados coincidan carácter por carácter con los de los metadatos SP, y que el usuario esté autorizado en la aplicación.
Los mensajes de error más comunes, con su causa y solución, están recopilados en Preguntas frecuentes sobre SSO (FAQ).
Si el problema persiste, contacta con el soporte de Cyber Guru proporcionando: mensaje de error completo, hora del intento, username del usuario afectado, subdominio de la empresa y, si es posible, los archivos SamlRequest.xml y SamlResponse.xml.
7. Después del go-live: mantenimiento
Después de la configuración, los metadatos deben considerarse fijos. Si cambian — renovación del certificado de firma, nuevos endpoints, nueva aplicación, sustitución del Identity Provider — no los modifiques por tu cuenta: abre una solicitud al soporte de Cyber Guru, que coordinará la actualización en ambos lados. Lo mismo aplica para cambios de email, UPN o dominio de los usuarios, que pueden interrumpir la asociación con las cuentas en la plataforma.
Los procedimientos están en Mantenimiento SSO: renovación de certificado y cambio de username/email.