1. A quién va dirigida esta guía
Esta guía te acompaña en la configuración del inicio de sesión único (SSO) entre Google Workspace y la plataforma Cyber Guru, utilizando el protocolo SAML 2.0. Al finalizar, tus usuarios accederán a Cyber Guru con sus credenciales de Google Workspace, sin necesidad de una contraseña específica.
Necesitas una cuenta con rol de Super Admin de Google Workspace, con acceso a la Consola de administración (https://admin.google.com).
En el texto, el interlocutor indicado como "Cyber Guru" es Cyber Guru o el partner que gestiona tu plataforma.
Esta guía también cubre el caso de autenticación SSO vía SAML 2.0 con mecanismo SP-Initiated (es decir, comenzando desde la URL); si necesitas configurar el acceso SSO desde la aplicación (IDP-Initiated), por favor contacta con soporte.
| 💡 | Las capturas de pantalla de esta guía muestran la Consola de administración de Google en inglés. Si tu consola está en español, encontrarás los nombres equivalentes indicados en el texto entre paréntesis. |
2. Índice
- Requisitos previos y decisiones a tomar antes de empezar
- Configuración paso a paso (pasos 1-5)
- Prueba y confirmación
- Si algo no funciona
- Después del go-live: mantenimiento
- Recursos adicionales
3. Requisitos previos y decisiones a tomar antes de empezar
Estos puntos deben aclararse antes de abrir la consola: la mayoría de los problemas de configuración surgen por una mala decisión en alguno de estos aspectos.
| Elemento | Quién lo proporciona | Notas |
|---|---|---|
| Cuenta Super Admin de Google Workspace | Cliente | Acceso a admin.google.com. |
| Protocolo | — | SAML 2.0. No se admiten otros protocolos. |
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. Si existe la posibilidad de que el Correo principal cambie (por cambio de apellido, migración de dominio), no lo uses: elige un campo estable como el ID de empleado. Ver §7. |
| Atributos obligatorios presentes en los perfiles | Cliente | Son cuatro: username, email, firstName, lastName. Si un campo está vacío en el perfil de Google, el atributo llegará vacío. |
| Organizaciones a enviar | Cliente + Cyber Guru | Opcionales, en la forma org_{NOMBRE_ORG} (sede, departamento, unidad organizativa…). Son necesarias si la empresa opera sin precarga o si alguna de ellas debe usarse como Equipo para estadísticas y gamificación. Más detalles en Atributos Identity Provider SSO. |
| Grupo de usuarios autorizados | Cliente | Usa un grupo dedicado en lugar de habilitar la app para toda la organización: solo los usuarios para quienes el servicio esté activo podrán acceder. |
| Modo de carga de usuarios | Cliente + Cyber Guru | Con precarga (recomendado) o sin ella. Lee Procedimiento General SSO antes de decidir. |
| Usuario de prueba | Cliente | Es útil disponer de un usuario de prueba para las verificaciones. |
| Subdominio de la plataforma | Cyber Guru | En la forma https://<subdominio>.platform.cyberguru.eu. |
4. Configuración paso a paso
Paso 1 — Accede a la Consola de administración de Google
Abre https://admin.google.com e inicia sesión con la cuenta de administrador.
Paso 2 — Descarga los metadatos IdP de Google y envíalos a Cyber Guru
En el menú de la izquierda selecciona Apps (Aplicaciones) → Web and mobile apps (Aplicaciones web y para dispositivos móviles).
Abre Settings (Configuración) → SAML certificates (Certificados SAML).
Se abrirá la página con los detalles del Proveedor de Identidad de Google.
Desplázate hasta el final de la página y haz clic en DOWNLOAD METADATA (DESCARGAR METADATOS).
Envía el archivo GoogleIDPMetadata.xml a Cyber Guru. Cyber Guru configurará su parte y te responderá con la URL de los metadatos SP (ver Paso 3.3).
Paso 3 — Crea la app SAML personalizada
Vuelve a Apps → Web and mobile apps.
Haz clic en Add app (Agregar aplicación) → Add custom SAML app (Agregar aplicación SAML personalizada).
3.1 — Detalles de la app. Completa App name (ej. Cyber Guru) y Description, luego haz clic en CONTINUE.
3.2 — Detalles IdP de Google. Esta pantalla muestra los mismos metadatos que ya enviaste en el Paso 2: no es necesario hacer nada, haz clic en CONTINUE.
3.3 — Detalles del Service Provider. Aquí debes introducir los valores tomados de los metadatos SP que recibiste de Cyber Guru.
La URL de los metadatos SP que recibes tiene este formato:
https://<host-login-cyberguru>/realms/<subdominio>/broker/saml/endpoint/descriptor
Ábrela en un navegador: los dos valores que debes copiar en el formulario se encuentran en el archivo XML.
| Campo Google | Dónde se encuentra en el archivo XML de metadatos SP |
|---|---|
| ACS URL | atributo Location del elemento <md:AssertionConsumerService> con binding HTTP-POST |
| Entity ID | atributo entityID del elemento raíz <md:EntityDescriptor>
|
| ⚠️ | 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. |
Completa ACS URL y Entity ID, configura el Name ID format según la indicación que recibas de Cyber Guru junto con los metadatos SP, deja Name ID con el valor predeterminado y haz clic en CONTINUE.
3.4 — Mapeo de atributos. Haz clic en ADD MAPPING (AGREGAR MAPEADO) y configura los cuatro claim requeridos por Cyber Guru.
| Atributo Google Directory | Nombre del atributo de la app | Notas |
|---|---|---|
| Campo inmutable elegido en los requisitos previos (ej. ID de empleado; Correo principal solo si nunca cambiará) | username |
Clave de asociación del usuario. |
| Correo principal | email |
|
| Nombre | firstName |
Obligatorio en camelCase. |
| Apellido | lastName |
Obligatorio en camelCase. |
| 🛑 |
Los nombres de los claim distinguen entre mayúsculas y minúsculas. firstName y lastName deben escribirse exactamente así (camelCase). Escribirlos como FirstName o firstname impedirá que la plataforma los reconozca. |
Mapeo de username:
Mapeo de firstName:
Mapeo de lastName:
Mapeo de email:
Si también necesitas las organizaciones (org_{NOMBRE_ORG}) o los atributos opcionales locale y country, en caso de que la cuenta se cree al iniciar sesión por SSO, añádelos siguiendo las mismas reglas. La referencia completa está en Atributos Identity Provider SSO.
Haz clic en FINISH al final de la página. La app está creada:
Paso 4 — Habilita la app para tus usuarios
En la vista general de la app, localiza el panel User access (Acceso de usuario).
Haz clic en OFF for everyone (DESACTIVADO para todos).
Selecciona Groups (Grupos) y elige el grupo que contiene a los usuarios autorizados.
Configura el Service status (Estado del servicio) en ON para ese grupo y haz clic en SAVE.
| ⚠️ | Para las pruebas, habilita un grupo reducido con 2-3 usuarios de prueba. Si un usuario no está incluido en un grupo con el servicio en ON, al iniciar sesión recibirá un error de servicio no habilitado aunque todo lo demás esté correctamente configurado. Los cambios de estado del servicio pueden tardar unos minutos en propagarse. |
Paso 5 — Documenta la configuración
Guarda en un lugar seguro el archivo de metadatos y los valores introducidos (ACS URL, Entity ID, mapeo de claim, grupo habilitado): los necesitarás para la renovación del certificado.
5. Prueba y confirmación
- Verifica que el usuario de prueba pertenezca a un grupo con Service status = ON.
- Si la empresa está configurada con precarga, verifica que ese usuario ya esté presente en la plataforma con el mismo username que el valor enviado en el claim
username. Si no está precargado, el acceso será rechazado. - Abre una ventana del navegador en modo incógnito.
- Ve a
https://<subdominio>.platform.cyberguru.eu - Haz clic en el botón de acceso SSO.
- Autentícate con las credenciales de Google Workspace: si todo funciona llegarás a la página de bienvenida de Cyber Guru.
Por último, verifica que el nombre, apellido y correo electrónico del usuario sean correctos en la plataforma: si están vacíos o incorrectos, el problema está en el mapeo de los claim.
6. Si algo no funciona
- Captura la respuesta SAML con un rastreador SAML y verifica los nombres exactos de los claim recibidos. Un ejemplo de respuesta correcta:
<saml2:AttributeStatement>
<saml2:Attribute Name="username">
<saml2:AttributeValue>mario.rossi@esempio.it</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>- Verifica la URL de ACS y el Entity ID: deben coincidir exactamente, carácter por carácter, con los del archivo de metadatos del SP.
- Verifica el estado del servicio para el grupo del usuario.
- Recuerda que los cambios en Google pueden tardar unos minutos en propagarse.
Los mensajes de error más comunes, junto 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, nombre de usuario del usuario afectado y, si es posible, los archivos SamlRequest.xml y SamlResponse.xml.
7. Después del go-live: mantenimiento
- Rotación del certificado SAML de Google: si generas un nuevo certificado en la sección SAML certificates, debes comunicarlo a Cyber Guru antes de activarlo.
- Cambios en los metadatos: deben permanecer sin cambios; cualquier modificación debe gestionarse con el soporte de Cyber Guru.
-
Cambios de correo principal o de dominio: si el correo se usa como
username, un cambio rompe la asociación con la cuenta en la plataforma y bloquea el acceso.
Los procedimientos están en Mantenimiento SSO: renovación de certificado y cambio de username/correo. Avisa a Cyber Guru antes de migraciones de dominio o cambios masivos.