SSO mit Keycloak einrichten

Richte SSO für eine bestehende Kanroo-Organisation ein. Wir haben diese Schritte von Hand mit Keycloak 26.7.3 getestet. Wie Du Keycloak installierst, erklärt diese Anleitung nicht.

Kontoverknüpfung, Zugriff auf die Einstellungen und Fragen zur täglichen Anmeldung erklärt Persönliche und SSO-Anmeldung.

Bevor Du beginnst

• SSO muss verfügbar sein: in jedem Plan von Kanroo Cloud oder bei selbst gehostetem Enterprise.
• Melde Dich bei Kanroo persönlich per E-Mail als Inhaber der Organisation an. Du brauchst Zugriff auf dieses Postfach.
• Du brauchst Administratorzugriff auf den vorgesehenen Keycloak-Realm und einen Benutzer für den Kanroo-Inhaber.
• Der Browser und der Kanroo-Server müssen die HTTPS-Endpunkte des Realms erreichen und ihnen vertrauen. Betreiber einer selbst gehosteten Installation müssen den OIDC-Verschlüsselungs-Keyring einrichten, bevor sie ein Client Secret speichern. Issuer in einem privaten Netz und Issuer auf einem anderen Port als 443 verlangen zusätzlich OIDC_ALLOW_PRIVATE_ISSUERS=true. HTTPS bleibt Pflicht. Kanroo Cloud akzeptiert nur Port 443. Stelle den Realm dann auf Port 443 bereit, zum Beispiel über einen Reverse Proxy.

1. Kanroo in Keycloak anlegen

Öffne in Kanroo Organisationseinstellungen → SSO und kopiere die angezeigte Weiterleitungs-URL.

Öffne im vorgesehenen Keycloak-Realm Clients → Create client:

Einstellung	Wert
Client type	OpenID Connect
Client ID	kanroo
Client authentication	On
Authorization	Off
Authentication flow	Nur Standard flow. Direct access grants und andere Flows ausschalten
Valid redirect URIs	Die exakte Weiterleitungs-URL aus Kanroo, ohne Wildcards
Weitere URL-Felder, auch Web origins	Leer lassen

Speichere den Client. Setze unter Settings → Capability config die Option Require PKCE auf On und PKCE Method auf S256 und speichere. In Keycloak 26.7.3 liegen diese Optionen nicht im Tab Advanced.

Wähle unter Credentials als Client Authenticator Client Id and Secret und kopiere das Client Secret. Halte das Secret geheim.

2. Organisation verbinden

(vergrößern)

Prüfe dann in Kanroo unter Organisationseinstellungen → SSO, ob die Weiterleitungs-URL (Rahmen 1) mit der registrierten übereinstimmt. Gib dann diese Werte in die Felder des Identitätsanbieters ein (Rahmen 2):

Feld	Wert
Issuer-URL	Die URL Deines Realms, zum Beispiel https://login.example.com/realms/company
Client-ID	kanroo, passend zum Client oben
Client-Secret	Das aus Keycloak kopierte Secret

Nutze die Issuer-URL des Realms, nicht die URL /.well-known/openid-configuration.

Wähle Entwurf speichern (Rahmen 3) und dann Testen und verbinden. Melde Dich mit dem Keycloak-Benutzer des Inhabers an und gib dann den Bestätigungscode ein, den Kanroo per E-Mail schickt. Damit verknüpfst Du die Konten. Danach sollte der Identitätsanbieter Verbunden zeigen. Lass SSO erzwingen aus, bis Du den Zugriff für Mitglieder getestet hast.

3. Mitglieder aufnehmen und Anmeldung testen

Lade Mitglieder in die Organisation ein oder schalte den automatischen Beitritt (JIT) ein. Mit JIT kann jeder Benutzer, der sich über diesen Keycloak-Client anmelden kann, als Mitglied beitreten, im Rahmen der Limits der Organisation. Beschränke den Zugriff deshalb in Keycloak.

Mitglieder wählen auf der Anmeldeseite von Kanroo Mit SSO fortfahren und geben den Slug der Organisation ein. Oder sie öffnen den Link zur SSO-Anmeldung, den Du unter Organisationseinstellungen → SSO kopierst. Er wählt die Organisation schon vor. Bei ihrer ersten Anmeldung bestätigen Mitglieder ihre E-Mail-Adresse. Damit wird das Konto verknüpft. Liefert Keycloak keinen E-Mail-Claim, fragt Kanroo zuerst nach einer Adresse. Spätere Anmeldungen mit derselben verknüpften Identität wiederholen diese Bestätigung nicht.

Eine reine SSO-Sitzung zeigt Persönliche Bestätigung erforderlich anstelle von API-Schlüsseln, Sicherheitsaktivität und Webhooks. Brauchst Du diese Einstellungen, wähle Persönliches Konto bestätigen und gib den Code aus der E-Mail ein. Die Sitzung bleibt bestehen. Die Rolle in der Organisation ändert sich nicht.

4. SSO verlangen und Wiederherstellung sichern

Erzeuge als Inhaber die Wiederherstellungscodes, schließe die angeforderte E-Mail-Bestätigung ab, speichere die Codes sicher und bestätige, dass Du sie gespeichert hast. Schalte dann SSO erzwingen ein und bestätige. Die persönliche Anmeldung per E-Mail allein gibt dann keinen Zugriff mehr auf diese Organisation.

Ist Keycloak nicht erreichbar, melde Dich persönlich als Inhaber an und öffne /auth/company/recovery auf Deiner Kanroo-Instanz. Wähle die Organisation und sende einen neuen E-Mail-Bestätigungscode zusammen mit einem Wiederherstellungscode ab. Das schaltet SSO erzwingen aus, verbraucht diesen Wiederherstellungscode und behält die Konfiguration des Identitätsanbieters.

Entferne ausscheidende Mitglieder in Kanroo und deaktiviere zusätzlich ihren Keycloak-Zugang. JIT stellt eine entfernte Mitgliedschaft nicht automatisch wieder her. Erst eine ausdrückliche Einladung lässt das Mitglied wieder beitreten.

Mehrere Kanroo-Organisationen können denselben Realm und Client nutzen. Ein verknüpftes Mitglied meldet sich in derselben Browser-Sitzung einmal bei jeder Organisation an. Danach wechselt es in der Organisationsauswahl zwischen ihnen, ohne die Kontoverknüpfung zu wiederholen. Die SSO-Anmeldung gilt für jede Organisation 24 Stunden. Danach ist eine erneute Anmeldung über Keycloak nötig.

Referenz: Client-Konfiguration in Keycloak.