1. Für wen ist diese Anleitung gedacht
Diese Anleitung führt dich durch die Einrichtung des Single Sign-On (SSO) zwischen Google Workspace und der Cyber Guru Plattform unter Verwendung des SAML 2.0-Protokolls. Am Ende können deine Nutzer sich mit ihren Google Workspace-Zugangsdaten bei Cyber Guru anmelden, ohne ein separates Passwort.
Du benötigst ein Konto mit der Rolle Super Admin in Google Workspace und Zugriff auf die Admin-Konsole (https://admin.google.com).
Im Text wird mit „Cyber Guru“ Cyber Guru oder der Partner, der deine Plattform verwaltet gemeint.
Diese Anleitung behandelt außerdem den Fall der SSO-Authentifizierung via SAML 2.0 mit SP-Initiated-Mechanismus (also Start über die URL). Falls du SSO-Zugriff über die Anwendung (IDP-Initiated) einrichten möchtest, wende dich bitte an den Support.
| 💡 | Die Screenshots in dieser Anleitung zeigen die Google Admin-Konsole auf Englisch. Wenn deine Konsole auf Deutsch ist, findest du die entsprechenden Begriffe im Text in Klammern. |
2. Inhaltsverzeichnis
- Voraussetzungen und Entscheidungen vor dem Start
- Schritt-für-Schritt-Konfiguration (Schritte 1-5)
- Test und Bestätigung
- Wenn etwas nicht funktioniert
- Nach dem Go-Live: Wartung
- Zusätzliche Ressourcen
3. Voraussetzungen und Entscheidungen vor dem Start
Diese Punkte sollten vor dem Öffnen der Konsole geklärt werden: Die meisten Konfigurationsprobleme entstehen durch falsche Entscheidungen an dieser Stelle.
| Element | Wer stellt es bereit | Hinweise |
|---|---|---|
| Super Admin-Konto für Google Workspace | Kunde | Zugriff auf admin.google.com. |
| Protokoll | — | SAML 2.0. Andere Protokolle werden nicht unterstützt. |
Feld, das als username verwendet wird
|
Kunde | Wichtigste Entscheidung der Konfiguration. Es muss ein unveränderliches Attribut sein: Es ist der Schlüssel, mit dem die Plattform den Nutzer erkennt und kann nach Projektstart nicht mehr geändert werden. Falls sich die Haupt-E-Mail ändern könnte (z. B. Namensänderung, Domainwechsel), verwende sie nicht: Wähle ein stabiles Feld wie Mitarbeiter-ID. Siehe §7. |
| Pflichtattribute, die im Profil ausgefüllt sein müssen | Kunde | Es sind vier: username, email, firstName, lastName. Ist ein Feld im Google-Profil leer, wird das Attribut leer übertragen. |
| Zu übermittelnde Organisationen | Kunde + Cyber Guru | Optional, im Format org_{ORG_NAME} (Standort, Abteilung, Organisationseinheit ...). Notwendig, wenn das Unternehmen ohne Vorab-Import arbeitet oder eine davon als Team für Statistiken und Gamification genutzt werden soll. Details unter Identity Provider SSO Attribute. |
| Gruppe der berechtigten Nutzer | Kunde | Verwende eine eigene Gruppe statt die App für die gesamte Organisation zu aktivieren: Nur Nutzer, für die der Dienst aktiv ist, können zugreifen. |
| Art der Nutzerbereitstellung | Kunde + Cyber Guru | Mit Vorab-Import (empfohlen) oder ohne. Lies Allgemeine SSO-Prozedur vor der Entscheidung. |
| Testnutzer | Kunde | Es ist hilfreich, einen Test-Account für die Überprüfung bereitzustellen. |
| Subdomain der Plattform | Cyber Guru | Im Format https://<subdomain>.platform.cyberguru.eu. |
4. Schritt-für-Schritt-Konfiguration
Schritt 1 — Melde dich in der Google Admin-Konsole an
Öffne https://admin.google.com und melde dich mit deinem Administratorkonto an.
Schritt 2 — Lade die IdP-Metadaten von Google herunter und sende sie an Cyber Guru
Wähle im linken Menü Apps (Apps) → Web and mobile apps (Web- und mobile Apps).
Gehe zu Settings (Einstellungen) → SAML certificates (SAML-Zertifikate).
Es öffnet sich die Seite mit den Details des Google Identity Providers.
Scrolle ganz nach unten und klicke auf DOWNLOAD METADATA (METADATEN HERUNTERLADEN).
Sende die Datei GoogleIDPMetadata.xml an Cyber Guru. Cyber Guru richtet die eigene Seite ein und schickt dir die SP-Metadaten-URL zurück (siehe Schritt 3.3).
Schritt 3 — Erstelle die benutzerdefinierte SAML-App
Gehe zurück zu Apps → Web and mobile apps.
Klicke auf Add app (App hinzufügen) → Add custom SAML app (Benutzerdefinierte SAML-App hinzufügen).
3.1 — App-Details. Fülle App name (z. B. Cyber Guru) und Description aus und klicke dann auf CONTINUE.
3.2 — Google IdP-Details. Auf diesem Bildschirm werden die gleichen Metadaten angezeigt, die du bereits in Schritt 2 gesendet hast: Du musst nichts tun, klicke einfach auf CONTINUE.
3.3 — Service Provider-Details. Hier trägst du die Werte aus den SP-Metadaten ein, die du von Cyber Guru erhalten hast.
Die SP-Metadaten-URL, die du erhältst, sieht so aus:
https://<host-login-cyberguru>/realms/<subdomain>/broker/saml/endpoint/descriptor
Öffne sie im Browser: Die beiden Werte, die du im Formular eintragen musst, findest du in der XML-Datei.
| Google-Feld | Wo im SP-Metadaten-XML zu finden |
|---|---|
| ACS URL | Attribut Location des Elements <md:AssertionConsumerService> mit HTTP-POST-Binding |
| Entity ID | Attribut entityID des Wurzelelements <md:EntityDescriptor>
|
| ⚠️ | Kopiere die Werte exakt aus deiner Metadatendatei, Zeichen für Zeichen. Baue sie nicht manuell nach und kopiere sie nicht aus anderen Anleitungen oder Konfigurationen anderer Organisationen: Die Adresse hängt von der Umgebung ab, in der dein Unternehmen gehostet wird. |
Trage ACS URL und Entity ID ein, stelle das Name ID format entsprechend der Angabe von Cyber Guru zusammen mit den SP-Metadaten ein, lasse Name ID auf dem Standardwert und klicke auf CONTINUE.
3.4 — Attribut-Mapping. Klicke auf ADD MAPPING (MAPPING HINZUFÜGEN) und richte die vier von Cyber Guru geforderten Claims ein.
| Google Directory-Attribut | Name des App-Attributs | Hinweise |
|---|---|---|
| Unveränderliches Feld aus den Voraussetzungen (z. B. Mitarbeiter-ID; Primäre E-Mail nur, wenn sie sich nie ändert) | username |
Schlüssel zur Nutzerzuordnung. |
| Primäre E-Mail | email |
|
| Vorname | firstName |
camelCase ist Pflicht. |
| Nachname | lastName |
camelCase ist Pflicht. |
| 🛑 |
Die Claim-Namen sind groß-/kleinschreibungssensitiv. firstName und lastName müssen exakt so (camelCase) geschrieben werden. Schreibweisen wie FirstName oder firstname werden von der Plattform nicht erkannt. |
Mapping von username:
Mapping von firstName:
Mapping von lastName:
Mapping von email:
Falls auch Organisationen (org_{ORG_NAME}) oder die optionalen Attribute locale und country benötigt werden, wenn der Nutzer beim SSO-Login gleichzeitig angelegt wird, füge sie nach denselben Regeln hinzu. Die vollständige Referenz findest du unter Identity Provider SSO Attribute.
Klicke unten auf der Seite auf FINISH. Die App ist nun erstellt:
Schritt 4 — Aktiviere die App für deine Nutzer
In der App-Übersicht findest du das Panel User access (Nutzerzugriff).
Klicke auf OFF for everyone (FÜR ALLE AUS).
Wähle Groups (Gruppen) und suche die Gruppe mit den berechtigten Nutzern aus.
Setze den Service status (Dienststatus) für diese Gruppe auf ON und klicke auf SAVE.
| ⚠️ | Für den Test aktiviere eine kleine Gruppe mit 2-3 Testnutzern. Wenn ein Nutzer nicht zu einer Gruppe mit aktiviertem Dienst gehört, erhält er beim Login eine Fehlermeldung „Dienst nicht aktiviert“, auch wenn alles andere korrekt eingerichtet ist. Änderungen am Dienststatus können einige Minuten dauern, bis sie wirksam werden. |
Schritt 5 — Dokumentiere die Konfiguration
Bewahre die Metadatendatei und die eingetragenen Werte (ACS URL, Entity ID, Claim-Mapping, aktivierte Gruppe) an einem sicheren Ort auf: Du benötigst sie für die Zertifikatserneuerung.
5. Test und Bestätigung
- Stelle sicher, dass der Testnutzer zu einer Gruppe mit Service status = ON gehört.
- Wenn das Unternehmen mit Vorab-Import konfiguriert ist, prüfe, dass derselbe Nutzer bereits auf der Plattform vorhanden ist und der Username mit dem Wert in der Claim
usernameübereinstimmt. Ist er nicht vorab importiert, wird der Zugriff verweigert. - Öffne ein Browserfenster im Inkognito-Modus.
- Gehe zu
https://<subdomain>.platform.cyberguru.eu - Klicke auf den SSO-Anmeldebutton.
- Melde dich mit den Google Workspace-Zugangsdaten an: Wenn alles funktioniert, landest du auf der Cyber Guru Willkommensseite.
Prüfe abschließend, ob Vorname, Nachname und E-Mail des Nutzers auf der Plattform korrekt sind: Sind sie leer oder falsch, liegt das Problem im Claim-Mapping.
6. Wenn etwas nicht funktioniert
- Fange die SAML-Antwort mit einem SAML-Tracer ab und prüfe die exakten Namen der empfangenen Claims. Ein Beispiel für eine korrekte Antwort:
<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>- Überprüfe ACS-URL und Entity ID: Sie müssen exakt mit denen aus der SP-Metadatendatei übereinstimmen.
- Überprüfe den Servicestatus für die Benutzergruppe.
- Beachte, dass Änderungen in Google einige Minuten benötigen, um wirksam zu werden.
Die häufigsten Fehlermeldungen mit Ursache und Lösung findest du in den Häufig gestellten Fragen zu SSO (FAQ).
Wenn das Problem weiterhin besteht, wende dich an den Cyber Guru Support und gib folgende Informationen an: vollständige Fehlermeldung, Zeitpunkt des Versuchs, Benutzername des betroffenen Nutzers und, wenn möglich, die Dateien SamlRequest.xml und SamlResponse.xml.
7. Nach dem Go-Live: Wartung
- Rotation des Google SAML-Zertifikats: Wenn du ein neues Zertifikat im Bereich SAML certificates erstellst, muss dies vor der Aktivierung an Cyber Guru gemeldet werden.
- Änderungen an den Metadaten: Diese müssen unverändert bleiben; jede Änderung muss vom Cyber Guru Support begleitet werden.
-
Wechsel der Haupt-E-Mail oder Domain: Wird die E-Mail als
usernameverwendet, führt eine Änderung dazu, dass die Verknüpfung zum Nutzerkonto in der Plattform verloren geht und der Zugriff gesperrt wird.
Die entsprechenden Anleitungen findest du unter SSO-Wartung: Zertifikatserneuerung und Änderung von Username/E-Mail. Informiere Cyber Guru unbedingt vorab bei Domainumzügen oder größeren Änderungen.