Keycloak installieren

Allgemein

Keycloak [1] ist eine Open Source Lösung, die ein Single Sign On für verschiedene Anwendungen ermöglicht. Dabei ermöglicht es sowohl die Identitätsverwaltung als auch Zugriffsmanagement.

Es kann die Benutzer entweder aus einem existierenden Verzeichnisdienst (LDAP, Active Directory) auslesen, oder die Gruppen und Benutzer auch selber verwalten.

Technische Details

Keycloak ist in Java geschrieben. Bisher lief es in einem Wildfly Server, aber seit Version 17 (Februar 2022) benutzt es Quarkus, welches ein leichtgewichtiges Java Framework ist.

Es gibt ein Ansible Skript, das die Installationsschritte für Keycloak automatisiert durchführt.

Die Quellen für das Ansible Skript können hier eingesehen werden: [2]

Installation

Was das Ansible Skript macht, lässt sich mit diesen Worten beschreiben:

• Es wird ein Linux Benutzer eingerichtet.
• Es wird eine Postgresql Datenbank eingerichtet.
• Es wird eine Domain aufgeschaltet.
• Es wird Keycloak als Zip Datei heruntergeladen, z.B. [3], und ins Verzeichnis $HOME/keycloak-17.0.0 entpackt.
• Dann werden ein paar Konfigurationen an der Datei keycloak/conf/keycloak.conf vorgenommen, um die Postgresql Datenbank einzurichten, und um den Proxymodus auf edge zu setzen und den Hostname zu setzen.
• Nun wird die Keycloak Instanz initialisiert, mit dem Befehl: keycloak/bin/kc.sh --cache=local --profile=prod build. Hierbei verhindert die Einstellung für den Cache, dass Keycloak versucht über das Netzwerk Verbindungen zu anderen Instanzen herzustellen.
• Es muss der Server einmal gestartet werden, während der Admin Benutzer mit Passwort in einer Umgebungsvariable gesetzt ist, damit der Benutzer eingerichtet wird.
• Es wird Monit konfiguriert, um den Keycloak Service zu starten, der auf einem internen Port lauscht.
• Es wird der Apache in der htaccess Datei konfiguriert, damit die aufgeschaltete Domain über Proxy auf den Keycloak Dienst verweist. Dabei ist wichtig, dass der Java Prozess mitbekommt, dass die Seite über https läuft. Dazu wird in der htaccess Datei der Wert X-Forwarded-Proto auf https gesetzt.

Keycloak mit Systemd

Sofern linger für den User schon verfügbar ist, kann auch Systemd verwendet werden. Zudem sollte im Vorfeld export XDG_RUNTIME_DIR=/run/user/$UID ausgeführt werden um Zugriff auf die Befehle zu erhalten.

Beispiel einer Systemd Konfiguration in .config/systemd/user/keycloak.service

[Unit]
Description=Keycloak

[Service]
Type=simple
Restart=on-abort
WorkingDirectory=/home/pacs/xyz00/users/login/keycloak
Environment=PROXY_ADDRESS_FORWARDING=true

# Für den ersten Start, um den Adminuser zu setzen
#Environment=KEYCLOAK_ADMIN=changeme
#Environment=KEYCLOAK_ADMIN_PASSWORD=changeme

# Die Option cache=local kann auch an anderer Stelle gesetzt werden.
# Hauptsache sie taucht auf, da es sonst zu Performance-Problemen wie
# Timeouts kommen kann.
ExecStart=/home/pacs/xyz00/users/login/keycloak/latest/bin/kc.sh start --cache=local

[Install]
# Achtung: multiuser.target würde hier zu Problemen führen
WantedBy=default.target

Beispiel einer Einrichtung

Diese Anleitung steht auch als Video auf Youtube zur Verfügung.

• Auf https://keycloak.example.org/admin anmelden.

Admin User einrichten

• Der auf der Kommandozeile angelegte Benutzer ist nur vorübergehend gültig.
• Bitte einen permanenten Admin User anlegen, mit den entsprechenden Rollen (role_admin und role_default-roles) ausstatten
• Login mit permanentem Admin durchführen
• Dann den temporären Benutzer löschen.

Realm einrichten

• Es soll nicht mit der master Realm gearbeitet werden, sondern sollte eine weitere Realm eingerichtet werden, z.B. "MeineFirma"
• Diese neue Realm wird dann ausgewählt

Benutzer einrichten

• Innerhalb der neuen Realm wird dann ein neuer Benutzer angelegt.
• Beim neuen Benutzer kann ausgewählt werden, dass die E-Mail bereits bestätigt ist.
• Nach dem Speichern des Benutzers kann man dann auch bei Credentials das Passwort setzen. Wenn es nur temporär ist, muss der Benutzer es bei der ersten Anmeldung ändern.
• Nun kann man sich als Administrator abmelden und sich als der Benutzer anmelden, auf https://keycloak.example.org/realms/MeineFirma/account/#/
  • Achtung: in anderen Anleitungen heißen die URLs /auth/realms usw, aber auth scheint nicht mehr Teil der Standardeinrichtung zu sein.
• Als Benutzer kann man sein Passwort ändern.
• Wieder abmelden, und wieder als Administrator anmelden.

Client einrichten

• Achtung: erst aus der Master Realm in die vorher angelegte Realm wechseln, z.B. "MeineFirma"
• Nun sollte ein Client hinzugefügt werden, also eine beliebige Anwendung, die mit Keycloak zusammenarbeiten soll
  • Als Client-Protokoll wählt man "OpenID Connect"
  • Die Client-ID kann so aussehen: my-nextcloud
  • Anwählen: 'Client Authentication', um den OID Typ auf 'Confidential Access Type' zu setzen.
  • Anwählen: 'Standard Flow', 'Implicit Flow' und 'Direct Access Grants'
• Eine Root Url eingeben, z.B. https://nextcloud.example.org
• Eine Valid Redirect URI eingeben, z.B. https://nextcloud.example.org/*
• Gültige Web Origins eingeben, z.B. https://nextcloud.example.org
• Speichern
• Unter Roles eine neue Rolle mit Namen admin anlegen.
• Wieder unter den Client Nextcloud gehen, und bei "Client Scopes" klicke auf "my-nextcloud-dedicated", und wähle dort "Add predefined Mapper". Wähle "client roles", und klicke auf "Add". Dann diesen neuen Mapper "client roles" Bearbeiten, und Client ID auf "my-nextcloud" setzen, und "Token Claim Name" mit "roles" setzen, und "Add to userinfo" auf "ON" stellen. Dann Speichern.
• Dann zu nochmal zu Client Scopes (im Client) gehen, und auf "my-nextcloud-dedicated" klicken, und dort im Reiter "Scope" die Option "Full Scope Allowed" abschalten.

• Dann unter Configure / Realm Settings, in General, bei Endpoints auf "OpenID Endpoint Configuration" klicken, dann wird eine Seite geöffnet, auf dieser URL: https://keycloak.example.org/realms/MeineFirma/.well-known/openid-configuration; diese Seite offen halten, wir brauchen daraus die Daten für die Nextcloud Einrichtung

Nextcloud einrichten (Einfach)

• Als Administrator anmelden, und bei den Apps die App "Social Login" installieren.
• Dann bei Einstellungen, unter Verwaltung, Social Login, die gewünschten Einstellungen vornehmen.
• Es sollte ein Kreuz sein bei: Anlegen eines Kontos verhindern, wenn die E-Mail-Adresse bereits von einem anderen Konto verwendet wird.
• Es sollte ein Kreuz sein bei: Verhindern, dass sich Benutzer ohne gemappte Gruppe anmelden können.
• Speichern
• Dann bei "Benutzerdefinierte OpenID Connect Anbindung" auf das Plus klicken
• Nun die Daten aus der "OpenID Endpoint Configuration" (siehe oben) übernehmen: Authorize URL, Token URL, User info URL, Logout URL
• Client ID: nc (Name des Clients in Keycloak)
• Client Secret: hier kommt das Secret hinein, das in Keycloak im Client unter Credentials "Client Secret" zu finden ist. Das kann über die Zwischenablage kopiert werden.
• Scope: openid
• Speichern

Nextcloud einrichten (Fortgeschritten)

Die folgende App wird mit Rücksicht auf Keycloak entwickelt und hat daher eine bessere Kompatibilität als das Beispiel oben. Allerdings gibt es hierfür keine Optionen in der Cloud, stattdessen wird die config.php direkt bearbeitet.

Plugin-Installation

1. Als Administrator die App "Nextcloud OIDC Login" installieren
2. Die Nextcloud Konfigurationsdatei unter pfad/zur/nextcloud/config/config.php öffnen und basierend auf dem Readme der App (Link aus Schritt #1) befüllen. Das könnte so aussehen:

'oidc_login_client_id' => 'nextcloud',
'oidc_login_client_secret' => 'bSIPDNUyTQpxmfOpXdwyoBP8nZDQZVuL', // Client Reiter "Credentials" in Keycloak
'oidc_login_provider_url' => 'https://login.mydomain.de/realms/myrealm',
'oidc_login_end_session_redirect' => true,
'oidc_login_logout_url' => 'https://cloud.mydomain.de/index.php/apps/oidc_login/oidc',
'oidc_login_auto_redirect' => true, // hiermit wird das Login-Formular übergangen um Leute weniger zu verwirren
'oidc_login_redir_fallback' => false,
'oidc_login_disable_registration' => false, // Nextcloud soll neue Keycloak Accounts akzeptieren
'oidc_login_attributes' => array(
'id' => 'preferred_username',
'mail' => 'email',
'groups' => 'ownCloudGroups',
'is_admin' => 'ownCloudAdmin',
),

In Keycloak nochmal alles kontrollieren

1. Client ID stimmt überein
2. unter Capability config ist Client authentication aktiv (damit wir ua. unser Secret bekommen)
3. Valid redirect URIs erlaubt https://cloud.mydomain.de/* – oder eine konkretere Adresse. Das Plus übernimmt die Einstellung aus Valid redirect URIs
4. Valid post logout redirect URIs erlaubt + oder https://cloud.mydomain.de/* – oder eine konkretere Adresse
5. Fine Grain OpenID Connect Configuration steht unter ID Token Signature Algorithm auf RS256 (Achtung, hier verrutscht man schnell weil die Einträge sich ähneln)

Gruppen Synchronisation über Rollen ermöglichen

Hierfür legen wir einen Mapper in nextcloud Client an. Anschließend müssen die tatsächlichen Gruppen mit Roles verknüpft werden. Hintergrund ist, dass Roles eigentlich für Berechtigungsmanagement gedacht sind, und Gruppen eigentlich nur User gruppieren sollen.

1. wir wechseln im Client nextcloud auf den Reiter Client scopes
2. wir wählen nextcloud-dedicated
3. Add mapper -> by configuration
   1. Type: User Client Role
   2. Name: ownCloudGroups
   3. Client ID
      1. Option #1: none – es werden alle Realm roles abgerufen. Das umfasst allerdings auch die Defaults wie uma_authorization, offline_access, default-user-roles und ist nicht immer gewünscht.
      2. Option #2: nextcloud hier können im Anschluss roles im Client angelegt und mit Groups oder Realm roles verknüpft werden.
   4. Multivalued: On
   5. Token Claim Name: ownCloudGroups
   6. Claim JSON Type: String
   7. die folgenden drei Optionen: On

Gruppen Synchronisation in der Praxis

Option #2: Client ID nextcloud

1. wir wechseln im Client nextcloud auf den Reiter Roles
2. Create role
   1. Wunschname
3. wir wechseln in Groups (Sidebar)
4. Create group
   1. Wunschname
5. In der Gruppe wechseln wir auf den Reiter Role mapping
   1. Assign role
   2. Im Dropdown welchseln wir auf den Filter by clients
   3. Wir wählen die gewünschte Rolle
   4. Unten Links, button Assign

Ab hier können wir die Gruppe normal zuweisen.

Benutzer einrichten

• Einen Benutzer im Keycloak einrichten, in der Realm "MeineFirma".
• Den Benutzer bearbeiten, und unter "Role Mappings", "Assign Role", "Filter by Clients", wähle "my-nextcloud admin" und klicke auf "Assign".

Fehler beheben

Problem: Gerade beim Experimentieren kommt schon mal die Meldung: "expected expression, got end of script"

• Lösung: Webseite aus der Firefox Chronik komplett löschen, oder in einem privaten Fenster öffnen, dann geht es wieder.

Generell kann es zu verwirrenden Fehlermeldungen kommen, wenn man sich versucht in einer verknüpften Anwendung einzuloggen aber beispielsweise noch als Admin im Master-Realm eingeloggt ist.

Logging

Um Fehler besser verstehen zu können, kann das Logging angeschaltet werden, siehe auch [4].

Dazu müssen im Start Skript bin/start-keycloak.sh folgende Parameter hinzugefügt werden:

--log-level=ERROR --log=file

Also sieht es z.B. so aus:

./bin/kc.sh start --http-port [...] --proxy edge --log-level=ERROR --log=file &

Nach dem Neustart von Keycloak gibt es dann die Datei keycloak/data/log/keycloak.log.

Links

• Webseite von Keycloak
• Ansible Playbook für Hostsharing
• Getting started with Keycloak
• OpenID Connect with Nextcloud and Keycloak von Janik Vonrotz, Oktober 2020
• Nextcloud SSO using Keycloak von Jörns Blog, Dezember 2019
• Erklärvideo auf Youtube zum Einrichten von Keycloak und Nextcloud
• Nextcloud App Social Login

---