1. Für wen ist diese Anleitung gedacht
Diese Anleitung führt dich durch die Einrichtung des Single Sign-On (SSO) zwischen Microsoft Entra ID (ehemals Azure Active Directory) und der Cyber Guru Plattform unter Verwendung des SAML 2.0-Protokolls.
Um die Einrichtung abzuschließen, benötigst du eine Rolle mit administrativen Rechten in Microsoft Entra ID (typischerweise Cloud Application Administrator oder Application Administrator). Falls du dir nicht sicher bist, ob du diese Rechte hast, wende dich vor Beginn an das IT-Team deiner Organisation.
Im Text wird der Ansprechpartner „CyberGuru“ als CyberGuru oder der Partner, der deine Plattform betreut bezeichnet.
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 Microsoft-Konsole auf Englisch. Falls deine Konsole auf Deutsch ist, findest du die entsprechenden Begriffe im Text in Klammern. Die Bezeichnungen in der Microsoft-Oberfläche ändern sich häufig: Falls du einen Begriff nicht exakt findest, nutze die Suchleiste im Portal. |
2. Inhaltsverzeichnis
- Schlüsselbegriffe
- Voraussetzungen und Entscheidungen vor dem Start
- Schritt-für-Schritt-Konfiguration (Schritte 1-8)
- Test und Bestätigung
- Wenn etwas nicht funktioniert
- Nach dem Go-Live: Wartung
- Zusätzliche Ressourcen
3. Schlüsselbegriffe
- IdP (Identity Provider): Das System, das die Nutzer authentifiziert. In diesem Szenario ist das Microsoft Entra ID.
- SP (Service Provider): Der Dienst, auf den der Nutzer zugreift, also die Cyber Guru Plattform.
- Metadaten: XML-Datei (oder URL), über die IdP und SP Endpunkte und Zertifikate austauschen, um gegenseitiges Vertrauen herzustellen (circle of trust).
- Claim (Anspruch): Eine Information über den Nutzer, die der IdP in die SAML-Antwort einfügt – zum Beispiel Vorname, Nachname, E-Mail.
- Enterprise Application: Das Objekt in Entra ID, das die zu integrierende Anwendung repräsentiert.
4. Voraussetzungen und Entscheidungen vor dem Start
Diese Punkte sollten vor dem Öffnen der Konsole geklärt werden: Die meisten Konfigurationsprobleme entstehen durch eine falsche Entscheidung an dieser Stelle.
| Element | Wer stellt es bereit | Hinweise |
|---|---|---|
| Administrativer Zugriff auf Microsoft Entra ID | Kunde | Rolle Application Administrator oder höher. |
| Protokoll | — | SAML 2.0. Andere Protokolle werden nicht unterstützt. |
Feld, das als username verwendet wird
|
Kunde |
Wichtigste Entscheidung der Konfiguration. Es muss sich um ein unveränderliches Attribut handeln: Es ist der Schlüssel, mit dem die Plattform den Nutzer erkennt und kann nach Projektstart nicht mehr geändert werden. In Entra ID wird die Verwendung der Object ID (user.objectid) empfohlen. Alternativen (z. B. Personalnummer) sind zulässig, sofern sie unveränderlich sind. Vermeide E-Mail und UPN, falls diese sich ändern können: siehe §8. |
| Pflichtattribute im Nutzerprofil | Kunde | Es sind vier: username, email, firstName, lastName. Stelle sicher, dass Vorname, Nachname und E-Mail im Entra-Profil ausgefüllt sind. |
| Zu übermittelnde Organisationen | Kunde + Cyber Guru | Optional, im Format org_{NOME_ORG} (Standort, Abteilung, Organisationseinheit ...). Notwendig, wenn das Unternehmen ohne Vorabimport arbeitet oder eine davon als Team für Statistiken und Gamification genutzt werden soll. Details unter Identity Provider SSO Attribute. |
| Zugriffsrichtlinie für die Anwendung | Kunde | Nutze eine dedizierte Gruppe statt einzelne Nutzer zuzuweisen: Das ist langfristig am einfachsten zu verwalten. Nur Nutzer, die der App zugewiesen sind, erhalten Zugriff. |
| Modus der Nutzerbereitstellung | Kunde + Cyber Guru | Mit Vorabimport (empfohlen) oder ohne. Die beiden Varianten haben unterschiedliche Auswirkungen auf Lizenzen und Attribute: Lies Allgemeine SSO-Prozedur vor der Entscheidung. |
| Testnutzer | Kunde | Stelle einen Test-Account in Entra ID bereit, um die Einrichtung zu überprüfen. |
| Subdomain der Plattform | Cyber Guru | Im Format https://<subdomain>.platform.cyberguru.eu. |
5. Schritt-für-Schritt-Konfiguration
Schritt 1 — Melde dich bei Microsoft Entra ID an
Gehe auf https://entra.microsoft.com mit einem Account, der die in den Voraussetzungen genannten administrativen Rechte besitzt.
Schritt 2 — Öffne "Enterprise applications" (Unternehmensanwendungen)
Wähle im linken Navigationsmenü Enterprise applications (Unternehmensanwendungen).
Schritt 3 — Erstelle eine neue Non-Gallery-Anwendung
Klicke oben auf der Seite auf New application (Neue Anwendung).
Klicke dann auf Create your own application (Eigene Anwendung erstellen).
Im sich öffnenden Panel: Gib der Anwendung einen Namen (z. B. Cyber Guru), stelle sicher, dass die Option "Integrate any other application you don't find in the gallery (Non-gallery)" ausgewählt ist, und klicke auf Create.
Schritt 4 — Starte die SAML-Konfiguration
Öffne auf der Übersichtsseite der gerade erstellten Anwendung im linken Menü Single sign-on (oder das Feld Set up single sign on).
Wähle unter den vorgeschlagenen Methoden SAML aus.
Schritt 5 — Sende die IdP-Metadaten an Cyber Guru
Im Bereich 3 — SAML Certificates findest du das Feld App Federation Metadata Url.
Kopiere diese URL und sende sie an Cyber Guru. Sie sieht so aus:
https://login.microsoftonline.com/<tenant-id>/federationmetadata/2007-06/federationmetadata.xml?appid=<app-id>
| ⚠️ | Sende die URL, nicht das heruntergeladene Zertifikat oder die XML-Datei. Nach der Konfiguration müssen die Metadaten unverändert bleiben. Falls sie sich in Zukunft ändern – neues Zertifikat, neue Anwendung, andere Endpunkte – ändere sie nicht selbstständig und erstelle sie nicht neu: Öffne ein Ticket beim CyberGuru-Support, der die Aktualisierung koordiniert. Siehe §8. |
Schritt 6 — Erhalte und lade die SP-Metadaten von Cyber Guru hoch
Cyber Guru schließt die Konfiguration auf seiner Seite ab und sendet dir die SP-Metadaten-URL im Format:
https://<host-login-cyberguru>/realms/<subdomain>/broker/saml/endpoint/descriptor
| ⚠️ | Verwende genau die URL, die du von Cyber Guru erhältst: Baue sie nicht selbst zusammen 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. |
Öffne die URL in einem Browser und speichere die Seite als XML-Datei. Klicke dann auf der SAML-Seite der Anwendung oben auf Upload metadata file (Metadatendatei hochladen) und lade die gespeicherte Datei hoch.
Entra ID füllt Identifier (Entity ID) und Reply URL (ACS URL) automatisch aus. Überprüfe die Werte auf der Übersichtsseite und klicke auf Save.
Schritt 7 — Konfiguriere die Claims (Attributes & Claims)
Öffne den Bereich 2 — Attributes & Claims und klicke auf Edit. Nach dem Erstellen der App findest du einen Satz vordefinierter Claims:
Du kannst die bestehenden zusätzlichen Claims bearbeiten oder alle entfernen und neue anlegen. Cyber Guru benötigt genau diese vier Claims:
| Name der Claim (Name) | Namespace | Empfohlenes Quellattribut |
|---|---|---|
username |
(leer) |
user.objectid oder user.userprincipalname |
email |
(leer) | user.mail |
firstName |
(leer) | user.givenname |
lastName |
(leer) | user.surname |
| Unique User Identifier | identisch mit username |
Für jede Claim stelle in Manage claim Source = Attribute ein und wähle das Quellattribut aus:
| 🛑 |
Die beiden häufigsten Fehler, beide in diesem Schritt: 1. Das Feld Namespace muss leer bleiben. Entra ID füllt es automatisch mit einem Wert wie http://schemas.xmlsoap.org/ws/2005/05/identity/claims: Wenn du es so lässt, wird die Claim mit diesem Präfix an Cyber Guru gesendet und nicht erkannt. Lösche es bei allen vier Claims.2. Die Namen der Claims sind case-sensitiv. firstName und lastName müssen exakt so (camelCase) geschrieben werden. |
Falls auch Organisationen (org_{NOME_ORG}) 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ändigen Regeln zu Attributen – Pflicht, optional, Organisationen und Teams, Aktualisierungshäufigkeit – findest du unter Identity Provider SSO Attribute, das als Referenz dient.
Nach Abschluss der Konfiguration solltest du eine Übersicht wie diese sehen. Überprüfe das Mapping Zeile für Zeile sorgfältig:
Schritt 8 — Nutzer autorisieren und Konfiguration dokumentieren
Gehe zu Users and groups (Benutzer und Gruppen) und weise der Anwendung die Gruppe zu, die die berechtigten Nutzer enthält. Nutzer, die der App nicht zugewiesen sind, erhalten beim Zugriff einen Fehler 403 oder eine Nicht-Autorisierungs-Meldung vom IDP, auch wenn alles andere korrekt eingerichtet ist.
Für den Test weise zunächst nur 2-3 Testnutzer zu; die vollständige Gruppe kannst du zum Go-Live hinzufügen.
Bewahre eine digitale Kopie der Konfiguration auf (Metadaten-URLs, Claim-Namen, zugewiesene Gruppe): Das ist beim Zertifikatswechsel hilfreich.
6. Test und Bestätigung
- Stelle sicher, dass der Testbenutzer der Anwendung zugewiesen ist in Entra ID.
- Wenn das Unternehmen mit Vorab-Laden konfiguriert ist, stelle sicher, dass derselbe Benutzer bereits auf der Plattform vorhanden ist und dass sein Benutzername auf der Plattform exakt dem Wert im Claim
usernameentspricht. Ist er nicht vorab geladen, wird der Zugriff verweigert. - Öffne ein Browserfenster im Inkognito-Modus (um keine bereits aktiven Microsoft-Sitzungen wiederzuverwenden).
- Gehe zu
https://<subdomain>.platform.cyberguru.eu - Klicke auf den SSO-Anmeldebutton.
- Melde dich bei Microsoft an. Wenn alles funktioniert, gelangst du direkt zur Cyber Guru Willkommensseite, ohne weitere Zugangsdaten eingeben zu müssen.
- Überprüfe auf der Plattform, ob Name, Nachname und E-Mail des Benutzers korrekt sind: Wenn sie leer oder falsch sind, liegt das Problem im Claim-Mapping.
7. Wenn etwas nicht funktioniert
Probiere diese drei Kontrollen aus, sie lösen die meisten Fälle:
-
Fange die SAML-Antwort mit einem SAML-Tracer (Browser-Erweiterung) ab und prüfe die genauen Namen der empfangenen Claims: richtige Groß-/Kleinschreibung? Kein Namespace? Ist der Wert von
usernameidentisch mit dem auf der Plattform? - Überprüfe die Zuweisung des Benutzers zur Anwendung in Entra ID.
- Lies die Fehlermeldung: Sie ist fast immer aufschlussreich.
Die häufigsten Fehlermeldungen mit Ursache und Lösung findest du unter Häufige Fragen zu SSO (FAQ).
Wenn das Problem weiterhin besteht, kontaktiere den Cyber Guru Support und gib folgende Informationen an: die vollständige Fehlermeldung, den Zeitpunkt des Versuchs, den Benutzernamen des betroffenen Nutzers und, wenn möglich, die Dateien SamlRequest.xml und SamlResponse.xml aus dem Tracer.
8. Nach dem Go-Live: Wartung
Drei Ereignisse erfordern eine Abstimmung mit Cyber Guru. Plane sie im Voraus:
- Ablauf des SAML-Signaturzertifikats in der Entra-Anwendung (Microsoft benachrichtigt vor Ablauf).
- Jegliche Änderung der Metadaten der Anwendung: Sie müssen unverändert bleiben, jede Änderung muss vom Support begleitet werden.
- Änderungen von E-Mail, UPN oder Domain der Benutzer: Sie können die Zuordnung zwischen Entra-Identität und Plattform-Benutzerkonto unterbrechen, was den Zugriff blockiert.
Die Vorgehensweisen sind beschrieben unter SSO-Wartung: Zertifikatserneuerung und Änderung von Username/E-Mail. Informiere Cyber Guru vorab bei Domain-Migrationen oder massenhaften UPN-Änderungen.
9. Weitere Ressourcen
- Allgemeine SSO-Anleitung — die zwei SSO-Methoden und die Grundvoraussetzungen.
- SSO Identity Provider Attribute — vollständige Referenz zu den Attributen.
- Häufige Fragen zu SSO (FAQ)
- SSO-Wartung
- Erweiterte SSO-Szenarien
- Hybride Authentifizierung (SSO + Anwendungszugangsdaten)
- Microsoft Entra ID Dokumentation zu SAML SSO