Keycloak: ein Konto für alles

Ein Konto für alles: Mit Keycloak meldet man sich einmal an und ist in Paperless, Proxmox, WordPress und Co. gleichzeitig angemeldet. Dieses Kapitel ist optional, macht den Alltag aber deutlich angenehmer.

Was ist Keycloak?

Keycloak ist ein Open-Source-Identity Provider. Statt dass jedes System seine eigenen Benutzer und Passwörter verwaltet, fragen alle bei Keycloak nach, wer sich gerade anmeldet. Dafür gibt es zwei Standards: OpenID Connect (OIDC) und SAML. Wer das Amt wechselt, wird an einer Stelle angelegt oder gesperrt, und Zwei-Faktor-Anmeldung gilt für alle Systeme auf einmal.

Realm	ein abgeschlossener Bereich mit eigenen Benutzern, z. B. `verein`
Client	eine Anwendung, die Keycloak zur Anmeldung nutzt, z. B. Paperless
Gruppe / Rolle	z. B. „Vorstand“ oder „Kasse“, wird an die Anwendungen weitergegeben

Welche Systeme mitmachen

System	Anbindung	Hinweis
Proxmox	OIDC, eingebaut	Rechenzentrum → Berechtigungen → Realms
Paperless-ngx	OIDC, eingebaut	über Umgebungsvariablen, siehe unten
WordPress	OIDC per Plugin	z. B. „OpenID Connect Generic Client“
ResourceSpace	SAML, eingebaut	über das mitgelieferte SAML-Plugin
Nextcloud	OIDC per App	offizielle App „OpenID Connect user backend“
Vaultwarden	bewusst nicht	Der Tresor bleibt mit eigenem Master-Passwort getrennt
Uptime Kuma	nein	eigenes Admin-Konto, nur für die Technik
n8n	nur mit Lizenz	SSO gehört bei n8n zur kostenpflichtigen Enterprise-Version
Admidio	siehe Hinweis	Admidio ist selbst die Mitgliederverwaltung, siehe unten

Keycloak oder Admidio? Im Verein liegen die Mitglieder ohnehin in Admidio. Neuere Admidio-Versionen können nach meinem Stand selbst als Anmeldedienst (SSO-Anbieter) auftreten. Für kleine Vereine kann das reichen, und man spart sich einen Dienst. Keycloak lohnt sich, wenn auch Nicht-Mitglieder wie Dienstleister oder Partner Zugänge brauchen, oder wenn man feinere Regeln und Zwei-Faktor für alles zentral will. Vor der Entscheidung prüfe ich, was die eingesetzte Admidio-Version wirklich kann.

Installation

Keycloak bekommt den Container login (ID 101) aus der Vorlage, mit 2 Kernen, 2 GB Arbeitsspeicher und den Features Nesting und keyctl für Docker. Dann Docker wie im Kapitel Paperless beschrieben installieren.

# /opt/keycloak/compose.yaml
services:
  db:
    image: postgres:16
    restart: unless-stopped
    environment:
      POSTGRES_DB: keycloak
      POSTGRES_USER: keycloak
      POSTGRES_PASSWORD: ${DB_PASSWORD}
    volumes:
      - pgdata:/var/lib/postgresql/data

  keycloak:
    image: quay.io/keycloak/keycloak:26
    restart: unless-stopped
    command: start
    depends_on: [db]
    environment:
      KC_DB: postgres
      KC_DB_URL: jdbc:postgresql://db:5432/keycloak
      KC_DB_USERNAME: keycloak
      KC_DB_PASSWORD: ${DB_PASSWORD}
      KC_HOSTNAME: https://login.meinverein.de
      KC_PROXY_HEADERS: xforwarded
      KC_HTTP_ENABLED: "true"
      KC_BOOTSTRAP_ADMIN_USERNAME: admin
      KC_BOOTSTRAP_ADMIN_PASSWORD: ${ADMIN_PASSWORD}
    ports:
      - "8080:8080"

volumes:
  pgdata:

cd /opt/keycloak
cat > .env <<EOF
DB_PASSWORD=$(openssl rand -hex 16)
ADMIN_PASSWORD=$(openssl rand -base64 18)
EOF
docker compose up -d
docker compose logs -f keycloak    # warten bis „Listening on http://0.0.0.0:8080“

Im Reverse Proxy login.meinverein.de auf http://192.168.178.31:8080 zeigen lassen. Danach unter https://login.meinverein.de mit dem Bootstrap-Admin anmelden, sofort einen eigenen Administrator mit Zwei-Faktor anlegen und den Bootstrap-Admin löschen.

Einrichtung

Einen Realm verein anlegen. Der Realm master bleibt nur für die Verwaltung von Keycloak selbst.
Gruppen nach Ämtern anlegen: Vorstand, Kasse, Presse, Jugend.
Unter Authentication Zwei-Faktor (OTP) für alle verpflichtend machen.
Pro Anwendung einen Client anlegen. Keycloak zeigt danach Client-ID und Client-Secret, die in die Anwendung eingetragen werden.

Beispiel: Paperless an Keycloak anbinden

In Keycloak einen Client paperless anlegen, „Client authentication“ an, Redirect-URI https://docs.meinverein.de/accounts/oidc/keycloak/login/callback/. In der compose.yaml von Paperless kommen diese Variablen dazu:

PAPERLESS_APPS: allauth.socialaccount.providers.openid_connect
PAPERLESS_SOCIALACCOUNT_PROVIDERS: >-
  {"openid_connect": {"APPS": [{
    "provider_id": "keycloak",
    "name": "Vereinskonto",
    "client_id": "paperless",
    "secret": "HIER-DAS-CLIENT-SECRET",
    "settings": {"server_url": "https://login.meinverein.de/realms/verein/.well-known/openid-configuration"}
  }]}}

Auf der Anmeldeseite von Paperless erscheint danach der Knopf „Vereinskonto“.