Download the PHP package marcel-maqsood/session-auth-middleware without Composer

Mezzio Session Auth Middleware

Die SessionAuthMiddleware (SAM) ist eine PSR-15-Middleware für Laminas/Mezzio-Anwendungen. Sie verbindet Session-basierte Authentifizierung, Login-Routen, Datenbank-gestützte Session-Fingerprints und ein gruppenbasiertes Berechtigungssystem.

SAM prüft nicht nur, ob ein Benutzer angemeldet ist. Sie stellt auch sicher, dass die Session noch gültig ist, dass kein neueres Login auf einem anderen Gerät existiert und dass der angemeldete Benutzer die Permission der aktuell angefragten Route besitzt.

Installation

Das Paket registriert seinen ConfigProvider automatisch über Laminas/Mezzio. Die projektbezogenen Konfigurationen müssen trotzdem in die Anwendung übernommen und angepasst werden.

Was SAM macht

• schützt einzelne Routen oder optional die gesamte Pipeline
• nutzt Mezzio Sessions und mezzio/mezzio-authentication-session
• authentifiziert Benutzer über MazeDEV\SessionAuth\Repository\PDORepository
• schreibt pro Login einen Session-Hash und einen Session-Zeitstempel in die Login-Tabelle
• verhindert parallele Logins mit demselben Account, indem ein neuer Login ältere Sessions ungültig macht
• prüft die Session gegen Browser/IP/User-Agent/Salt-Fingerprint
• verlängert den Session-Zeitstempel während aktiver Nutzung
• leitet nicht angemeldete Benutzer auf die passende Fallback- oder Login-Route
• prüft Permissions über Gruppen und Gruppen-Permission-Zuordnungen
• unterstützt mehrere Auth-Bereiche, z. B. user und admin, über Table Overrides
• kann Benutzernamen und Benutzer-/Permission-Daten an Requests weiterreichen
• stellt Handler für Login, Logout, Passwort-Reset und Account-Erstellung bereit
• legt Fehlertexte kurzzeitig im Cookie error ab, damit Login-Templates sie anzeigen können

Grundkonfiguration

Die mitgelieferten Dateien in config/ sind als Vorlage für config/autoload/ einer Mezzio-Anwendung gedacht:

• config/dependencies.global.php
• config/authentication.global.php
• config/messages.global.php

Die Datenbankstruktur liegt in db/base.sql. Zusätzlich gibt es ein MySQL-Workbench-Modell unter db/SQL-model.mwb.

Dependencies

SAM benötigt PersistentPDO, den eigenen PDORepository und die Mezzio SessionMiddleware.

Pipeline

Die Mezzio SessionMiddleware muss früh in der Pipeline laufen, bevor SAM oder Login-Handler auf die Session zugreifen.

SAM kann pro Route verwendet werden. Das ist die empfohlene Variante, wenn nur bestimmte Bereiche geschützt werden sollen.

Alternativ kann SAM global in die Pipeline gesetzt werden. Dann müssen öffentliche Routen in no-auth-routes eingetragen werden.

Wichtig: Wenn SAM global gepiped wird, muss sie nach Mezzio\Helper\UrlHelperMiddleware laufen, weil Redirects über den UrlHelper erzeugt werden.

Login-Routen

Login-Routen werden über loginHandling definiert. Der Schlüssel ist der Routename der Login-Route. destination ist die Route, auf die nach erfolgreichem Login weitergeleitet wird. resetDestination ist die Passwort-Reset-Route, die im Login-Template verfügbar gemacht wird.

Beispielrouten:

Der GlobalLoginHandler rendert das Template app::Login. Die mitgelieferte Vorlage liegt unter src/Templating/Login.html.twig.

Bei einem Login:

• wird eine bestehende User-Session zuerst entfernt
• werden Benutzername und Passwort über PhpSession und PDORepository geprüft
• wird das Passwort mit password_verify($password . $salt, $hash) validiert
• werden Session-Hash und Session-Start in der passenden Login-Tabelle gespeichert
• wird anschließend auf die konfigurierte destination weitergeleitet

Logout

Der LogoutHandler entfernt den User aus der Session und leitet auf die Route home weiter. Die Anwendung muss diese Route bereitstellen.

Öffentliche Routen

Wenn SAM global gepiped wird, werden Routen aus no-auth-routes ohne Auth-Prüfung durchgelassen. Das ist besonders für Passwort-Reset-Routen wichtig.

Der Wert wird vom Passwort-Reset-Handler auch als Login-Ziel genutzt, wenn ein Reset-Link ungültig oder abgelaufen ist.

Authentication Config

Die authentication-Config steuert Login-Felder, Repository-Zugriff, Session-Sicherheit, Passwort-Reset und optionale Weitergabe von Daten an Requests.

Konfigurationsfelder:

• username und password: POST-Feldnamen für Login-Formulare.
• repository.table: Standard-Tabellenprefix, wenn keine Route per table_override erkannt wird.
• repository.fields.identities: Datenbankfelder, über die ein Login gesucht werden darf, z. B. Benutzername oder E-Mail.
• repository.fields.password: Feld mit dem Passwort-Hash.
• repository.disable-check: aktiviert die Prüfung gegen das konfigurierte Disabled-Feld der Login-Tabelle.
• repository.table_override: ordnet Routenpräfixe einem Tabellenprefix zu. Beginnt eine Route mit admin, nutzt SAM z. B. admin, admin_groups, admin_permissions usw.
• security.algo: Hash-Algorithmus für Session- und Reset-Hashes.
• security.salt: Salt für Passwortprüfung und Session-Fingerprint.
• security.fields.session: Datenbankfeld für den aktuellen Session-Hash.
• security.fields.stamp: Datenbankfeld für den Session-Zeitstempel.
• username-forwarding: setzt den aktuellen Benutzernamen als Request-Attribut adminName.
• permission-forwarding: lädt Benutzerdaten und Permissions früh im Request über den PermissionManager.
• allowWildcard: erlaubt die Permission * als globale Berechtigung, wenn die angefragte Permission in der Datenbank existiert.
• passwordResetOffset: Gültigkeit neuer Passwort-Reset-Hashes in Sekunden.

Hinweis: Die aktuelle SessionAuthMiddleware liest table_override unter authentication.repository.table_override.

Session Config

gc_lifetime ist für SAM besonders wichtig: Der Wert definiert, wie lange der in der Datenbank gespeicherte Session-Zeitstempel gültig bleibt. Läuft diese Zeit ab, wird die Session verworfen und der Benutzer muss sich neu anmelden.

Während aktiver Nutzung aktualisiert SAM den Datenbank-Zeitstempel höchstens einmal pro Minute.

PermissionManager

Der PermissionManager lädt Berechtigungsdaten für den aktuellen Tabellenprefix und prüft anschließend die Route als Permission.

Das Prinzip ist bewusst einfach: Der Routename ist die Permission.

Beispiel: Eine Route mit dem Namen adminDashboard benötigt eine Permission mit dem Wert adminDashboard. Benutzer erhalten Permissions nicht direkt, sondern über Gruppen.

Der PermissionManager kann:

• alle Permissions eines Bereichs laden
• den aktuellen Tabellenprefix setzen, z. B. user oder admin
• Benutzerdaten inklusive Settings, Gruppen und Permissions laden
• prüfen, ob der Benutzer in einer Gruppe ist
• prüfen, ob der Benutzer eine Permission besitzt
• Bypass-Permissions berücksichtigen
• Wildcard-Permissions berücksichtigen
• eine Fallback-Route für fehlende Permissions ermitteln
• User-Daten und User-Settings aktualisieren

Permission-Fallbacks

Permissions können eine Fallback-Permission referenzieren. Hat ein Benutzer keinen Zugriff auf die angefragte Route und gibt es keinen internen Referer, leitet SAM auf die Fallback-Route um.

Wenn keine Permission zur Route existiert, verwendet der PermissionManager home als Fallback.

Bypass und Wildcard

Eine Permission mit allowBypass = 1 gilt immer als erlaubt. Das ist nützlich für Fallback- oder Basisrouten, die technisch geschützt sind, aber allen angemeldeten Benutzern offenstehen sollen.

Wenn authentication.allowWildcard auf true steht, kann eine Gruppe mit der Permission * Zugriff auf alle in der Datenbank definierten Permissions erhalten.

Tabellenkonfiguration

SAM verwendet Tabellenprefixe. Für den Prefix user werden z. B. diese Config-Keys erwartet:

• user
• user_settings
• user_group_relation
• user_groups
• user_permissions
• user_group_permission_relation

Für admin entsprechend:

• admin
• admin_settings
• admin_group_relation
• admin_groups
• admin_permissions
• admin_group_permission_relation

Beispiel für user:

Die Spaltennamen sind frei konfigurierbar, solange die Config die tatsächlichen Datenbankfelder korrekt abbildet.

Message Config

SAM und die Handler lesen Fehlermeldungen aus messages.error. Wenn SAM während einer Auth-Prüfung einen Fehler erkennt, wird der Text für 60 Sekunden als Cookie error gesetzt.

Verwendete Keys:

• session-detail-error: Sessiondaten fehlen oder sind nicht lesbar.
• session-set-error: Session-Zeitstempel konnte nicht sauber gesetzt oder gelesen werden.
• session-expired-error: Session ist nach gc_lifetime abgelaufen.
• another-device-logon-error: Der Datenbank-Sessionhash passt nicht mehr zur aktuellen Session.
• logon-required-error: Die Route benötigt ein Login.
• credential-error: Benutzername oder Passwort sind falsch.
• user-create-error: Account-Erstellung konnte nicht gespeichert werden.
• user-repo-error: Login passt nicht zum aktuellen Auth-Bereich.
• session-path-swap-error: Eine Session aus einem Auth-Bereich wird für einen anderen Bereich benutzt, z. B. Admin-Session auf User-Route.

Im Login-Handler wird das Cookie gelesen, gelöscht und als Template-Variable error an app::Login übergeben.

Passwort-Reset

Der ForgotPasswordHandler unterstützt zwei POST-Aktionen:

• request: Reset-Link anfordern
• submit: neues Passwort speichern

Für den Reset werden diese Felder in der Login-Tabelle benötigt:

• resetHash
• resetValid
• loginMail

Die Gültigkeit wird über authentication.passwordResetOffset gesteuert. Standard im Code ist 2592000 Sekunden, also 30 Tage.

Für den Mailversand erwartet der Handler:

• requestPasswordAdapter
• submitPasswordAdapter
• das optionale Paket MazeDEV\FormularHandlerMiddleware\Adapter\SmtpMail

Die mitgelieferten Templates liegen unter:

• src/Templating/SetPasswordForm.html.twig
• src/Templating/emailing/ForgotPassword.html.twig
• src/Templating/emailing/PasswordSet.html.twig
• src/Templating/emailing/DefaultMail.html.twig

Account-Erstellung

Der CreateAccountHandler verarbeitet POST-Requests und nutzt die Tabellenkonfiguration des aktuell erkannten Auth-Bereichs. Die eigentliche Feldabbildung wird über den AbstractRequestHandler erzeugt.

Fehlschläge werden mit messages.error.user-create-error gemeldet.

Session- und Sicherheitslogik

SAM erzeugt den Session-Fingerprint aus:

• PHP-Zeitzone
• Remote-IP plus Proxy-Header, wenn vorhanden
• User-Agent
• authentication.security.salt

Der Hash wird mit authentication.security.algo erzeugt und beim Login in der Datenbank gespeichert. Bei jedem geschützten Request wird der aktuelle Hash mit dem Datenbankwert verglichen.

Wenn ein anderer Login denselben Account verwendet, überschreibt dieser Login den Datenbankhash. Die ältere Session erkennt das beim nächsten Request und wird abgemeldet.

Zugriff auf User und Permissions im Code

Die Middleware hält den PermissionManager statisch vor:

Zusätzlich kann username-forwarding den Benutzernamen als Request-Attribut adminName setzen. Bei Sessions mit gespeichertem Auth-Bereich wird außerdem userPath gesetzt.

Credits

Entwickelt von MazeDEV / Marcel Maqsood.

License

MIT. Siehe LICENSE.md.