Kundenportal Architecture

🤖 Consolidated with Claude Code

✅ Reviewed by author

Co-Authored-By: Claude (noreply@anthropic.com)

Sources: Atos Architecture Review 2024, cca.endCustomerApi, cca.kundenportal.managementserver

Overview

Multi-tenant SPA solution for insurance Endkunden to access their Polizzen and documents.

Components

Repository	Component	Deployment
cca.kundenportal	Angular SPA (Frontend)	CDN + Hosting-Server
cca.kundenportal.managementserver	Hosting-Server + Management API	Together-CCA-Cloud
cca.endCustomerApi	EndcustomerApi	Inside CCAOnline
cca.ccaonline	Token/Auth + Config Page UI	Customer Infrastructure

External dependency: Hosting Git Repository (Azure DevOps) - contains manifest.json, SPA versions, per-portal customizations.

Architecture Diagram

Source: diagrams/architecture.d2

Infrastructure Split

Together-CCA-Cloud (Yellow - Public Data)

• WAF: Web Application Firewall - entry point for all requests
• Hosting-Server: Serves SPA with customer-specific config based on hostname
• Management API: CRUD operations for portal provisioning
• CDN: Shared SPA assets (js, css)
• Hosting Git Repo: Azure DevOps repo with manifest.json, versions, customizations

Customer Infrastructure (Blue - Protected Data)

• CCAOnline: Token/Auth endpoints + Config Page UI
• EndcustomerApi: API for Endkunden data (deployed inside CCAOnline)
• CCA-Database: Customer data
• File-Storage: Documents, attachments

Request Flows

Endkunde Flow

1. Endkunde navigates to makler.myversum.at
2. WAF routes to Hosting-Server
3. Hosting-Server looks up hostname in manifest.json → serves index.html + customizations
4. SPA loads shared assets (js, css) from CDN
5. SPA authenticates via Token Endpoint (MFA)
6. SPA fetches Endkunden data via EndcustomerApi (Bearer token)

Admin Flow (Portal Setup)

1. Support/Technical Team uses Config Page in CCAOnline
2. Config Page calls Management API (through WAF)
3. Management API provisions portal → pushes to Hosting Git Repo

Hosting Git Repository Structure

hosting-repo/
├── manifest.json              # hostname → portal config mapping
├── _versionen/                # SPA version folders
│   ├── 1.0.0/
│   └── 1.1.0/
├── _portal_template/          # template for new portals
└── {hostname}/                # per-portal customizations
    └── customization/
        └── settings.json      # API endpoints, auth config, branding

Data Classification

• Yellow (Together-Cloud): Public data only - SPA assets, hosting config
• Blue (Customer Infrastructure): Protected customer data - Polizzen, documents, personal info
• Green (SPA): Runs in Endkunde's browser

Constraints / Randbedingungen

Constraint	Description
Data Residency	Kundendaten (Polizzen, Dokumente, persönliche Daten) verbleiben auf Kundeninfrastruktur (Blue zone). Together-Cloud enthält nur öffentliche Daten (Hosting-Config, SPA-Assets).
Browser Support	Aktuelle Versionen von Chrome, Firefox, Edge, Safari. Keine IE11-Unterstützung.
CCAOnline Compatibility	SPA-Version wird automatisch via CCAOnline /health Endpoint (applicationVersion) selektiert. 10 Minuten Cache pro Portal.
Network	CCAOnline muss aus dem Internet erreichbar sein (Endkunde-Browser, Together-Cloud Health Checks). Erforderliche Routen siehe HOSTING.md Section 3. TLS 1.2+ erforderlich.
Multi-Tenant Isolation	Jedes Portal hat eigene Konfiguration (settings.json). Datenbanktrennung via Customer Infrastructure.
OAuth2 Public Client	SPA ist ein public OAuth2 client (Implicit Flow). Kein Refresh-Token, kein Client Secret.
File Upload	Nur File-Extension-Filterung implementiert. Empfehlung aus Atos Review: Virus Scanning + Malicious Code Detection hinzufügen.
No Direct DB Access	Kein direkter Datenbankzugriff aus Together-Cloud. Alle Datenzugriffe über EndcustomerApi.

Cross-Cutting Concerns

Authentication

Implementierung: OAuth2 Implicit Flow + MFA via CCAOnline Token Endpoint

Component	Mechanism
Endkunde Login	Username/Passwort + optionale 2FA (SMS)
Token Type	Bearer Token (Reference Token)
Token Endpoint	CCAOnline /token Endpoint
Token Validation	AccessTokenAuthenticationFilter, ReferenceTokenStore

Hinweis: Bearer Token Hijacking-Risiko besteht (siehe SEC Consult Threat Model). Zukünftige Option: BFF Auth-API Proposal.

Authorization

Review Pending: thomas.steinglaubl@tis-cca.com, jorn.pranger@tis-cca.com

Two-Layer Authorization Model:

Layer	Component	Mechanism
Management API	Management Server	Azure AD Scopes + Client ID Matching
Endkunde Data	EndcustomerApi	Security Filters + Database Views + Rollen

Produktvarianten (ViewType):

ViewType	Produkt	Rollenmodell
CLASSIC	myVersum	Einfach - nur Benutzer
BUSINESS	myVersum for Business	Admin, Schadenmelder, Subuser

EndcustomerApi Authorization (myVersum for Business):

1. BerechtigungsTyp (Datenzugriffsebene):

   Typ	Beschreibung
   Person	Zugriff auf alle Verträge des Mandanten (via MandantPerson)
   Vertrag	Zugriff nur auf explizit freigegebene Verträge

2. Rollen (DB → Code → Claim):

   DB Rolle (ecav2.Rolle)	BerechtigungsTyp	Claim	Funktionsrechte
   Admin	Person	MandantenAdmin	Voller Mandant-Zugriff, Subuser-Verwaltung
   Schadenmelder	Vertrag	Schadenmelder	Nur Schadenmeldungen erstellen
   (kein Eintrag)	Vertrag	(keiner)	Subuser - nur freigegebene Verträge

3. BenutzerVertragBerechtigung: Mapping Subuser ↔ freigegebene Verträge

   • Admin benötigt keine Einträge (sieht alle via MandantPerson)
   • Subuser sehen nur Verträge mit expliziter Berechtigung in ecav2.BenutzerVertragBerechtigung

4. Database Views: ~40 Views im Schema ecav2 für Datenzugriffskontrolle

Code-Referenzen:

• ecav2.Benutzer.BerechtigungsTyp, ecav2.Rolle, ecav2.BenutzerVertragBerechtigung (DB)
• CCA.EndcustomerApi.Core/Identity/Services/ProVersum/BenutzerSettingsService.cs
• CCA.EndcustomerApi.EntityFramework/Identity/StoresNetCore/EndcustomerApiUserStore.cs:GetClaimsAsync()

Observability

Implementierung: Microsoft Application Insights (OpenTelemetry via Azure Monitor)

Feature	Status	Details
X-Correlation-id	⚠️ Teilweise	Header für Request-Tracking, nicht durchgängig in allen Komponenten
Application Insights	✅ Aktiv	HTTP Request/Response Logging
Custom Properties	✅ Aktiv	client_id, cca_lizenznehmer, user_name
Error Dashboards	⏳ Geplant	Proaktive Fehleranalyse (Atos Empfehlung)

TelemetryInitializer enriches telemetry with:

• Cloud.RoleName: Service-Identifikation
• User.AccountId: Lizenznehmer (Makler)
• Device.Id / User.Id: OAuth Client ID

Bekannte Lücken (Atos Review 6.1.4):

• Nicht alle Fehler enthalten Correlation-ID
• UI zeigt Transaction-ID nicht bei Fehlermeldungen

Error Handling

Aspect	Status	Notes
Global Exception Handler	✅	Standard ASP.NET Core Middleware
User-facing Errors	⚠️	Generische Fehlermeldungen ohne Context
Error Correlation	⚠️	Transaction-ID nicht in UI sichtbar

Empfehlungen (Atos Review):

• Transaction-ID (X-Correlation-id) in Fehlermeldungen anzeigen
• Dashboards für proaktive Fehleranalyse
• Detailliertere Fehlermeldungen für Support-Team

Decisions

See decisions/ for Architecture Decision Records (ADRs).