grommunio-auth mit Keycloak: SSO und zentrale Anmeldung Schritt für Schritt

Kurzüberblick

Getestete Basis ist die openSUSE-basierte grommunio Appliance 2026.06.1. Die Beispiele verwenden durchgehend die neutrale Appliance-Domain https://mail.example.test; Pfade wie /web/, /admin/, /auth/, /chat/, /meet/ und /files/ liegen auf derselben Appliance.Dieser Beitrag zeigt, wie du grommunio-auth auf der bestehenden grommunio Appliance installierst und den grommunio-Realm in Keycloak sauber betreibst.

Meet-spezifische Adapter-Schritte gehören nicht hierher. Dieser Beitrag konzentriert sich auf grommunio-auth, grommunio Web, Keycloak, Federation, MFA, Discovery und Login-Flow.

Getestete Umgebung

• grommunio 2026 auf der openSUSE-basierten grommunio Appliance.

• Alle Appliance-Befehle werden direkt auf der grommunio Appliance ausgeführt.

• Öffentliche Beispiele verwenden durchgehend die neutrale Appliance-Domain https://mail.example.test.

Voraussetzungen

Ausgangspunkt ist eine installierte grommunio-Appliance, die über HTTPS unter https://mail.example.test erreichbar ist. Die Anleitung baut bewusst auf dem Installationsbeitrag der Serie auf: Erst die Groupware-Basis, danach Antispam, danach zentrale Anmeldung und MFA.

Für ein produktives Projekt brauchst du vor der Authentifizierungsumstellung einen festen FQDN, funktionierendes DNS, TLS, NTP, einen getesteten Admin-Zugang, aktuelle Pakete und einen Rückfallplan. SSO greift tief in den Loginpfad ein; deshalb prüfst du zuerst die Basisdienste und dokumentierst den aktuellen Zustand.

# Run on the grommunio appliance
hostname -f
cat /etc/os-release
rpm -q grommunio-auth grommunio-keycloak grommunio-web gromox grommunio-admin-api
systemctl is-active nginx php-fpm mariadb grommunio-keycloak gromox-http gromox-zcore
curl -k -I https://mail.example.test/web/

Erwartet wird der FQDN mail.example.test, aktive Dienste und ein HTTP-Header von grommunio Web. Wenn nginx oder grommunio-keycloak nicht aktiv sind, behebst du zuerst den Dienststatus, bevor du mit Keycloak-Clients oder MFA weitermachst.

Schritt-für-Schritt-Anleitung

2.1 Pakete installieren und Dienste prüfen

Installiere grommunio-auth und grommunio-keycloak aus den konfigurierten grommunio-Repositories. Danach prüfst du, ob Keycloak lokal auf Port 9080 läuft und ob nginx die öffentlichen Pfade unter /auth bereitstellt.

# Run on the grommunio appliance
zypper refresh
zypper install grommunio-auth grommunio-keycloak
systemctl enable --now grommunio-keycloak nginx php-fpm mariadb
systemctl status grommunio-keycloak --no-pager
ss -ltnp | grep ':9080'

Wenn Port 9080 nicht lauscht, prüfst du zuerst journalctl -u grommunio-keycloak. Häufige Ursachen sind Datenbankzugriff, falsche Hostname-Werte oder ein fehlender Keycloak-Build nach der Paketinstallation.

2.2 grommunio-auth Setup starten

Das Setup verbindet die grommunio-Datenbank, Keycloak und die Web-Komponenten. Starte es interaktiv auf der Appliance und arbeite die Felder nacheinander ab.

# Run on the grommunio appliance
/usr/share/grommunio-auth/setup-grommunio-auth.sh

Trage den FQDN ein, unter dem Benutzer später wirklich arbeiten. In der validierten Umgebung ist das https://mail.example.test. Verwende keine Fantasie-URL und keinen lokalen Port, wenn Benutzer später über den echten Hostnamen zugreifen.

Wähle als Provider die Keycloak-Integration und lasse das Setup die lokale grommunio-Keycloak-Anbindung vorbereiten. Danach validierst du die generierten Dateien und startest die relevanten Dienste neu.

2.3 Realm grommunio öffnen und nicht im master-Realm arbeiten

Melde dich an der Keycloak Admin Console an und wechsle in den Realm grommunio. Der master-Realm ist nur für die Keycloak-Administration da. Die eigentliche grommunio-Anwendung, Benutzer-Federation, MFA-Policy und Broker-Anbindung werden im Realm grommunio gepflegt.

https://mail.example.test/auth/admin/master/console/#/grommunio/realm-settings

Prüfe im Realm, dass Enabled aktiv ist und Require SSL auf External requests steht. Wenn du versehentlich im master-Realm arbeitest, landen Clients und Identity Provider an der falschen Stelle und grommunio Web findet später seine OIDC-Konfiguration nicht.

2.4 grommunio-Client prüfen

Öffne Clients im Realm grommunio. Dort muss der Client grommunio existieren. Dieser Client ist die OIDC-Anwendung, über die grommunio Web den Benutzer zu Keycloak leitet und anschließend Token prüft.

https://mail.example.test/auth/admin/master/console/#/grommunio/clients

Öffne den Client grommunio. In der getesteten Umgebung sind Root URL und Home URL auf https://mail.example.test:443/ gesetzt und die Redirect URI erlaubt https://mail.example.test/*. In einer echten Umgebung setzt du hier die reale öffentliche URL deiner grommunio-Installation.

https://mail.example.test/auth/admin/master/console/#/grommunio/clients/414cb6f4-2eb0-48b1-8fd7-941af3928e25/settings

Der Client ist confidential und verwendet Client ID plus Secret. Das Secret wird nicht veröffentlicht. Du kopierst es aus Keycloak und trägst es in /etc/gromox/keycloak.json ein.

https://mail.example.test/auth/admin/master/console/#/grommunio/clients/414cb6f4-2eb0-48b1-8fd7-941af3928e25/credentials

Prüfe außerdem die Client-Scopes. Standard-Scopes wie profile und email müssen verfügbar sein, weil grommunio Name und E-Mail-Adresse aus den OIDC-Claims benötigt. Der Audience-Mapper grommunio-audience sorgt dafür, dass Token die erwartete Audience für den grommunio-Client enthalten.

https://mail.example.test/auth/admin/master/console/#/grommunio/client-scopes

# Run on the grommunio appliance
/usr/share/grommunio-keycloak/bin/kcadm.sh get clients \
  -r grommunio \
  -q clientId=grommunio \
  --fields id,clientId,enabled,redirectUris,webOrigins,standardFlowEnabled,directAccessGrantsEnabled,serviceAccountsEnabled

/usr/share/grommunio-keycloak/bin/kcadm.sh get clients/<CLIENT_UUID>/protocol-mappers/models \
  -r grommunio \
  --fields name,protocolMapper,config

Erwartet wird ein aktivierter OIDC-Client grommunio mit Standard Flow, passender Redirect URI und einem oidc-audience-mapper. Wenn der Mapper fehlt, erhalten Anwendungen zwar ein Token, aber die Audience-Prüfung kann fehlschlagen.

2.5 User Federation aus grommunio prüfen

Die Benutzer kommen in dieser Installation aus der grommunio-Umgebung. Öffne User federation im Realm grommunio und prüfe, ob der Provider grommunio aktiviert ist.

https://mail.example.test/auth/admin/master/console/#/grommunio/user-federation

Im Detailbild muss der Provider enabled sein. Damit kann Keycloak Benutzer aus grommunio sichtbar machen, ohne sie als lokale Keycloak-Accounts doppelt zu pflegen.

https://mail.example.test/auth/admin/master/console/#/grommunio/user-federation/grommunio/55b1e099-3375-4d52-93c7-696b59efc6e3

Suche anschließend unter Users nach *. In der getesteten Umgebung erscheinen synthetische Benutzer wie alex@example.test, alice@example.test, bob@example.test und meet@example.test. In Produktion würdest du hier deine echten grommunio-Benutzer sehen.

https://mail.example.test/auth/admin/master/console/#/grommunio/users

2.6 MFA im grommunio-Realm aktivieren und Login prüfen

MFA gehört in den Realm grommunio, nicht in master. Öffne Authentication und arbeite mit dem Browser Flow beziehungsweise einer Kopie davon. Für produktive Umgebungen empfiehlt sich eine eigene Flow-Kopie, damit du Built-in-Flows nicht direkt veränderst.

https://mail.example.test/auth/admin/master/console/#/grommunio/authentication

Für den sauberen Einstieg aktivierst du MFA zuerst kontrolliert pro Benutzer. Öffne im Realm grommunio den Bereich Users, suche den gewünschten Benutzer, öffne den Benutzer und setze unter Required user actions die Aktion Configure OTP. Speichere den Benutzer danach.

1. Realm links oben auf grommunio stellen.

2. Users öffnen und den Benutzer suchen, zum Beispiel alex@example.test.

3. Benutzer öffnen und im Reiter Details beziehungsweise Required user actions Configure OTP hinzufügen.

4. Speichern und den Benutzer einmal vollständig abmelden lassen.

5. https://mail.example.test/web/ öffnen und den Login erneut ausführen.

6. Keycloak zeigt beim nächsten Login die TOTP-Einrichtung mit QR-Code. Der Benutzer scannt den Code mit einem Authenticator und bestätigt den ersten Einmalcode.

Wenn MFA für alle Benutzer verpflichtend werden soll, kopierst du im Realm grommunio den Browser Flow, ergänzt oder aktivierst die OTP-Prüfung als verpflichtenden Schritt und bindest diese Flow-Kopie unter Bindings als Browser flow. Das solltest du erst nach einem getesteten Break-Glass-Admin und dokumentiertem Rückweg aktivieren.

Danach rufst du grommunio Web auf. Der Benutzer wird über Keycloak authentifiziert und landet nach erfolgreichem Login wieder in grommunio Web.

https://mail.example.test/web/

https://mail.example.test/web/

https://mail.example.test/admin/

2.7 Bestehenden Keycloak als Broker anbinden

Wenn bereits ein zentraler Keycloak oder anderer OIDC-Provider existiert, bindest du ihn im Realm grommunio als Identity Provider ein. Im Lab wurde dafür ein zweiter Keycloak-Kontext auf derselben isolierten VM simuliert; in Produktion verwendest du den echten zentralen IdP mit seiner realen FQDN.

https://mail.example.test/auth/admin/master/console/#/grommunio/identity-providers

Der Alias im Beispiel lautet forgeone-keycloak. Wichtig sind die Redirect URI im grommunio-Realm und die OIDC-Endpunkte des Upstream-Providers: Authorization URL, Token URL, Logout URL und User Info URL.

https://mail.example.test/auth/admin/master/console/#/grommunio/identity-providers/keycloak-oidc/forgeone-keycloak/settings

Lege auf dem Upstream-Keycloak einen confidential Client für den Broker an. Als Redirect URI verwendest du die Redirect URI, die Keycloak im grommunio-Realm beim Identity Provider anzeigt. Danach trägst du Client ID und Secret beim Broker ein. Das Secret wird nicht im Artikel veröffentlicht.

Für Logout-Rücksprünge braucht grommunio in dieser validierten Umgebung einen nginx-Redirect. Er gehört in den nginx-server-Kontext der grommunio-Web-Instanz, also zu der vHost-Konfiguration, die auch die /auth-Pfade für mail.example.test ausliefert. In der Appliance werden die Keycloak-Proxy-Locations aus /usr/share/grommunio-common/nginx/locations.d/grommunio-auth.conf eingebunden; die lokale Ergänzung gehört in die eigene nginx-Konfiguration, nicht in keycloak.conf.

# /etc/nginx/conf.d/grommunio.conf
location ~ ^/auth/realms/grommunio/broker/[^/]+/endpoint/logout_response$ {
    return 302 $scheme://$host/web/;
}

# Run on the grommunio appliance
nginx -t
systemctl reload nginx
curl -k -I https://mail.example.test/auth/realms/grommunio/broker/forgeone-keycloak/endpoint/logout_response

Erwartet wird nach dem Reload ein HTTP 302 zurück auf /web/. Wenn stattdessen eine Keycloak-Fehlerseite erscheint, greift der nginx-Location-Block nicht im richtigen Server-Kontext oder wird von einer spezifischeren Location überholt.

2.8 Relevante Konfigurationsdateien prüfen

Nach dem Setup müssen die Dateien zueinander passen. Die öffentliche Browser-URL ist https://mail.example.test/auth/. Der interne Keycloak-Prozess lauscht lokal auf http://localhost:9080/auth und wird über nginx veröffentlicht.

# /etc/grommunio-keycloak/keycloak.conf
db=mariadb
proxy=edge
http-port=9080
http-relative-path=/auth
http-host=localhost
http-enabled=true
db-username=grommunio_keycloak
db-password=<REDACTED>
db-url-database=grommunio_keycloak
db-url-host=localhost
hostname=mail.example.test
hostname-strict=false
hostname-strict-https=false
proxy-headers=xforwarded

# /etc/grommunio-keycloak/grommunio.properties
grommunio.db-kind=org.mariadb.jdbc.Driver
grommunio.jdbc-url=jdbc:mariadb://localhost:3306/grommunio
grommunio.username=groauth
grommunio.password=<REDACTED>

{
  "realm": "grommunio",
  "auth-server-url": "https://mail.example.test/auth/",
  "ssl-required": "external",
  "resource": "grommunio",
  "verify-token-audience": true,
  "credentials": {
    "secret": "<CLIENT_SECRET>"
  },
  "confidential-port": 0,
  "policy-enforcer": {
    "credentials": {}
  }
}

# /etc/grommunio-common/nginx/auth_allow.conf
allow 10.0.2.0/24;
allow 127.0.0.1;

Die Datei /etc/gromox/keycloak.json muss für grommunio Web lesbar sein, aber nicht weltlesbar. In der validierten Umgebung ist die Datei root:groweb und 0640. Wenn die Gruppe oder Berechtigung falsch ist, kann der Login trotz korrektem Keycloak-Client scheitern.

# Run on the grommunio appliance
stat -c '%U:%G %a %n' /etc/gromox/keycloak.json /etc/grommunio-keycloak/keycloak.conf /etc/grommunio-keycloak/grommunio.properties
systemctl restart grommunio-keycloak nginx php-fpm gromox-http gromox-zcore
systemctl is-active grommunio-keycloak nginx php-fpm gromox-http gromox-zcore

2.9 Token, Discovery und Introspection prüfen

Vor der Abnahme prüfst du Discovery, Token-Ausstellung und Introspection. Damit stellst du sicher, dass nicht nur die UI funktioniert, sondern auch die OIDC-Grundlage für grommunio Web stimmt.

# Run on the grommunio appliance
curl -k https://mail.example.test/auth/realms/grommunio/.well-known/openid-configuration | jq '.issuer,.authorization_endpoint,.token_endpoint,.introspection_endpoint'

TOKEN_RESPONSE=$(curl -ks \
  -d grant_type=password \
  -d client_id=grommunio \
  -d client_secret='<CLIENT_SECRET>' \
  -d username='alex@example.test' \
  -d password='<USER_PASSWORD>' \
  -d scope='openid profile email' \
  https://mail.example.test/auth/realms/grommunio/protocol/openid-connect/token)

echo "$TOKEN_RESPONSE" | jq -r '.token_type,.expires_in'

Erwartet werden gültige OIDC-Endpunkte, ein Bearer Token und eine Ablaufzeit. Wenn ein invalid_client erscheint, stimmen Client ID oder Secret nicht. Wenn invalid_grant erscheint, prüfst du Benutzerpasswort, MFA-Status und Required Actions.

2.10 Audience-Mapper für Token-Introspection ergänzen

Wenn grommunio Web ein Access Token gegen Keycloak introspektiert, reicht azp=grommunio allein nicht aus. Das Token muss den grommunio-Client auch als Audience enthalten. Fehlt diese Audience, kann Keycloak ein INTROSPECT_TOKEN_ERROR mit invalid_token loggen, obwohl der Login-Flow auf den ersten Blick korrekt wirkt.

Öffne dafür im Realm grommunio den Pfad Clients -> grommunio -> Client scopes -> grommunio-dedicated -> Mappers -> Add mapper -> By configuration -> Audience. Lege dort einen Mapper an, der die Client-Audience grommunio in Access Token und Token-Introspection schreibt. ID Token und Lightweight Access Token bleiben dafür deaktiviert.

Mapper type: Audience
Name: grommunio-self-audience
Include Client Audience: grommunio
Add to ID token: Off
Add to access token: On
Add to lightweight access token: Off
Add to token introspection: On

Danach holst du ein neues Token. Ein altes Token ändert sich nicht nachträglich. Vor der Korrektur enthält der Token-Body typischerweise azp=grommunio, aber keine passende aud-Liste für grommunio. Nach der Korrektur muss aud den Wert grommunio enthalten.

# Run on the grommunio appliance, placeholders intentionally redacted
ACCESS_TOKEN='<ACCESS_TOKEN>'
printf '%s' "$ACCESS_TOKEN" | awk -F. '{print $2}' | base64 -d -i 2>/dev/null | jq '{azp,aud,scope}'

curl -k -sS -X POST \
  'https://mail.example.test/auth/realms/grommunio/protocol/openid-connect/token/introspect' \
  -u 'grommunio:<CLIENT_SECRET>' \
  -d "token=$ACCESS_TOKEN" | jq '{active,client_id,username,aud,azp,iss}'

Die Abnahme ist erst sauber, wenn Introspection active=true liefert und aud=grommunio sichtbar ist. Wenn die Introspection weiterhin invalid_token meldet, prüfst du, ob der Mapper wirklich im Scope grommunio-dedicated des Clients grommunio liegt und ob ein neues Access Token verwendet wurde.

2.11 localhost:5000, gromox-http und IPv6-Loopback prüfen

Ein häufiger Stolperstein ist nicht Keycloak selbst, sondern die lokale grommunio-Kommunikation. In der validierten Appliance löst localhost zuerst auf ::1 auf, und gromox-http lauscht auf [::1]:5000. Wenn der lokale IPv6-Loopback deaktiviert oder gebrochen ist, können interne Komponenten auf localhost:5000 scheitern. Das ist kein Argument dafür, extern IPv6 freizuschalten; es betrifft die lokale Loopback-Kommunikation auf der Appliance.

# Run on the grommunio appliance
getent hosts localhost
getent ahosts localhost
sysctl net.ipv6.conf.all.disable_ipv6 net.ipv6.conf.default.disable_ipv6 net.ipv6.conf.lo.disable_ipv6
ip addr show lo
ss -tlnp | grep ':5000'
journalctl -u gromox-http -u gromox-zcore --since '30 minutes ago' --no-pager

Erwartet wird, dass lo die Adresse ::1/128 besitzt und gromox-http auf [::1]:5000 lauscht. Zusätzlich sollte /etc/gromox/gromox.cfg beziehungsweise die aktuell noch ausgewertete http.cfg zur laufenden gromox-Version passen. Wenn hier eine Abweichung auftaucht, korrigierst du zuerst Loopback, Dienststatus und gromox-Konfiguration, bevor du Keycloak-Claims suchst.

2.13 Reboot- und Persistenztest

Zum Abschluss startest du die Appliance neu und wiederholst die Kernprüfungen. SSO ist erst dann abgenommen, wenn Dienste, nginx, Discovery und Web-Login nach einem Neustart ohne manuelle Nacharbeit funktionieren.

# Run on the grommunio appliance
systemctl reboot

# After reconnecting
systemctl is-active grommunio-keycloak nginx php-fpm mariadb gromox-http gromox-zcore
curl -k -I https://mail.example.test/auth/realms/grommunio/.well-known/openid-configuration
curl -k -I https://mail.example.test/web/

2.12 Abschließender Login-Test mit grommunio Web

Der Auth-Test endet nicht bei einem Keycloak-Token. Für die praktische Abnahme wurde der komplette Benutzerweg definiert: https://mail.example.test/web/ öffnen, Redirect zu grommunio-auth/Keycloak, Login, MFA falls erzwungen, Redirect zurück nach grommunio Web, sichtbare Mailbox und Logout. Nur dieser Rückweg zählt als End-to-End-erfüllt.

• ✓ grommunio Web vor Login: Der Webclient leitet bei geschützten Bereichen zum vorgesehenen Loginweg.

• ✓ Keycloak/grommunio-auth Login: Der Benutzer kann sich im Realm grommunio anmelden.

• ✓ MFA: Eine Required Action oder MFA-Richtlinie wird abgefragt, wenn sie aktiviert ist.

• ✓ Redirect zurück nach grommunio Web: Nach erfolgreichem Login landet der Benutzer wieder im Webclient.

• ✓ Mailbox sichtbar: Das Postfach ist nach dem Login erreichbar.

• ✓ Logout: Abmelden beendet die Sitzung nachvollziehbar.

Ergebniskontrolle / Technische Abnahme

Typische Fehler und Troubleshooting

Falscher Realm

Fehlerbild: Der Client ist scheinbar angelegt, grommunio Web leitet aber nicht korrekt zu Keycloak oder findet den Client nicht. Ursache ist häufig, dass im master-Realm gearbeitet wurde. Lösung: Im Realm-Wechsler grommunio auswählen und Clients, User Federation, Authentication und Identity Providers dort prüfen.

Redirect URI passt nicht

Fehlerbild: Keycloak meldet invalid_redirect_uri. Ursache ist eine URL-Abweichung zwischen Browser, nginx und Client-Konfiguration. Lösung: Root URL, Home URL, Valid Redirect URIs und /etc/gromox/keycloak.json auf denselben FQDN bringen.

Client Secret falsch oder nicht lesbar

Fehlerbild: invalid_client oder Login-Schleife. Ursache ist meist ein falsches Secret in /etc/gromox/keycloak.json oder eine zu restriktive Dateiberechtigung. Lösung: Secret im Credentials-Tab neu kopieren, Datei auf root:groweb 0640 setzen und Dienste neu starten.

Broker-Logout endet auf einer Keycloak-Seite

Fehlerbild: Nach Logout über den vorgeschalteten Identity Provider landet der Benutzer nicht zurück in grommunio Web. Lösung: Den nginx-Redirect für /auth/realms/grommunio/broker/<alias>/endpoint/logout_response im grommunio-vHost setzen, nginx -t ausführen und nginx neu laden.

Token-Introspection scheitert mit INTROSPECT_TOKEN_ERROR

Fehlerbild: Keycloak protokolliert invalid_token bei der Introspection, obwohl azp=grommunio im Token steht. Ursache: Der grommunio-Client fehlt als aud im Access Token. Lösung: Audience-Mapper grommunio-self-audience im grommunio-dedicated Scope des Clients grommunio anlegen, neues Token ausstellen und Introspection erneut prüfen.

localhost:5000 ist nicht erreichbar

Fehlerbild: Login oder interne grommunio-Kommunikation scheitert rund um localhost:5000. Ursache: gromox-http lauscht lokal auf [::1]:5000, aber der IPv6-Loopback oder die Namensauflösung für localhost passt nicht. Lösung: ::1 auf lo, getent hosts localhost, gromox-http-Status und gromox-Konfiguration prüfen. Externe IPv6-Erreichbarkeit ist dafür nicht erforderlich.

Fazit und Ausblick

Damit steht eine produktiv nachvollziehbare SSO-Basis für grommunio: Keycloak läuft hinter nginx, der Realm grommunio enthält Client, Federation, MFA-Flow, Audience-Mapper und optionalen Broker, und grommunio Web kann Benutzer zentral anmelden.

Der nächste logische Schritt in der Serie ist die gezielte SSO-Anbindung einzelner grommunio-Bausteine wie Meet, Chat und Files. Jeder Baustein bekommt dabei seinen eigenen Client, seine eigenen Redirects und eine eigene Abnahme, damit die Konfiguration wartbar bleibt.

Weiter in der Serie:grommunio Meet 2026 Schritt für Schritt,grommunio Chat für Teams und Mandanten betreibenundgrommunio Files und Office integrieren.