kaffeekasse-saas/docs/m9-anmeldung-magic-link-und-sso.md

# 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.