Planung M9: Anmeldung per Magic-Link und SSO ueber Entra ID
Noch keine Umsetzung - nur Datenmodell, Ablaeufe und Reihenfolge zum Abschaetzen. Zwei unabhaengig lieferbare Stufen: erst Magic-Link (klein und stellt danach den Notzugang bereit), dann OIDC gegen Entra ID. Festgehaltene Entscheidungen: OIDC statt SAML, ADFS indirekt ueber Entra, kein automatisches Anlegen von Konten beim SSO-Login, SSO-Pflicht pro Mandant mit Magic-Link als Notzugang fuer owner/admin. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
This commit is contained in:
Claude Opus 4.8
@@ -0,0 +1,228 @@
|
||||
# M9 Anmeldung: Magic-Link und SSO über Entra ID
|
||||
|
||||
Stand: 2026-07-22 — **Planung, noch nicht umgesetzt.**
|
||||
|
||||
Ziel: Mitglieder sollen sich ohne eigenes Passwort anmelden können, und ein
|
||||
Mandanten-Administrator soll das selbst einrichten können. Zwei Stufen, die
|
||||
unabhängig voneinander lieferbar sind:
|
||||
|
||||
1. **Magic-Link** — Anmeldung per Einmal-Link in der E-Mail.
|
||||
2. **SSO über Entra ID** (OpenID Connect) — Anmeldung über das Konto des
|
||||
Kunden; dient gleichzeitig der Anbindung eines dahinterliegenden ADFS.
|
||||
|
||||
Die Reihenfolge ist bewusst so gewählt: Der Magic-Link ist klein, sofort
|
||||
nützlich und stellt danach den **Notzugang** bereit, den die SSO-Pflicht
|
||||
braucht.
|
||||
|
||||
## Entscheidungen (getroffen)
|
||||
|
||||
| Frage | Entscheidung |
|
||||
|---|---|
|
||||
| Protokoll | OpenID Connect gegen Entra ID; **kein** SAML |
|
||||
| ADFS | indirekt über Entra ID, nicht direkt angebunden |
|
||||
| Konten anlegen | **kein** automatisches Anlegen beim SSO-Login |
|
||||
| SSO-Pflicht | pro Mandant einschaltbar, Passwort dann deaktiviert |
|
||||
| Notzugang | Magic-Link, beschränkt auf `owner`/`admin` |
|
||||
| Entra-Modell | Kunde registriert **eigene** App in seinem Verzeichnis |
|
||||
|
||||
### Warum kein automatisches Anlegen
|
||||
|
||||
Beim SSO-Login wird ausschließlich ein **bestehendes** Mitglied dieses
|
||||
Mandanten angemeldet. Gibt es keines, erscheint ein Hinweis. Das passt zum
|
||||
vorhandenen Ablauf (Mitglied anlegen → „Zugang gewähren" über
|
||||
`saas_grant_participant_access()`) und macht eine DNS-Domain-Verifikation für
|
||||
die Sicherheit entbehrlich: Ohne Anlegen und ohne Verschmelzen fremder Konten
|
||||
kann ein Mandant über sein IdP keine Identitäten beanspruchen, die ihm nicht
|
||||
gehören.
|
||||
|
||||
`tenant_domains` bleibt damit vorerst ungenutzt. Eine Verifikation wäre später
|
||||
nur Komfort (Mandant automatisch an der E-Mail-Domain erkennen).
|
||||
|
||||
## Was schon vorhanden ist
|
||||
|
||||
Beide Stufen setzen fast vollständig auf Bestehendem auf:
|
||||
|
||||
```text
|
||||
app/saas-auth.php saas_create_auth_token(), saas_fetch_valid_auth_token(),
|
||||
saas_session_login(), saas_grant_participant_access()
|
||||
app/saas-mail.php saas_send_mail(), saas_log_outbound_email(), saas_app_url()
|
||||
app/rate-limit.php app_rate_limit_check()
|
||||
app/audit.php app_audit_log()
|
||||
user_auth_tokens user_id, tenant_id (nullable), token_type, token_hash,
|
||||
expires_at, consumed_at
|
||||
users password_hash ist NULL-fähig -> Konten ohne Passwort
|
||||
sind bereits darstellbar
|
||||
```
|
||||
|
||||
`saas_create_auth_token()`/`saas_fetch_valid_auth_token()` sind über
|
||||
`token_type` generisch. Der Magic-Link ist damit ein **neuer Token-Typ**, keine
|
||||
neue Infrastruktur. `passwort-vergessen.php` dient als Vorlage für den Ablauf
|
||||
inklusive Rate-Limits.
|
||||
|
||||
---
|
||||
|
||||
## Stufe 1: Magic-Link
|
||||
|
||||
### Datenmodell
|
||||
|
||||
Keine neue Tabelle. Ergänzungen an `tenant_settings`:
|
||||
|
||||
```sql
|
||||
login_password_enabled TINYINT(1) NOT NULL DEFAULT 1
|
||||
login_magic_link_enabled TINYINT(1) NOT NULL DEFAULT 0
|
||||
magic_link_ttl_minutes INT NOT NULL DEFAULT 15
|
||||
```
|
||||
|
||||
Neuer Wert für `user_auth_tokens.token_type`: `magic_link`. Anders als beim
|
||||
Passwort-Reset wird `tenant_id` **gesetzt** — der Link meldet für genau einen
|
||||
Mandanten an.
|
||||
|
||||
### Ablauf
|
||||
|
||||
1. Auf `login.php` neben dem Passwortfeld: „Link per E-Mail anfordern"
|
||||
(nur sichtbar, wenn für den Mandanten aktiviert).
|
||||
2. Eingabe E-Mail + Kundenkürzel. Rate-Limit analog `passwort-vergessen.php`
|
||||
(pro E-Mail und pro IP).
|
||||
3. Nutzer mit aktiver Mitgliedschaft in diesem Mandanten suchen. Antwort ist
|
||||
**immer gleich**, unabhängig davon, ob es ihn gibt.
|
||||
4. Token erzeugen (TTL aus den Einstellungen), Link per Mail, Versand über
|
||||
`saas_log_outbound_email()` protokollieren.
|
||||
5. Neue Seite `magic-login.php`: Token prüfen, als verbraucht markieren,
|
||||
`saas_session_login()` mit **festem** Mandanten aufrufen, `app_audit_log()`.
|
||||
|
||||
### Zu beachten
|
||||
|
||||
- Token ist **einmal** gültig (`consumed_at`) und kurzlebig (15 Minuten).
|
||||
- Bestehende, noch offene Magic-Link-Token des Nutzers beim Neuanfordern
|
||||
entwerten — sonst sammeln sich mehrere gültige Links an.
|
||||
- Der Link darf **nicht** über den `pending`-Weg der Mandantenauswahl laufen,
|
||||
sondern direkt in den Mandanten, für den er ausgestellt wurde.
|
||||
- Link nur per `POST`-Bestätigung einlösen oder mit `Referrer-Policy` schützen,
|
||||
damit er nicht über Referer/Prefetch abfließt.
|
||||
|
||||
### Aufwand
|
||||
|
||||
Klein — eine Migration, zwei Seiten, eine Mailvorlage, Erweiterung von
|
||||
`login.php` und den Mandant-Einstellungen.
|
||||
|
||||
---
|
||||
|
||||
## Stufe 2: SSO über Entra ID (OIDC)
|
||||
|
||||
### Datenmodell
|
||||
|
||||
Neue Tabelle `tenant_sso_providers` (eine Konfiguration je Mandant):
|
||||
|
||||
```text
|
||||
id INT PK
|
||||
tenant_id INT NOT NULL UNIQUE -> tenants(id) ON DELETE CASCADE
|
||||
provider VARCHAR(30) 'entra'
|
||||
directory_id VARCHAR(100) Entra-Verzeichnis (tid), hart geprüft
|
||||
client_id VARCHAR(200)
|
||||
client_secret_enc VARBINARY mit libsodium verschlüsselt
|
||||
discovery_url VARCHAR(500)
|
||||
enabled TINYINT(1)
|
||||
enforce_sso TINYINT(1) Passwort/Magic-Link für Mitglieder aus
|
||||
created_at/updated_at DATETIME
|
||||
```
|
||||
|
||||
Ergänzung an `users` für die stabile Zuordnung:
|
||||
|
||||
```sql
|
||||
sso_subject VARCHAR(200) NULL -- Entra: tid|oid
|
||||
UNIQUE KEY uq_users_sso_subject (sso_subject)
|
||||
```
|
||||
|
||||
Die E-Mail dient nur der **ersten** Zuordnung zum vorhandenen Mitglied; danach
|
||||
wird über `sso_subject` erkannt. `email`/`preferred_username` sind in Entra
|
||||
veränderbar und taugen nicht als Schlüssel.
|
||||
|
||||
### Ablauf (Authorization Code + PKCE)
|
||||
|
||||
1. `sso-start.php?tenant=<slug>`: Konfiguration laden, `state`, `nonce` und
|
||||
`code_verifier` in der Session ablegen, zu Entra weiterleiten.
|
||||
2. `sso-callback.php`: `state` prüfen, Code gegen Token tauschen
|
||||
(`https`-Stream-Wrapper, kein curl nötig).
|
||||
3. **ID-Token prüfen**: Signatur über JWKS (RS256, `openssl`), dazu `iss`,
|
||||
`aud`, `exp`/`iat`, `nonce` — und `tid` **hart gegen `directory_id`**.
|
||||
4. Nutzer über `sso_subject` suchen, sonst einmalig über die E-Mail einem
|
||||
vorhandenen Mitglied **dieses** Mandanten zuordnen und `sso_subject`
|
||||
festschreiben.
|
||||
5. Kein Treffer → Hinweisseite: „Für diese E-Mail-Adresse ist in diesem
|
||||
Mandanten kein Zugang hinterlegt." Kein Konto anlegen.
|
||||
6. Treffer → `saas_session_login()` mit dem Mandanten aus Schritt 1.
|
||||
|
||||
### Sicherheitsregeln
|
||||
|
||||
- **`tid` immer prüfen.** Ohne diese Prüfung könnte sich jeder Entra-Mandant
|
||||
der Welt anmelden — der klassische Fehler bei mandantenfähigen Entra-Apps.
|
||||
- **Nie über die Mandantenauswahl.** Der SSO-Rückkanal ruft
|
||||
`saas_session_login()` direkt mit festem Mandanten auf. Heute ist dieser Weg
|
||||
ohnehin zu (`mandant-auswahl.php` verlangt den `pending`-Zustand); er darf
|
||||
nicht nachträglich geöffnet werden.
|
||||
- **Client-Secret verschlüsselt** ablegen (libsodium, Schlüssel aus der Env,
|
||||
z. B. `APP_SECRET_KEY`), niemals im Klartext und nie im Formular
|
||||
zurückspielen — nur „gesetzt/nicht gesetzt" anzeigen.
|
||||
- **Ablauf des Secrets** ist die wahrscheinlichste Störung (Entra-Standard:
|
||||
6–24 Monate). Ablaufdatum mitpflegen und rechtzeitig warnen.
|
||||
|
||||
### SSO-Pflicht und Notzugang
|
||||
|
||||
Ist `enforce_sso` gesetzt:
|
||||
|
||||
| Rolle | Passwort | Magic-Link | Entra |
|
||||
|---|---|---|---|
|
||||
| `member`, `viewer`, `treasurer` | aus | aus | ja |
|
||||
| `owner`, `admin` | aus | **ja (Notzugang)** | ja |
|
||||
|
||||
Jede Nutzung des Notzugangs wird im Audit-Log vermerkt; zusätzlich eine
|
||||
Info-Mail an die übrigen Inhaber, damit eine stille Umgehung auffällt. Grund:
|
||||
Ein abgelaufenes Client-Secret sperrt sonst genau die Personen aus, die es
|
||||
reparieren müssten — der Mailversand ist davon nicht betroffen.
|
||||
|
||||
`enforce_sso` darf sich erst einschalten lassen, **nachdem** mindestens eine
|
||||
erfolgreiche Testanmeldung über Entra stattgefunden hat. Sonst sperrt eine
|
||||
fehlerhafte Konfiguration den Mandanten sofort aus.
|
||||
|
||||
### Einrichtung durch den Mandanten-Administrator
|
||||
|
||||
Neuer Abschnitt in `mandant-einstellungen.php`:
|
||||
|
||||
1. Anzeige der Redirect-URI zum Kopieren (`https://…/sso-callback.php`).
|
||||
2. Eingabe von Verzeichnis-ID, Client-ID, Client-Secret.
|
||||
3. Schaltfläche „Verbindung testen" — führt einen vollständigen Anmeldelauf
|
||||
aus und zeigt die zurückgelieferten Claims an.
|
||||
4. Erst nach erfolgreichem Test: „SSO verpflichtend" aktivierbar.
|
||||
|
||||
Als Anleitung für die Entra-Seite: App-Registrierung anlegen, Redirect-URI vom
|
||||
Typ *Web* eintragen, Client-Secret erzeugen, Berechtigungen `openid`,
|
||||
`profile`, `email`.
|
||||
|
||||
### Aufwand
|
||||
|
||||
Deutlich größer als Stufe 1 — der Flow selbst ist überschaubar, aber
|
||||
JWKS-Abruf mit Cache, Token-Prüfung, verschlüsselte Secrets, Testfunktion und
|
||||
die Admin-Oberfläche summieren sich.
|
||||
|
||||
---
|
||||
|
||||
## Reihenfolge
|
||||
|
||||
1. Migration Login-Einstellungen + Magic-Link (Stufe 1) — danach ist der
|
||||
Notzugang vorhanden.
|
||||
2. `tenant_sso_providers` + Secret-Verschlüsselung.
|
||||
3. OIDC-Flow ohne Oberfläche, per Konfiguration in der Env testbar.
|
||||
4. Admin-Oberfläche inklusive Testanmeldung.
|
||||
5. `enforce_sso` scharfschalten, Notzugangs-Regeln und Protokollierung.
|
||||
|
||||
## Offene Punkte
|
||||
|
||||
- **Composer**: Für OIDC nicht zwingend nötig (`openssl` + `json` +
|
||||
`https`-Wrapper genügen). Falls doch eine JWT-Bibliothek gewünscht ist,
|
||||
müsste Composer auf dem Netcup-Webspace eingerichtet werden. Welche
|
||||
PHP-Erweiterungen dort verfügbar sind, ist noch zu prüfen (`php -m`).
|
||||
- **Mehrere IdPs je Mandant** ist bewusst nicht vorgesehen (eine
|
||||
Konfiguration je Mandant). Bei Bedarf später `UNIQUE` auf `tenant_id` lösen.
|
||||
- **SCIM/automatische Bereitstellung** aus Entra ist bewusst nicht Teil des
|
||||
Plans — durch die Entscheidung gegen automatisches Anlegen bleibt die
|
||||
Mitgliederpflege in der Kaffeeliste.
|
||||
Reference in New Issue
Block a user