Sascha WolfandClaude Opus 5
419e57b55d
OpenID Connect mit Authorization Code Flow und PKCE, vollstaendig
serverseitig - der Browser sieht weder Tenant- noch Client-ID. Genutzt wird
dieselbe App-Registrierung wie die Postfachanbindung, also kein zweites
Secret; delegiert statt app-only.
Nach dem Token-Tausch beweist ein Aufruf von /me bei Graph, dass das
Zugriffstoken gilt, und liefert die Objekt-ID. Sie landet in der neuen Spalte
crm_users.entra_oid und ist danach die stabile Verknuepfung - die E-Mail-
Adresse eines Menschen kann sich aendern, die Objekt-ID nicht.
Bewusst so entschieden:
- Es werden keine Konten angelegt. Wer kein CRM-Konto mit derselben Adresse
hat, wird abgewiesen; Zugriff vergibt weiter die Nutzerverwaltung.
- Die Anmeldung mit Benutzername und Passwort bleibt fuer alle bestehen -
Notzugang, falls Entra oder das Secret ausfaellt.
- Das CRM-Token kommt als Einmal-Ticket zurueck, nicht in der Adresszeile:
die Rueckleitung ist ein GET und stuende sonst in Browserverlauf und
Apache-Log.
- Keine Signaturpruefung des ID-Tokens und damit keine JWKS-Bibliothek. Es
kommt ueber TLS direkt vom Token-Endpunkt (OIDC Core 3.1.3.7); geprueft
werden aud, tid, nonce und exp, und der Graph-Aufruf belegt den Rest.
Ohne MS_SSO_ENABLED=true bleibt alles aus und die Anmeldemaske sieht aus wie
bisher.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
127 lines
5.0 KiB
Markdown
127 lines
5.0 KiB
Markdown
# 01 Architektur
|
||
|
||
## Bausteine
|
||
|
||
Drei Teile, keiner davon spricht direkt mit einem anderen ausser über HTTP bzw.
|
||
SQL:
|
||
|
||
| Teil | Technik | Wo |
|
||
| --- | --- | --- |
|
||
| Frontend | React 19, TypeScript, Tailwind 4, Vite | statisches Build in `/var/www/perinco_CRM/dist` |
|
||
| Backend | Express 4, mysql2 (CRM), Sequelize (Scanner) | `/var/www/perinco_CRM/server`, `127.0.0.1:5006` |
|
||
| Datenbank | MariaDB 10.11 | `perinco_CRM` und `perinco_scanner` |
|
||
|
||
Der Browser spricht **nie** direkt mit MariaDB - deshalb überhaupt ein Backend.
|
||
Das Backend bindet ausschließlich auf `127.0.0.1` und ist von außen nur über
|
||
den Apache-Reverse-Proxy erreichbar. Das CRM hört auf `pcrm.perinco.de` und
|
||
seit 16.09.2026 auch auf `crm.perinco.de` (`ServerAlias` im selben Vhost, beide
|
||
Namen im selben Let’s-Encrypt-Zertifikat).
|
||
|
||
## Topologie
|
||
|
||
```mermaid
|
||
flowchart LR
|
||
U(("Browser")) -->|"HTTPS"| A["Apache :443<br/>pcrm.perinco.de<br/>crm.perinco.de"]
|
||
A -->|"/"| D["dist/<br/>SPA, FallbackResource"]
|
||
A -->|"/api"| E["Express :5006"]
|
||
E --> C[("perinco_CRM")]
|
||
E --> S[("perinco_scanner")]
|
||
```
|
||
|
||
Der Scanner im CRM hängt unter `/api/scanner` und braucht damit **keine eigene
|
||
Apache-Regel**: alles läuft über den bestehenden `/api`-Proxy. Dasselbe gilt für
|
||
die Postfachanbindung unter `/api/mail` (siehe
|
||
[11 Postfachanbindung](11-postfach.md)).
|
||
|
||
## Ausgehende Verbindungen
|
||
|
||
Das Backend spricht von sich aus mit vier fremden Diensten. Alle sind
|
||
optional - fehlen die Zugangsdaten oder ist das Ziel nicht erreichbar, läuft die
|
||
Anwendung ohne den jeweiligen Teil weiter.
|
||
|
||
| Ziel | Wofür | Ausgelöst von |
|
||
| --- | --- | --- |
|
||
| Projektbörsen | Scraping der Projektangebote | Scanner-Scheduler |
|
||
| `api.openai.com` | Bewertung Lebenslauf gegen Projekt | Scanner-Pipeline |
|
||
| `login.microsoftonline.com`, `graph.microsoft.com` | Postfach `crm@perinco.de` lesen | Mail-Scheduler |
|
||
| `linkedin.com`, `media.licdn.com` | Profilfoto zu einem Kontakt holen | Benutzer im Kontaktformular |
|
||
|
||
Der LinkedIn-Abruf ist der einzige, den ein Benutzer direkt auslöst: Er liest die
|
||
öffentliche Vorschau (`og:image`) einer Profilseite und lädt das Bild vom
|
||
LinkedIn-CDN. Keine Anmeldung, kein Zugriff auf geschützte Inhalte - schlägt der
|
||
Abruf fehl, bleibt es beim Hochladen von Hand.
|
||
|
||
Die Postfachanbindung schickt **keine** Mailinhalte an Dritte: Kontaktdaten
|
||
werden auf dem Server aus Graph-Feldern und Signaturen gelesen, ohne
|
||
Sprachmodell.
|
||
|
||
## Anfrageweg mit Anmeldung
|
||
|
||
```mermaid
|
||
sequenceDiagram
|
||
actor B as Browser
|
||
participant A as Apache
|
||
participant E as Express
|
||
participant M as MariaDB
|
||
|
||
B->>A: POST /api/auth/login
|
||
A->>E: weiterleiten
|
||
E->>M: SELECT crm_users WHERE username
|
||
M-->>E: Zeile mit bcrypt-Hash
|
||
E->>E: bcrypt.compare
|
||
E-->>B: { token (JWT, 12 h), user }
|
||
Note over B: Token im localStorage
|
||
|
||
B->>A: GET /api/scanner/matches<br/>Authorization: Bearer ...
|
||
A->>E: weiterleiten
|
||
E->>E: requireAuth: JWT pruefen
|
||
E->>M: SELECT crm_users WHERE id (ist der noch aktiv?)
|
||
E->>M: SELECT matches JOIN agents, projects
|
||
M-->>E: Treffer
|
||
E-->>B: JSON
|
||
```
|
||
|
||
Bei `401` löscht das Frontend das Token und springt zurück auf den
|
||
Anmeldeschirm (`setUnauthorizedHandler` in `src/lib/api.ts`). Das Token wird bei
|
||
jeder Anfrage neu gegen die Datenbank geprüft - ein deaktivierter Benutzer ist
|
||
sofort draußen, ohne auf den Ablauf des Tokens zu warten.
|
||
|
||
Der zweite Weg zu demselben Token ist die Anmeldung über Microsoft Entra: statt
|
||
`bcrypt.compare` steht dort der OIDC-Ablauf mit Microsoft, danach geht es
|
||
identisch weiter - dasselbe JWT, dieselbe Prüfung bei jeder Anfrage. Wer kein
|
||
CRM-Konto hat, kommt auch mit gültigem Microsoft-Konto nicht hinein.
|
||
Einzelheiten: [13 Anmeldung über Microsoft](13-anmeldung-sso.md).
|
||
|
||
## Rollen
|
||
|
||
```mermaid
|
||
flowchart TD
|
||
L["Anmeldung"] --> R{"Rolle"}
|
||
R -->|admin| A["Dashboard, Akquise, Opportunities, Interviews, Kontakte, Mails, Scanner<br/>Einstellungen: Nutzerverwaltung, Mein Konto, Akquise, Postfach, Scanner, Whisper"]
|
||
R -->|user| U["Dashboard, Akquise, Opportunities, Interviews, Kontakte, Mails, Scanner<br/>Einstellungen: Mein Konto, Akquise, Whisper"]
|
||
```
|
||
|
||
Bei den Mails darf jede Rolle lesen und zuordnen - `crm@perinco.de` ist ein
|
||
gemeinsames Vertriebspostfach. Einrichten, Verbindungstest und manueller Abgleich
|
||
sind Administratoren vorbehalten.
|
||
|
||
Die Rollenprüfung sitzt **doppelt**: das Menü blendet aus, was nicht erlaubt
|
||
ist, und das Backend weist Zugriffe zusätzlich mit `403` ab (`requireAdmin`).
|
||
Ausnahme ist `GET /api/users/directory` - die Benutzerliste brauchen alle Rollen
|
||
für Netzwerkdiagramm, Zuständigkeiten, @-Mentions, Teilnehmerauswahl und
|
||
Terminfarben. Passwort-Hashes liefert der Endpunkt nie.
|
||
|
||
Ein Sicherheitsnetz im Backend verhindert, dass der letzte aktive Administrator
|
||
degradiert, deaktiviert oder gelöscht wird.
|
||
|
||
## Belegte Ports auf dem Server
|
||
|
||
Der Rechner hostet weitere Dienste (n8n, Docker, ~15 Apache-Vhosts). Vor jeder
|
||
Portbelegung `ss -tlnp` prüfen. Relevant hier:
|
||
|
||
| Port | Dienst |
|
||
| --- | --- |
|
||
| 5006 | perinco CRM Backend (nur `127.0.0.1`) |
|
||
| 3000 | weitere Vite-App |
|
||
| 5678 | n8n |
|