Zum Hauptinhalt gehen
Anmelden
English (United States) Español Français Italiano

Anleitung zur Konfiguration von SSO mit einem generischen Identity Provider (SAML 2.0)

1. Für wen ist diese Anleitung gedacht

Die Cyber Guru Plattform lässt sich mit jedem Identity Provider integrieren, der SAML 2.0 unterstützt. Für Microsoft Entra ID und Google Workspace gibt es eigene Anleitungen mit Screenshots der jeweiligen Konsolen:

Diese Anleitung gilt für alle anderen Fälle: Okta, Microsoft ADFS, Shibboleth, Oracle, ForgeRock, IBM, AWS, WSO2, PingFederate oder eine intern entwickelte Lösung.

Du findest hier keine Screenshots: Jede Konsole sieht anders aus und die Menüpunkte ändern sich je nach Version. Stattdessen findest du alles, was dein Identity Provider tun muss und die genauen Werte, die ausgetauscht werden müssen, damit jemand, der dein System kennt, es ohne Zögern konfigurieren kann.

💡 Die Konfiguration deines Identity Providers liegt in der Verantwortung deiner Organisation – entweder mit eigenen Ressourcen oder mit Unterstützung des Identitätsplattform-Anbieters. Cyber Guru konfiguriert die eigene Seite und stellt alle notwendigen Werte bereit.

2. So funktioniert die Integration

Cyber Guru agiert als Service Provider (SP), dein System als Identity Provider (IdP). Damit das Protokoll funktioniert, müssen beide SAML 2.0-Komponenten haben und gegenseitiges Vertrauen (circle of trust) durch Austausch der Metadaten einrichten.

Der vorgesehene Ablauf ist SP-initiated: Der Nutzer startet von der Plattform-Adresse, wird zum Identity Provider zur Authentifizierung weitergeleitet und kehrt mit einer SAML-Assertion zur Plattform zurück. (Der Zugang vom IdP-Portal aus — IdP-initiated — ist möglich, erfordert aber zusätzliche Konfiguration: siehe Erweiterte SSO-Szenarien.)

3. Voraussetzungen und Entscheidungen vor dem Start

Element Wer stellt es bereit Hinweise
Identity Provider mit SAML 2.0-Unterstützung Kunde Andere Protokolle werden nicht unterstützt.
Administratorrechte auf dem IdP Kunde Es muss möglich sein, eine neue Anwendung/Relying Party zu erstellen und die auszugebenden Attribute zu definieren.
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. In Active Directory ist das typischerweise das ObjectGUID; in anderen Systemen eine vergleichbare Kennung (z. B. eine Personalnummer). Vermeide E-Mail und UPN, wenn diese sich im Laufe der Zeit ändern können.
Pflichtattribute, die im Profil ausgefüllt sind Kunde Es sind vier: username, email, firstName, lastName.
Zu übermittelnde Organisationen Kunde + Cyber Guru Optional, im Format org_{ORG_NAME}. Notwendig, wenn das Unternehmen ohne Vorab-Import arbeitet oder eine Organisation als Team für Statistiken und Gamification genutzt werden soll.
IdP-Metadaten Kunde Öffentlich erreichbare URL oder XML-Datei.
Zugriffsrichtlinie für die Anwendung Kunde Nutze eine eigene Gruppe: Nur autorisierte Nutzer erhalten Zugriff auf die Anwendung.
Art der Nutzerbereitstellung Kunde + Cyber Guru Mit Vorab-Import (empfohlen) oder ohne: siehe Allgemeine SSO-Prozedur.
Testnutzer Kunde 2-3 Testnutzer für die Abnahme, die für die Anwendung freigeschaltet sind.
Plattform-Subdomain und SP-Metadaten Cyber Guru Werden nach dem Austausch bereitgestellt.

4. Schritt-für-Schritt-Konfiguration

Schritt 1 — Erstelle die SAML-Anwendung auf deinem Identity Provider

Erstelle eine neue Anwendung (je nach System application, relying party trust, service provider, client genannt) vom Typ SAML 2.0. Verwende keine Katalogvorlagen für andere Produkte: Es wird eine generische Integration benötigt.

Schritt 2 — Übermittle die IdP-Metadaten an Cyber Guru

Sende Cyber Guru die öffentliche Metadaten-URL deines Identity Providers (bevorzugt) oder die XML-Datei der Metadaten.

Die Metadaten müssen enthalten: das entityID des IdP, den Endpoint des Single Sign-On Service und das öffentliche Signaturzertifikat.

⚠️ Wenn dein Identity Provider nur aus dem internen Netzwerk erreichbar ist, müssen die Metadaten trotzdem über eine öffentliche URL bereitgestellt oder als Datei übermittelt werden. Ein Endpoint, der nicht aus dem Internet erreichbar ist, kann nicht für die Authentifizierung externer Nutzer verwendet werden.

Schritt 3 — Erhalte die SP-Metadaten von Cyber Guru und konfiguriere die Anwendung

Cyber Guru schließt die Konfiguration auf der eigenen Seite ab und sendet dir die SP-Metadaten-URL. Wenn dein System den automatischen Import von Metadaten unterstützt, nutze diesen: Das ist der sicherste Weg. Andernfalls öffne die URL im Browser und entnimm die Werte aus der XML-Datei:

Zu konfigurierender Wert Wo im SP-Metadaten-XML zu finden
Entity ID (audience / SP identifier) Attribut entityID des Root-Elements <md:EntityDescriptor>
ACS URL (Assertion Consumer Service, reply URL, destination) Attribut Location des Elements <md:AssertionConsumerService> mit HTTP-POST-Binding
⚠️ Kopiere die Werte aus deiner Metadaten-Datei, 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.

Schritt 4 — Technische Anforderungen an die Assertion

Parameter Erforderlicher Wert
Protokollversion SAML 2.0
Antwort-Binding HTTP-POST an die ACS URL
Signatur Die Assertion (oder die Antwort) muss mit dem privaten Schlüssel des IdP signiert sein; das zugehörige öffentliche Zertifikat muss in den übermittelten Metadaten enthalten sein
Verschlüsselung der Assertion Nicht erforderlich. Falls dein IdP dies erzwingt, teile es vor der Konfiguration mit
Name ID Format Nach Vorgabe, die du zusammen mit den SP-Metadaten von Cyber Guru erhältst
Single Logout Optional. Falls dein IdP Logout mit HTTP-POST-Binding unterstützt, teile dies mit: Es erfordert eine zusätzliche Konfiguration auf Cyber Guru Seite

Schritt 5 — Konfiguriere die ausgegebenen Attribute

Die Assertion muss vier Pflichtattribute mit genau diesen Namen enthalten:

Attributname Inhalt
username Die im Vorfeld gewählte unveränderliche Kennung
email E-Mail-Adresse des Nutzers
firstName Vorname
lastName Nachname

Optional: locale (zweistelliger ISO-Sprachcode, klein geschrieben), country (zweistelliger ISO-Ländercode, groß geschrieben) und Organisationen im Format org_{ORG_NAME}.

🛑 Zwei Regeln, die für jeden Identity Provider gelten:
1. Die Attributnamen sind groß-/kleinschreibungssensitiv. firstName und lastName müssen exakt so, im camelCase, geschrieben werden.
2. Die Namen dürfen keine Namespace-Präfixe haben. Viele Identity Provider — insbesondere ADFS und Microsoft Entra ID — geben Attribute mit einem Präfix wie http://schemas.xmlsoap.org/ws/2005/05/identity/claims aus: Dieser Präfix muss entfernt werden, sonst wird das Attribut nicht erkannt.

Die vollständige Referenz zu den Attributen — Pflicht, optional, Organisationen und Teams, Aktualisierungshäufigkeit — findest du unter Identity Provider SSO Attribute. Attribute, die dort nicht aufgeführt sind, müssen vorab mit Cyber Guru abgestimmt werden.

Ein Beispiel, wie der Attribut-Teil der Assertion aussehen muss:

<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>

Schritt 6 — Nutzer autorisieren

Weise der Anwendung die Gruppe zu, die die autorisierten Nutzer enthält. Nutzer, die nicht für die Anwendung freigeschaltet sind, erhalten beim Login eine Fehlermeldung, auch wenn alles andere korrekt konfiguriert ist. Für den Testbetrieb autorisiere nur die Testnutzer.

Schritt 7 — Konfiguration dokumentieren

Bewahre die eingetragenen Werte (Entity ID, ACS URL, Attributnamen, autorisierte Gruppe) und die Metadaten-Datei auf: Sie werden für die Zertifikatserneuerung benötigt.

5. Test und Bestätigung

  1. Stelle sicher, dass der Testnutzer auf dem Identity Provider für die Anwendung autorisiert ist.
  2. Wenn das Unternehmen mit Vorab-Import konfiguriert ist, prüfe, dass derselbe Nutzer bereits auf der Plattform vorhanden ist und der Username exakt dem Wert im username-Attribut entspricht. Ist er nicht vorab importiert, wird der Zugang verweigert.
  3. Öffne ein Browserfenster im Inkognito-Modus.
  4. Gehe zu https://<subdomain>.platform.cyberguru.eu und klicke auf den SSO-Login-Button.
  5. Melde dich bei deinem Identity Provider an: Wenn alles funktioniert, landest du ohne weitere Eingabe von Zugangsdaten auf der Cyber Guru Willkommensseite.
  6. Überprüfe auf der Plattform, ob Name, Nachname und E-Mail korrekt sind: Wenn sie leer oder falsch sind, liegt das Problem bei den ausgegebenen Attributen.

6. Wenn etwas nicht funktioniert

Das wichtigste Werkzeug ist ein SAML-Tracer im Browser: Er fängt die SAML-Antwort ab und prüft die exakten Attributnamen (inklusive Groß-/Kleinschreibung), das Fehlen von Namespace-Präfixen, den Wert von username und das Vorhandensein aller vier Pflichtattribute.

Prüfe außerdem, dass Entity ID und ACS URL exakt mit denen aus den SP-Metadaten übereinstimmen und dass der Nutzer für die Anwendung autorisiert ist.

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: vollständige Fehlermeldung, Zeitpunkt des Versuchs, Username des betroffenen Nutzers, Subdomain des Unternehmens und – wenn möglich – die Dateien SamlRequest.xml und SamlResponse.xml.

7. Nach dem Go-Live: Wartung

Nach der Konfiguration gelten die Metadaten als fest. Wenn sie sich ändern – z. B. bei Erneuerung des Signaturzertifikats, neuen Endpoints, neuer Anwendung oder Wechsel des Identity Providers – ändere sie nicht eigenständig: Eröffne ein Ticket beim Cyber Guru Support, der die Aktualisierung auf beiden Seiten koordiniert. Das gilt auch für Änderungen an E-Mail, UPN oder Domain der Nutzer, da dies die Zuordnung zu den Plattform-Nutzern unterbrechen kann.

Die entsprechenden Anleitungen findest du unter SSO-Wartung: Zertifikatserneuerung und Änderung von Username/E-Mail.

8. Verwandte Artikel

Verwandte Beiträge