Login & Registrierung

Dieser Abschnitt ist die ausführliche Referenz zu allen Anmelde-Verfahren der Future-Box: Selbstregistrierung mit E-Mail-Verifikation, Anlage durch Admin, LDAP, Keycloak, OpenID, Passwort-Zurücksetzen, Zwei-Faktor-Authentifizierung und Logout.

Überblick

Die Future-Box unterstützt vier Anmelde-Verfahren, die über die Konfiguration einer Instanz gesteuert werden:

Login-Typ (login_type)	Wer legt Accounts an?	Passwort liegt bei	Typische Einsatzkontexte
registration	Personen selbst	Future-Box (Hash)	Allgemeinbildende Schulen, frei zugängliche Instanzen
creation	Admin manuell oder per CSV	Future-Box (Hash)	Schulen ohne LDAP, bei denen Admin alle Accounts vorab anlegt
ldap	Verzeichnisdienst (autom. Anlage beim ersten Login)	LDAP-Server	UCS-Schulserver, Hochschulen, größere Träger
keycloak	Identity-Provider (autom. Anlage beim ersten Login)	Keycloak	Organisationsweite Single-Sign-On-Verbünde

Zusätzlich gibt es OpenID als separaten Endpunkt — er funktioniert unabhängig vom globalen login_type und kann parallel betrieben werden.

💡 Erste Schritte: Die schrittweise Anleitung für Endnutzer:innen finden Sie unter Erste Schritte. Dieser Abschnitt vertieft die technische Sicht.

---

Selbstregistrierung (login_type = registration)

🎓 Lernende / 👩‍🏫 Lehrende

Ablauf

1. Auf der Login-Seite „Registrieren“ öffnen.
2. Felder ausfüllen:
   • Name (Pflicht, max. 255 Zeichen)
   • E-Mail (Pflicht, gültiges Format, instanzweit eindeutig)
   • Passwort (Pflicht, mind. 6 Zeichen, Bestätigung erforderlich)
3. Auf „Registrieren“ klicken.
4. Die Future-Box legt einen Account an mit:
   • verified = 0 (noch nicht bestätigt)
   • email_token (20-stelliger Zufalls-String)
   • Default-Rolle: user (Lernende)
   • Falls noch kein anderer User existiert → Account wird zusätzlich is_admin = 1 und erhält Superadmin-Rechte
5. Eine Verifikations-E-Mail wird an die angegebene Adresse versendet.
6. Eine Erfolgsseite informiert: „Bitte bestätigen Sie Ihre E-Mail-Adresse.“

E-Mail-Verifikation

1. Empfänger:in öffnet die E-Mail.
2. Klick auf den Link /register/verify/{token}.
3. Future-Box setzt verified = 1, entfernt das Token.
4. Weiterleitung zur Login-Seite mit Hinweis: „Deine E-Mail-Adresse wurde bestätigt.“

⚠️ Hinweis: Ein nicht verifizierter Account kann sich nicht einloggen — die Login-Logik prüft verified = 1. Solange das Token gültig ist, kann es jederzeit per Klick auf den Link verwendet werden.

Eindeutigkeit

Die E-Mail-Adresse muss innerhalb der Instanz eindeutig sein. Eine schon registrierte Adresse löst eine Fehlermeldung aus.

---

Anlage durch Admin (login_type = creation)

⚙️ Admin

In dieser Variante können sich Personen nicht selbst registrieren – die Schaltfläche „Registrieren“ auf der Login-Seite ist deaktiviert. Account-Anlage erfolgt über die Benutzerverwaltung: manuell pro Person oder per CSV-Import.

Manuell angelegte Accounts können beim Anlegen direkt als verifiziert markiert werden, sodass keine E-Mail-Bestätigung nötig ist.

---

LDAP-Login (login_type = ldap)

Voraussetzungen

⚙️ Admin

• LDAP-Verbindungsdaten in der Server-Konfiguration (config/ldapconnections.php bzw. .env-Variablen LDAP_1_HOST, LDAP_1_PORT, LDAP_1_BASE_DN, LDAP_1_USERNAME, LDAP_1_PASSWORD, LDAP_1_SSL, LDAP_1_TLS, LDAP_LOGIN_FIELD, LDAP_LOGIN_KEY etc.)
• Mehrere LDAP-Connections können konfiguriert werden (Failover)

Ablauf für Endnutzer:innen

1. Auf der Login-Seite (LDAP-Variante) Benutzername + Passwort eingeben.
2. Future-Box durchläuft die konfigurierten LDAP-Connections und versucht, mit den Daten einen Bind durchzuführen.
3. Bei erfolgreicher Authentifizierung:
   • Existiert bereits ein Future-Box-Account mit dem LDAP-Identifier (uidnumber) → einloggen.
   • Existiert noch keiner → automatische Anlage:
     • Felder aus dem LDAP-Eintrag: E-Mail, Anzeigename
     • Erster User wird Superadmin, alle weiteren erhalten die Default-Rolle.
     • Zusätzlich: Wenn LDAP_MAP_DATA_BY_IDENTIFIER aktiv ist und ein älterer Account mit gleichem Identifier existiert, werden dessen Stacks geklont.
   • Bei UCS-LDAP wird zusätzlich das Feld ucsschoolrole ausgewertet (Format role:school:scope).

Integration mit Default-User

Der Default-Account (mit default = 1 in der Datenbank) kann sich auch im LDAP-Modus immer lokal mit E-Mail + Passwort einloggen. Damit bleibt Administration auch bei Ausfall des LDAP-Servers möglich.

⚠️ Hinweis: Die LDAP-Konfiguration erfolgt server- bzw. instanz-seitig durch die Administration. Endnutzer:innen müssen sich nicht darum kümmern – sie verwenden ihre gewohnten Zugangsdaten.

---

Keycloak-Login (login_type = keycloak)

Voraussetzungen

⚙️ Admin

• Keycloak-Server mit konfigurierter Future-Box-Client-App
• .env-Variablen oder Tenant-Konfiguration mit Client-ID, Client-Secret, Redirect-URI, Realm-URL

Ablauf für Endnutzer:innen

1. Auf der Login-Seite den Keycloak-Anmelde-Button klicken.
2. Weiterleitung an /auth/keycloak/redirect. Der Browser landet auf der Keycloak-Anmeldeseite Ihrer Organisation.
3. Anmeldung dort (Single Sign-On, ggf. inkl. eigener 2FA des Identity-Providers).
4. Rückleitung an /auth/keycloak/callback.
5. LoginKeycloakService::handleCallback() legt einen Future-Box-Account an oder findet einen bestehenden, prüft verified und accept_data_protection, loggt ein.
6. Rollenbasierter Redirect (Trainer-/Kammer-Dashboard oder Stack-Übersicht).

---

OpenID-Login (parallel verfügbar)

⚙️ Admin (Konfiguration), 🎓 Lernende / 👩‍🏫 Lehrende (Nutzung)

OpenID-Routen sind unabhängig vom globalen login_type aktivierbar. Sie funktionieren wie der Keycloak-Modus, sind aber als eigene Endpunkte ausgelegt:

Endpunkt	Funktion
/auth/openid/login	Wendet Tenant-OpenID-Konfiguration an, leitet auf den Provider
/auth/openid/callback	Verarbeitet Rückleitung, legt ggf. Account an, loggt ein
/auth/openid/logout	Lokales Logout + Single-Sign-Out beim Provider, sofern openid_end_session_endpoint konfiguriert
/auth/openid/error	Fehlerseite

OpenID nutzt intern den Socialite-Keycloak-Driver, kann aber gegen jeden OIDC-konformen Provider konfiguriert werden, der dessen Schema entspricht.

---

Default-User / Admin-Bypass

⚙️ Admin / 🛡️ Superadmin

Pro Instanz kann genau ein Account das Flag default = 1 tragen. Dieser Account verhält sich besonders:

• Lokal anmelden auch bei LDAP/Keycloak: Die attemptLogin()-Logik prüft als allererstes per isDefaultLocalUser(), ob es ein Default-User ist, und führt dann einen lokalen Passwort-Login durch — unabhängig vom Login-Type.
• In der Benutzerverwaltung versteckt: Der Default-Account wird in der Liste nicht angezeigt und ist damit gegen versehentliche Löschung geschützt.

⚠️ Wichtig: Bewahren Sie die Zugangsdaten des Default-Accounts sicher auf. Bei Ausfall des LDAP- oder Keycloak-Dienstes ist er Ihre Rückversicherung, um die Future-Box weiterhin administrieren zu können.

---

Passwort-Reset

🎓 Lernende / 👩‍🏫 Lehrende

Verfügbar nur bei lokalen Accounts (Login-Typ registration oder creation). LDAP- und Keycloak-Passwörter werden über das jeweilige Verzeichnis verwaltet.

Ablauf

1. Auf der Login-Seite „Passwort vergessen?“ klicken.
2. E-Mail-Adresse eingeben.
3. Future-Box versendet eine E-Mail mit einem Reset-Link.
4. Empfänger:in klickt den Link, gibt neues Passwort + Bestätigung ein.
5. Nach erfolgreichem Reset Weiterleitung zur Startseite.

Die Mechanik nutzt das Laravel-Standard-Trait SendsPasswordResetEmails bzw. ResetsPasswords. Reset-Tokens haben eine begrenzte Gültigkeit (Server-konfigurierbar; Standard 60 Minuten).

💡 Tipp: Wenn keine E-Mail ankommt, prüfen Sie zuerst den Spam-Ordner. Bleibt die Mail aus, kann das auf Konfigurationsprobleme im Mail-Setup der Future-Box-Instanz hindeuten — wenden Sie sich an die Administration.

---

Zwei-Faktor-Authentifizierung (2FA)

🎓 Lernende / 👩‍🏫 Lehrende / ⚙️ Admin

Aktivierung

2FA ist pro Instanz aktivierbar. Technisch trägt der Tenant-Datensatz dafür die Spalte two_factor_enabled — die Aktivierung erfolgt also nicht über die UI-Konfigurationsseiten, sondern auf der Tenant-Verwaltungsebene (Mandantenverwaltung). Wenn aktiv, gilt die 2FA-Einrichtung für alle Nutzer:innen der Instanz verpflichtend.

Einrichtung (Erstmalig)

1. Bei aktiver 2FA leitet die Future-Box nach dem ersten Login auf /2fa/setup.
2. Die Seite zeigt:
   • Einen QR-Code (TOTP-Standard)
   • Den geheimen Secret-Schlüssel als Text (für manuelle Eingabe in die App)
   • Eine Liste von Wiederherstellungscodes (8 Stück, je 10 Zeichen typisch)
3. Authenticator-App öffnen (Google Authenticator, Microsoft Authenticator, FreeOTP, Authy, 1Password etc.) und QR-Code scannen.
4. Den aktuell von der App generierten 6-stelligen Code eingeben und bestätigen.
5. Wiederherstellungscodes sicher speichern (ausdrucken, in Passwortmanager kopieren).

Bei jedem Login

1. Nach Eingabe von Identifier/E-Mail + Passwort fragt die Future-Box auf /2fa/login nach einem 6-stelligen Code.
2. Code aus der Authenticator-App eingeben oder einen Wiederherstellungscode verwenden.
3. Bei korrekter Eingabe wird die Session-Variable two_factor_passed = true gesetzt; Sie sind eingeloggt.

⚠️ Hinweis: Wiederherstellungscodes sind Einmalcodes. Nach Verwendung wird der genutzte Code automatisch durch einen neuen ersetzt. Notieren Sie sich daher die jeweils aktuellen Codes.

Bei Verlust des Smartphones

1. Mit einem Wiederherstellungscode einloggen.
2. Im Profil die 2FA neu einrichten (alten Secret entfernen, neuen QR-Code scannen).

Sind keine Wiederherstellungscodes mehr verfügbar, kann nur die Administration Ihren Account zurücksetzen.

---

Logout

Standard-Logout

Über den Abmelden-Button im Hauptmenü oder per POST auf /logout. Die Session wird invalidiert, ein Redirect zur Login-Seite erfolgt.

Single-Sign-Out (OpenID/Keycloak)

Beim OpenID-Logout (/auth/openid/logout) wird zusätzlich:

• Die lokale Session invalidiert.
• Der Browser zur End-Session-URL des Providers weitergeleitet, sofern openid_end_session_endpoint in der Tenant-OpenID-Config gesetzt ist.

So wird auch die Sitzung am Identity-Provider beendet — wichtig in geteilten Umgebungen (Schul-PCs).

---

Fehlersituationen und ihre Bedeutung

Fehlermeldung / Symptom	Wahrscheinliche Ursache	Lösung
„Account deaktiviert oder Login fehlgeschlagen.“	verified = 0 oder deactivated = 1	E-Mail-Verifikation klicken oder Admin kontaktieren
„Dein Account ist deaktiviert.“	LDAP-User mit verified = 0	Admin den Account aktivieren lassen
Nach LDAP-Login Endlosschleife	LDAP erreichbar, aber Bind schlägt für die einzelnen Connections fehl	Konfiguration in .env prüfen, Logs ansehen
„Fehler bei der Keycloak-Authentifizierung.“	Konfiguration des Keycloak-Clients fehlerhaft	Client-ID/Secret, Redirect-URI prüfen
404 auf /register	Login-Type ist nicht registration	Selbstregistrierung systemweit deaktiviert
„Der eingegebene Code ist ungültig oder abgelaufen.“ (2FA)	Authenticator-App-Zeit nicht synchron	Zeit am Telefon prüfen, ggf. neu synchronisieren

---

Hinweise & Tipps

• Login-Type wirkt instanzweit: Sie können nicht je nach Person verschiedene Login-Typen wählen — login_type ist eine globale Einstellung. Mischbetriebe lassen sich aber durch Kombination mit dem Default-User-Bypass und/oder OpenID konstruieren.
• Erste Person ist Admin: Vor dem produktiven Start ist es sinnvoll, gleich mit der ersten Person den Admin-Account einzurichten — sie erhält automatisch Superadmin-Rechte.
• 2FA für Admins empfohlen: Selbst wenn 2FA nicht instanzweit verpflichtend ist, sollten Personen mit Admin/Superadmin-Rolle 2FA aktivieren.
• Pausen-Sicherheit: In gemeinsam genutzten Umgebungen (Schul-PCs, Bibliothek) ist das aktive Abmelden nach der Sitzung wichtig. Bei Single-Sign-On nutzen Sie den OpenID-Logout, damit auch die Provider-Sitzung beendet wird.
• Mail-Setup testen: Vor dem produktiven Start eine Testregistrierung durchführen, um zu prüfen, dass Verifikations- und Passwort-Reset-Mails ankommen.
• Default-Account dokumentieren: Notieren Sie sich, welcher Account der Default-Account ist (er ist in der Liste unsichtbar). Eine externe Dokumentation hilft, ihn nicht zu vergessen.

Verwandte Bereiche

• Erste Schritte – Onboarding für neue Nutzer:innen
• Profil – Passwort ändern, 2FA verwalten, Account löschen
• Benutzerverwaltung – Accounts manuell anlegen oder per CSV importieren
• Systemkonfiguration – login_type und Verbindungsdaten setzen
• Rechte & Rollen – welche Rolle erhält ein neuer Account?