Saltar al contenido principal
Iniciar sesión
Deutsch English (United States) Français Italiano

Guía para la configuración de SSO con un proveedor de identidad genérico (SAML 2.0)

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

  1. Verifica que el usuario de prueba esté autorizado en la aplicación en el Identity Provider.
  2. 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.
  3. Abre una ventana del navegador en modo incógnito.
  4. Ve a https://<subdominio>.platform.cyberguru.eu y haz clic en el botón de acceso SSO.
  5. Auténticate 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.
  6. 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.

8. Artículos relacionados

Artículos relacionados