====== Keycloak ======
SSH Zugang grundsätzlich via: ssh opa02-jusos_keycloak@h11.hostsharing.net
Passwort siehe [[Bitwarden]]

===== Neue Doku (vor 2024) ======
Generell ist die Keycloak Dokumentation zu empfehlen: [[https://www.keycloak.org/documentation]]
Keycloak wird laufend weiterentwickelt und Foren-Einträge sind häufig veraltet, während die Hauptdokumentation bei Google schlecht indiziert ist.

==== Deployment ====
Aktuelle Version ist immer in <code>~/keycloak</code> gelinkt (in der Regel auf die größte Versionsnummer).
=== Start/Build-Script ===
<code>~/kc-build-script.sh</code>
<code>
Stand 2024-01-28
#!/bin/bash

set -e #stop on error
set -x #prints commands

cd $HOME/keycloak
./bin/kc.sh build --metrics-enabled=true --cache=local
systemctl --user restart keycloak
sleep 1
systemctl --user status keycloak
</code>

=== Unit-Skript ===
Hält den Dienst dauerhaft alive
<code>~/.config/systemd/user/keycloak.service</code>
<code>
Stand 2024-01-28
[Unit]
Description=Keycloak Open Source Identity and Access Management

[Service]
Type=simple
Restart=always
RestartSec=2s
ExecStart=%h/keycloak/bin/kc.sh start --optimized --spi-connections-jpa-quarkus-migration-strategy=update

[Install]
WantedBy=multi-user.target
</code>

==== Server-Konfiguration ====
=== Konfigurationsdatei ===
<code>~/keycloak/conf/keycloak.conf</code>
Host: 127.0.0.1
Port: 9005

=== Log ===
<code>~/keycloak/keycloak.log</code>

=== Theme ===
Wir überschreiben zur Zeit nur das Login-Theme (SSO). Das Theme ist ein Clon vom Keycloakv1-Theme (/lib/lib/main/org.keycloak.keycloak-themes-xx.xx.x.jar). Dieses erbt vom Basis-Theme. Die Jar-Datei kann mit einem Zip-Programm geöffnet werden.

Letztlich haben wir primär das Hintergrundbild ausgetauscht und ein paar Kleinigkeiten verändert. 
Unser Theme liegt als „Rote Tools v4“ im Theme-Ordner.

ToDo: Theme vernünftig vom KC-V1-Theme erben lassen.

== Achtung, Stolperfallen == 
  * Neues Theme lädt nicht?
    * Es können für jeden Client eigene Themes geladen werden, die das globale Theme überschreiben.
    * Keycloak mit folgendem Befehl neu starten: <code>start --spi-theme-static-max-age=-1 --spi-theme-cache-themes=false --spi-theme-cache-templates=false</code>


==== Webkonfiguration ====
Zugang unter [[https://login.rote.tools/]].

=== Realms ===
Keycloak erlaubt Realms für verschiedene Nutzer:innen-Gruppen. Unsere Produktiv-Umgebung liegt in "user". 

=== Username-Validation ===
Um eine Username-Validation bei der Registrierung zu ermöglichen, haben wir das Preview-Feature „DECLARATIVE_USER_PROFILE“ aktiviert. 

Unter Realm-Settings > User Profile > username läuft die Validation via pattern:
<code>{"pattern":"^[a-z0-9.\\-_]{3,63}$","error-message":"username-validation-error"}</code>

Die Errormessage wird über die Sprachkonfiguration Realm-Settings > Localization ausgegeben.



----

===== Alte Doku (vor 2023) =======
==== Links für Dienste (open id discovery url) ====
  https://keycloak.jusos.rocks/realms/master/.well-known/openid-configuration

==== Server Neustart ==== 
Es liegt im Home Verzeichnis des Users ein start-script.sh und ein stop-script.sh. Mit diesen kann der Server neu gestartet werden.

Aktuell werden die Debug-logs aus der Ausgabe weggeworfen. Sollten diese mal wichtig sein lässt sich der Server alternativ temporär auch mit

  ~/keycloak/bin/kc.sh start --http-port 8080 --http-host 127.0.0.1 --proxy edge --features=preview

gestartet werden - der logoutput landet dann im stdout in der Konsole

==== Reverse-Proxy ==== 
Unter 
  ~/doms/keycloak.jusos.rocks/htdocs-ssl/.htaccess
ist der Proxy definiert der den output der Java-Anwendung vom Localhost ins Netz durchreicht. Dateien die mit dem korrekten Pfad im htdocs-ssl ordner gefunden werden, werden prioritär behandelt. 


===== Theme =====
Zur Zeit existiert ein rudimentäres Custom-Juso-Theme auf Skeleton-Basis für die SSO-Login/Register-Seite:
  ~/keycloak/themes/juso-template/

Das Theme extended das Basis-Template um die CSS-Dateien style.css, skeleton.css und normalize.css. An den HTML-Grundlagen wurde nichts angepasst.

==== Theme-Entwicklung ====
Um am Theme zu entwickeln, empfiehlt sich eine lokale Standalone-Instanz aufzusetzen und mit folgenden Optionen zu starten:
  bin/kc.sh start-dev --spi-theme-static-max-age=-1 --spi-theme-cache-themes=false --spi-theme-cache-templates=false

==== Offene TODOs ====
  * Weg migrieren vom Master Realm, der sollte nur für KC selbst verwendet werden, Test Realms für den API Test
  * Theme mobile optimieren
  * Rausfinden wie man Gruppen mit den fine grant permissions selbstverwaltet organisieren kann
  * Prüfen ob andere Loginvarianten sinnvoll / nötig sind (TOPT, Magic Link) 
  * Rechte Management aufräumen, das man granularer pro Client Admin rechte vergeben kann
  * mehr Attribute ausliefern. Wie bspw. Quotas, Picture URL uvm