Mit Keycloak melden sich Ihre Mitarbeiter mit dem Firmenkonto aus Ihrem eigenen Keycloak-Server bei Schulungstool an. Sie legen in Keycloak einmalig einen Client für Schulungstool an und übertragen drei Angaben in Schulungstool – die Verbindung steht in etwa zehn Minuten. Wie Single Sign-on grundsätzlich funktioniert und was die einzelnen Felder bedeuten, erklärt der Artikel Single Sign-on einrichten.

In dieser Anleitung steht https://keycloak.ihre-firma.de/ beispielhaft für die Adresse Ihres Keycloak-Servers und ihre-firma für den Realm, in dem Ihre Benutzer liegen. Die Begriffe entsprechen der englischsprachigen Admin Console aktueller Keycloak-Versionen; die deutsche Übersetzung der Community ist unvollständig und weicht teils ab (etwa Protokolleinstellungen statt Capability config). Für die Einrichtung arbeiten Sie deshalb am besten mit der englischen Oberfläche.

Vorbereitung in Schulungstool

Öffnen Sie im Administrationsbereich Einstellungen > Erweiterte Einstellungen > Single Sign-on und kopieren Sie die Redirect-URI mit dem Button Kopieren. Sie hat die Form https://ihre-firma.schulungstool.de/accounts/sso/callback/ und wird gleich in Keycloak benötigt.

Schulungstool in Keycloak registrieren

Dafür benötigen Sie Zugang zur Keycloak Admin Console mit Verwaltungsrechten für den Realm Ihrer Benutzer, etwa die Rolle realm-admin oder mindestens manage-clients – ohne manage-clients zeigt Keycloak das Client-Secret nur maskiert an. Verwenden Sie nicht den Realm master, Keycloak rät davon ab, dort Benutzer anzulegen. Ihr Keycloak-Server muss über https:// aus dem Internet erreichbar sein – warum, erklärt die Aufklappbox weiter unten.

  1. Öffnen Sie die Admin Console, wählen Sie den Realm Ihrer Benutzer (im Beispiel ihre-firma) und klicken Sie auf Clients > Create client.
  2. Schritt General settings: Lassen Sie Client type auf OpenID Connect. Tragen Sie als Client ID zum Beispiel „schulungstool“ ein – genau dieser Wert ist später die Client-ID in Schulungstool. Vergeben Sie bei Name eine Bezeichnung wie „Schulungstool“ und klicken Sie auf Next.
  3. Schritt Capability config: Schalten Sie Client authentication auf On – der Client gilt damit als vertraulich und erhält ein Client-Secret. Unter Authentication flow bleibt Standard flow aktiviert; Direct access grants braucht Schulungstool nicht – in aktuellen Keycloak-Versionen ist die Option bereits ausgeschaltet, in älteren schalten Sie sie ab. Zeigt Ihre Version den Schalter Require PKCE, können Sie ihn einschalten – Schulungstool unterstützt PKCE mit S256. Klicken Sie auf Next.
  4. Schritt Login settings: Fügen Sie bei Valid redirect URIs die Redirect-URI aus Schulungstool ein – vollständig und ohne Platzhalter wie *. Optional tragen Sie bei Home URL die Login-URL aus Schulungstool ein (https://ihre-firma.schulungstool.de/accounts/sso/login/). Klicken Sie auf Save.
  5. Öffnen Sie im neuen Client den Tab Credentials. Bei Client Authenticator ist Client Id and Secret vorausgewählt. Kopieren Sie den Wert unter Client Secret über das Kopier-Symbol neben dem Feld – das ist das Client-Secret für Schulungstool.
  6. Die Discovery-URL Ihres Realms lautet https://keycloak.ihre-firma.de/realms/ihre-firma/.well-known/openid-configuration. In Keycloak finden Sie sie unter Realm settings > General > Endpoints > OpenID Endpoint Configuration: Der Link öffnet das Dokument, dessen Adresse Sie aus der Adresszeile kopieren – so stimmt sie auch bei Installationen mit eigenem Pfadpräfix. Es genügt auch die Realm-Adresse https://keycloak.ihre-firma.de/realms/ihre-firma – Schulungstool ergänzt den Rest.

Tipp: Schulungstool gleicht Benutzer über ihre E-Mail-Adresse ab. Prüfen Sie deshalb, dass Ihre Benutzer in Keycloak unter Users eine Adresse im Feld Email haben – legt ein Administrator Benutzer an, ist sie kein Pflichtfeld. Fehlen E-Mail-Adresse, Vor- oder Nachname, fordert Keycloak den Benutzer in der Standardkonfiguration bei der nächsten Anmeldung auf, sie nachzutragen. Weil Schulungstool bestehende Benutzer beim ersten Login über die E-Mail-Adresse verknüpft, sollten Benutzer ihre Adresse in Keycloak nicht selbst ändern dürfen (Realm settings > User profile > Attribut email > Permissions: nur Admin) oder Sie aktivieren unter Realm settings > Login die Option Verify email. Die Client Scopes email und profile, die E-Mail-Adresse und Namen übermitteln, sind neuen Clients standardmäßig zugeordnet (Tab Client scopes).

In Schulungstool eintragen

  1. Klicken Sie unter Einstellungen > Erweiterte Einstellungen > Single Sign-on auf Single Sign-on einrichten.
  2. Tragen Sie als Beschriftung des Buttons zum Beispiel „Firmenkonto“ oder den Namen Ihres Unternehmens ein – Ihre Login-Seite zeigt dann Mit Firmenkonto anmelden. Den Namen „Keycloak“ kennen Ihre Mitarbeiter meist nicht.
  3. Fügen Sie die Discovery-URL, die Client-ID (Anwendungs-ID) und das Client-Secret (Geheimer Clientschlüssel) ein.
  4. Wählen Sie unter Standardgruppen für automatisch angelegte Benutzer die gewünschten Gruppen, setzen Sie das Häkchen bei Single Sign-on aktivieren und klicken Sie auf Änderungen speichern. Schulungstool prüft dabei, ob die Discovery-URL erreichbar ist.

Anmeldung testen

Öffnen Sie Ihre Login-Seite in einem privaten Browserfenster und klicken Sie auf Mit Firmenkonto anmelden. Sie landen auf der Anmeldeseite Ihres Keycloak-Servers und nach der Anmeldung direkt im Lernbereich; fehlen im Profil noch Pflichtangaben, fragt Keycloak sie vorher ab. Eine Zustimmungsabfrage erscheint nur, wenn Sie im Client die Option Consent required eingeschaltet haben.

Welche Benutzer dürfen sich anmelden?

Grundsätzlich alle Benutzer des Realms, die sich bei Keycloak anmelden können. Keycloak bietet keinen Schalter, der einen Client auf bestimmte Benutzer oder Gruppen beschränkt; möglich ist das über einen angepassten Authentifizierungsablauf unter Authentication: eine Kopie des Browser-Ablaufs, die Benutzern ohne eine bestimmte Rolle mit Condition - user role und Deny access den Zugang verweigert und die Sie nur dem Client Schulungstool zuweisen (Tab Advanced > Authentication flow overrides > Browser Flow), damit andere Anwendungen des Realms nicht betroffen sind – ein Thema für Ihre Keycloak-Administration, beschrieben in der Keycloak-Dokumentation. Einfacher geht es oft auf Schulungstool-Seite: Schalten Sie Unbekannte Benutzer automatisch anlegen aus, dann können sich nur Benutzer anmelden, die es in Ihrem Konto bereits gibt. Bleibt die Option an, zählt jeder automatisch angelegte Benutzer zum Benutzerlimit Ihres Tarifs.

Keycloak läuft nur im Intranet – geht das?

So nicht: Schulungstool lädt das Discovery-Dokument und tauscht bei jeder Anmeldung serverseitig den Anmeldecode gegen die Benutzerdaten – dafür muss Ihr Keycloak-Server unter einer öffentlichen https://-Adresse mit gültigem Zertifikat erreichbar sein. Außerdem müssen Ihre Mitarbeiter die Anmeldeseite von dort erreichen, wo sie Kurse bearbeiten, zum Beispiel von unterwegs. Viele Unternehmen veröffentlichen dafür über einen Reverse-Proxy nur die Pfade /realms/ihre-firma/ und /resources/ ihres Keycloak-Servers – Letzterer liefert Stylesheets, Skripte und Bilder der Anmeldeseite; die Admin Console unter /admin/ bleibt im Intranet. Keycloak muss dabei seinen öffentlichen Hostnamen kennen, damit Discovery-Dokument und Issuer die öffentliche Adresse enthalten. Ist das bei Ihnen nicht möglich, bleibt der Login mit Benutzername und Passwort – oder Sie nutzen einen Identity Provider in der Cloud, etwa Microsoft Entra ID.

Ein Benutzer kann sich nicht anmelden – was prüfen?

Die häufigsten Ursachen: Der Benutzer hat in Keycloak keine E-Mail-Adresse im Feld Email (Schulungstool braucht sie zum Abgleich), die Option Unbekannte Benutzer automatisch anlegen ist ausgeschaltet und der Benutzer existiert noch nicht in Schulungstool, oder das Benutzerlimit Ihres Tarifs ist erreicht. Die Meldung auf der Login-Seite nennt den Grund. Scheitert dagegen jede Anmeldung, liegt es meist am Client in Keycloak: Die Adresse unter Valid redirect URIs muss Zeichen für Zeichen der Redirect-URI aus Schulungstool entsprechen – inklusive https:// und abschließendem / (Keycloak meldet sonst „Invalid parameter: redirect_uri“ bzw. „Ungültiger Parameter: redirect_uri“) – und Client authentication muss auf On stehen, sonst gibt es kein Client-Secret. Haben Sie das Secret in Keycloak über Regenerate erneuert, ist das alte sofort ungültig – tragen Sie den neuen Wert umgehend in Schulungstool ein.

Sie möchten die Einrichtung lieber gemeinsam mit uns durchgehen? Unser Support hilft kostenfrei: Schreiben Sie an support@schulungstool.de oder nutzen Sie Einstellungen > Erweiterte Einstellungen > Nachricht an Support senden.