1. Who this guide is for
This guide walks you through setting up Single Sign-On (SSO) between Google Workspace and the Cyber Guru platform using the SAML 2.0 protocol. When you're done, your users will log in to Cyber Guru with their Google Workspace credentials, without needing a separate password.
You need a Super Admin Google Workspace account with access to the Admin Console (https://admin.google.com).
In this guide, "Cyber Guru" refers to Cyber Guru or the partner managing your platform.
This guide also covers SSO authentication via SAML 2.0 using the SP-Initiated method (starting from the URL). If you need to set up SSO access via application (IDP-Initiated), please contact support.
| 💡 | The screenshots in this guide show the Google Admin Console in English. If your console is in Italian, you'll find the corresponding labels in parentheses in the text. |
2. Table of Contents
- Prerequisites and decisions to make before you start
- Step-by-step configuration (steps 1-5)
- Testing and confirmation
- If something doesn't work
- After go-live: maintenance
- Additional resources
3. Prerequisites and decisions to make before you start
Make sure you clarify these points before opening the console: most configuration issues come from making the wrong choice here.
| Item | Who provides it | Notes |
|---|---|---|
| Google Workspace Super Admin account | Customer | Access to admin.google.com. |
| Protocol | — | SAML 2.0. Other protocols are not supported. |
Field to use as username
|
Customer | The most important decision in the setup. It must be an immutable attribute: this is the key the platform uses to identify the user and it cannot be changed after the project starts. If there's a chance the Primary Email might change (name change, domain migration), do not use it: choose a stable field like Employee ID. See §7. |
| Required attributes set on profiles | Customer | There are four: username, email, firstName, lastName. If a field is empty in the Google profile, the attribute will be empty. |
| Organizations to send | Customer + Cyber Guru | Optional, in the format org_{ORG_NAME} (location, department, organizational unit, etc.). Needed if the company operates without preloading or if one of them needs to be used as a Team for stats and gamification. Details in SSO Identity Provider Attributes. |
| Group of authorized users | Customer | Use a dedicated group instead of enabling the app for the whole organization: only users with the service enabled will be able to access. |
| User population method | Customer + Cyber Guru | With preloading (recommended) or without. Read General SSO Procedure before choosing. |
| Test user | Customer | It's helpful to provide a test account for verification. |
| Platform subdomain | Cyber Guru | In the format https://<subdomain>.platform.cyberguru.eu. |
4. Step-by-step configuration
Step 1 — Log in to the Google Admin Console
Go to https://admin.google.com and log in with your admin account.
Step 2 — Download Google IdP metadata and send it to Cyber Guru
In the left menu, select Apps (App) → Web and mobile apps (App web e per dispositivi mobili).
Open Settings (Impostazioni) → SAML certificates (Certificati SAML).
This opens the page with the Google Identity Provider details.
Scroll to the bottom of the page and click DOWNLOAD METADATA (SCARICA METADATI).
Send the GoogleIDPMetadata.xml file to Cyber Guru. Cyber Guru will configure their side and reply with the SP metadata URL (see Step 3.3).
Step 3 — Create the custom SAML app
Go back to Apps → Web and mobile apps.
Click Add app (Aggiungi app) → Add custom SAML app (Aggiungi app SAML personalizzata).
3.1 — App details. Fill in App name (e.g., Cyber Guru) and Description, then click CONTINUE.
3.2 — Google IdP details. This screen shows the same metadata you already sent in Step 2: you don't need to do anything, just click CONTINUE.
3.3 — Service Provider details. Here, enter the values from the SP metadata you received from Cyber Guru.
The SP metadata URL you receive will look like this:
https://<host-login-cyberguru>/realms/<subdomain>/broker/saml/endpoint/descriptor
Open it in a browser: the two values you need for the form are in the XML file.
| Google field | Where to find it in the SP metadata XML file |
|---|---|
| ACS URL |
Location attribute of the <md:AssertionConsumerService> element with HTTP-POST binding |
| Entity ID |
entityID attribute of the root <md:EntityDescriptor> element
|
| ⚠️ | Copy the values from your metadata file, character by character. Do not try to build them manually or copy them from other guides or other organizations' setups: the address depends on the environment where your company is hosted. |
Fill in ACS URL and Entity ID, set the Name ID format as instructed by Cyber Guru along with the SP metadata, leave Name ID at its default value, and click CONTINUE.
3.4 — Attribute mapping. Click ADD MAPPING (AGGIUNGI MAPPATURA) and set up the four claims required by Cyber Guru.
| Google Directory attribute | App attribute name | Notes |
|---|---|---|
| Immutable field chosen in prerequisites (e.g., Employee ID; Primary email only if it will never change) | username |
User association key. |
| Primary email | email |
|
| First name | firstName |
Must use camelCase. |
| Last name | lastName |
Must use camelCase. |
| 🛑 |
Claim names are case-sensitive. firstName and lastName must be written exactly like this (camelCase). Writing them as FirstName or firstname will prevent the platform from recognizing them. |
Mapping for username:
Mapping for firstName:
Mapping for lastName:
Mapping for email:
If you also need organizations (org_{ORG_NAME}) or the optional attributes locale and country, if the user is created at the same time as SSO login, add them using the same rules. The full reference is at SSO Identity Provider Attributes.
Click FINISH at the bottom of the page. The app is now created:
Step 4 — Enable the app for your users
In the app overview, find the User access panel (Accesso utente).
Click OFF for everyone (OFF per tutti).
Select Groups (Gruppi) and choose the group containing the authorized users.
Set the Service status (Stato del servizio) to ON for that group and click SAVE.
| ⚠️ | For testing, enable a small group with 2-3 test users. If a user is not in a group with the service set to ON, they will get a "service not enabled" error at login even if everything else is set up correctly. Service status changes may take a few minutes to propagate. |
Step 5 — Document your configuration
Keep the metadata file and the values you entered (ACS URL, Entity ID, claim mapping, enabled group) in a safe place: you'll need them when renewing the certificate.
5. Testing and confirmation
- Make sure the test user is in a group with Service status = ON.
- If the company is set up with preloading, make sure the same user is already present on the platform with a username identical to the value sent in the
usernameclaim. If not preloaded, access will be denied. - Open a browser window in incognito mode.
- Go to
https://<subdomain>.platform.cyberguru.eu - Click the SSO login button.
- Log in with your Google Workspace credentials: if everything works, you'll land on the Cyber Guru welcome page.
Finally, check that the user's first name, last name, and email are correct on the platform: if they're empty or incorrect, the issue is with the claim mapping.
6. If something doesn't work
- Capture the SAML response with a SAML tracer and check the exact names of the claims received. Here is an example of a correct response:
<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>- Check ACS URL and Entity ID: they must match exactly, character by character, with those in the SP metadata file.
- Check the service status for the user's group.
- Remember that changes made in Google may take a few minutes to propagate.
The most common error messages, along with their causes and solutions, are listed in the SSO Frequently Asked Questions (FAQ).
If the problem persists, contact Cyber Guru support and provide: the full error message, the time of the attempt, the username of the affected user, and if possible, the SamlRequest.xml and SamlResponse.xml files.
7. After Go-Live: Maintenance
- Google SAML certificate rotation: if you generate a new certificate in the SAML certificates section, you must notify Cyber Guru before activating it.
- Metadata changes: these must remain unchanged; any modification must be handled by Cyber Guru support.
-
Primary email or domain changes: if the email is used as the
username, changing it will break the association with the user account on the platform and block access.
The procedures are described in SSO Maintenance: Certificate Renewal and Username/Email Change. Notify Cyber Guru in advance before domain migrations or mass changes.