SNLO – Spittank.net Ladeorganisation – OIDC-Konfiguration¶

SNLO – Spittank.net Ladeorganisation unterstützt OpenID Connect als serverseitigen Authorization-Code-Flow mit PKCE S256. Nutzer- und Administratorrechte werden aus Gruppen-Claims des Identity Providers abgeleitet.

1. OIDC-Client im Identity Provider¶

Der Client muss als vertraulicher Web-Client eingerichtet werden und den Authorization-Code-Flow erlauben.

Exakte Redirect-URI:

<APP_ORIGIN>/api/auth/oidc/callback

Beispiel:

https://snlo.de/api/auth/oidc/callback

Empfohlene Scopes:

openid profile email groups

Der Provider muss mindestens liefern:

• iss, sub, aud, exp und iat im ID-Token,
• email, standardmäßig mit email_verified=true,
• einen Anzeigenamen über name oder ersatzweise preferred_username,
• die Gruppen im ID-Token oder über den UserInfo-Endpunkt.

2. SNLO konfigurieren¶

Beispiel für .env:

APP_ORIGIN=https://snlo.de
COOKIE_SECURE=true

OIDC_ENABLED=true
OIDC_ISSUER_URL=https://sso.example.org/realms/home
OIDC_CLIENT_ID=snlo
OIDC_CLIENT_SECRET=ein-langes-client-secret
OIDC_SCOPES=openid profile email groups
OIDC_PROVIDER_NAME=Mein SSO

OIDC_GROUPS_CLAIM=groups
OIDC_USER_GROUPS=snlo-users
OIDC_ADMIN_GROUPS=snlo-admins

OIDC_AUTO_PROVISION=true
OIDC_LINK_BY_EMAIL=true
OIDC_AUTO_REDIRECT=true
OIDC_LOCAL_LOGIN_ENABLED=true

Danach:

docker compose up -d --build

3. Gruppen und Rollen¶

Gruppen werden exakt, aber ohne Beachtung der Groß-/Kleinschreibung verglichen.

Mitglied in OIDC_ADMIN_GROUPS -> ADMIN
sonst Mitglied in OIDC_USER_GROUPS -> USER
sonst -> Anmeldung abgelehnt

Ist ein Konto in beiden Gruppen, hat die Administratorgruppe Vorrang. Mehrere erlaubte Gruppen werden kommasepariert angegeben:

OIDC_USER_GROUPS=snlo-users,familie-laden
OIDC_ADMIN_GROUPS=snlo-admins,infra-admins

Der Claim-Pfad unterstützt:

OIDC_GROUPS_CLAIM=groups
OIDC_GROUPS_CLAIM=realm_access.roles
OIDC_GROUPS_CLAIM=/realm_access/roles

Mehrere mögliche Claim-Pfade können ebenfalls kommasepariert werden:

OIDC_GROUPS_CLAIM=groups,realm_access.roles

Bei jeder OIDC-Anmeldung synchronisiert SNLO Anzeigename, E-Mail-Adresse, Gruppen und Rolle. Normale Browser-Sitzungen enden spätestens mit dem früheren Zeitpunkt aus ID-Token-Ablauf und SESSION_TTL_HOURS. Installierte PWAs können dagegen eine eigene langlebige SNLO-Anwendungssitzung verwenden; Gruppenänderungen beim Identity Provider werden dort bei der nächsten OIDC-Anmeldung übernommen.

4. Automatische Nutzeranlage und Kontoverknüpfung¶

OIDC_AUTO_PROVISION=true

legt bei der ersten zulässigen Anmeldung automatisch einen Nutzer ohne lokales Passwort an.

OIDC_LINK_BY_EMAIL=true

verknüpft ein bereits vorhandenes lokales Konto mit derselben verifizierten E-Mail-Adresse. Das lokale Passwort bleibt dabei erhalten. Eine E-Mail-Adresse kann nicht mit zwei verschiedenen OIDC-Identitäten verbunden werden.

Mit:

OIDC_AUTO_PROVISION=false
OIDC_LINK_BY_EMAIL=true

muss der Nutzer zuvor lokal mit derselben E-Mail-Adresse angelegt werden.

Standardmäßig verlangt SNLO email_verified=true:

OIDC_REQUIRE_VERIFIED_EMAIL=true

Nur wenn der Provider diesen Standard-Claim nachweislich nicht liefert, kann die Prüfung deaktiviert werden. Das schwächt die Sicherheit der automatischen E-Mail-Verknüpfung.

5. Direkte Weiterleitung und lokaler Zugang¶

OIDC_AUTO_REDIRECT=true

leitet einen nicht angemeldeten Browser beim Aufruf von / direkt zum Identity Provider weiter.

Bleibt der lokale Login aktiviert, ist er trotz Direktweiterleitung erreichbar unter:

https://snlo.de/?local=1

Für reinen SSO-Betrieb:

OIDC_LOCAL_LOGIN_ENABLED=false

Dann existiert kein lokaler Anmeldeweg. Diese Einstellung sollte erst aktiviert werden, nachdem OIDC und die Administratorgruppe praktisch getestet wurden.

Die Schaltfläche „Abmelden“ beendet die SNLO-Sitzung. Sie beendet nicht automatisch die Sitzung beim Identity Provider. Durch /?local=1 wird nach dem lokalen Logout eine sofortige automatische SSO-Neuanmeldung vermieden.

6. PWA-Sitzungen¶

Eine installierte PWA startet über /?pwa=1. Bei einer anschließend durchgeführten Anmeldung markiert SNLO die Sitzung als PWA-Sitzung. Sie verwendet:

PWA_SESSION_TTL_DAYS=3650

und wird bei jedem erfolgreichen PWA-Start erneut ab dem aktuellen Zeitpunkt verlängert. Damit bleibt die App auf einem persönlichen Gerät praktisch bis zum aktiven Abmelden angemeldet. Eine normale Browser-Sitzung wird nicht ohne erneute Anmeldung in eine langlebige PWA-Sitzung umgewandelt.

Der OIDC-ID-Token wird beim Login weiterhin vollständig validiert; danach handelt es sich um eine eigenständige SNLO-Anwendungssitzung. Wer eine kürzere Bindung an aktuelle IdP-Gruppen benötigt, reduziert PWA_SESSION_TTL_DAYS entsprechend. Ein in SNLO deaktiviertes Konto verliert unabhängig davon sofort den Zugriff. Bei Browser und installierter PWA derselben Origin wird der HTTP-Cookie-Speicher je nach Plattform geteilt; nach einer PWA-Anmeldung kann die langlebige Sitzung deshalb auch im normalen Browser derselben Geräte-/Browserumgebung gelten.

7. Weitere Einstellungen¶

Client-Secret und Gruppenregeln werden ausschließlich über die Prozessumgebung konfiguriert. Das Client-Secret wird weder über die API ausgegeben noch in PostgreSQL gespeichert.

8. Sicherheitsprüfung vor Produktivbetrieb¶

1. HTTPS und COOKIE_SECURE=true aktivieren.
2. Redirect-URI exakt auf APP_ORIGIN abstimmen.
3. Anmeldung mit Nutzergruppe testen.
4. Anmeldung mit Administratorgruppe testen.
5. Konto ohne erlaubte Gruppe testen; die Anmeldung muss abgewiesen werden.
6. Rollenwechsel im Identity Provider und erneute Anmeldung testen.
7. Erst danach optional den lokalen Login deaktivieren.
8. .env wie ein Geheimnis sichern und Dateirechte einschränken.