Portal-Integration in den Helm Values deklarieren

Die Authentifizierung in den Portalen wird von einer tokenbasierten auf eine cookiebasierte Lösung umgestellt. Dafür werden zunächst die Services und ihre Abhängigkeiten in den Helm Values erfasst. Anschließend wird die Authentifizierung im Frontend angepasst.

Wie die Migration abläuft

Die Umstellung erfolgt in drei Phasen. Phase 1 und 2 sind abgeschlossen. Aktuell läuft Phase 3.

1. ✓ Portal-Integration definieren

   Identifier in den Helm Values deklarieren

   Abgeschlossen

2. ✓ Abhängigkeiten definieren

   Fremde Microfrontends als Dependency eintragen

   Abgeschlossen

3. 3 Frontend-Code anpassen

   keycloak-js ablegen, Backend-URLs ableiten

   Bis 30.09.2026 in Produktion

   Du bist hier

Phase 1 und 2 betreffen denselben Block in den Helm Values, müssen aber nacheinander deployt werden. Ein Service kann erst als Dependency referenziert werden, nachdem sein Identifier durch ein Deployment registriert wurde. Das gilt auch für ein eigenes Backend mit separatem Identifier: Zuerst wird der Identifier deployt, anschließend wird er beim Frontend unter dependencies eingetragen.

Aktuell läuft Phase 3. Sind die Values bereits vollständig, geht es bei Phase 3 weiter. Neue Services beginnen mit Phase 1.

Warum das nötig ist

Ein Portal bündelt Frontends und Backends unter einer gemeinsamen Domain. Das Auth-Gateway setzt das Cookie für diese Portal-Domain und ergänzt den JWT bei Requests an die Backends. Die beteiligten Services müssen deshalb unter der Portal-Domain erreichbar sein.

Der Identifier bestimmt die Subdomain, unter der ein Service im Portal erreichbar ist.

<identifier>.<portal-domain>

Aus name: vertragsservice wird beispielsweise vertragsservice.salesforce.dvag beziehungsweise vertragsservice.finanzanalyse.dvag.

Ohne portalIntegration kann der Service weder von einem Portal noch von einem anderen Microfrontend eingebunden werden. Auch eine zur Laufzeit abgeleitete Backend-URL kann dann nicht aufgelöst werden.

Phase 1: Identifier deklarieren

Ergänze in deinen Helm Values für jeden Endpoint, unter dem ein Frontend oder Backend von dir erreichbar ist, einen portalIntegration-Block:

portalIntegration:
  name: mein-mfe
  type: frontend

Damit vergibst du einen Identifier, unter dem dein Service in einem Portal eingebunden werden kann – von der Portal-Shell selbst oder von einem anderen Microfrontend.

Der Block wird in den bestehenden Helm Values ergänzt.

Der Block gehört an den Endpoint. Er steht in den Gateway-Values neben endpointName und domain, nicht in den Deployment-Values der Container. Zusammengehörige Endpoints tragen denselben Namen. Siehe Mehrere Endpoints unter einer Subdomain.

Auch Backends benötigen den Block. Jeder Service, der unter der Portal-Domain erreichbar sein muss, benötigt einen Identifier. Ein Backend mit eigenem Namen verwendet type: backend.

Nach dem Deployment prüfen. Der Name sollte nach wenigen Minuten in der Portal-Topologie erscheinen. Damit ist die Registrierung des Identifiers bestätigt.

Frontend

endpoints:
  - endpointName: mein-mfe-entwicklung-dvag
    domain: mein-mfe.entwicklung.dvag
    paths:
      - path: /
        serviceName: mein-mfe-frontend
        port: 8080

    # neu
    portalIntegration:
      name: mein-mfe
      type: frontend

Backend

endpoints:
  - endpointName: mein-backend-entwicklung-dvag
    domain: mein-backend.entwicklung.dvag
    paths:
      - path: /
        serviceName: mein-backend
        port: 8080

    # neu
    portalIntegration:
      name: mein-backend
      type: backend

Ob das Backend einen eigenen Namen erhält oder den Namen des Frontends verwendet, hängt von der gewünschten Einbindung ab:

Liegt das Backend in einem anderen Namespace, benötigt es einen eigenen Namen, da ein Name genau einem Namespace zugeordnet ist.

Mehrere Endpoints unter einer Subdomain

Die Subdomain im Portal ergibt sich aus dem Namen, nicht aus dem Endpoint. Mehrere Endpoints dürfen deshalb denselben Namen tragen und landen dann gemeinsam unter einer Subdomain – solange sie im selben Namespace liegen.

Mehrere Container hinter einem Endpoint, die nur über Pfade getrennt sind, benötigen einen gemeinsamen Block:

endpoints:
  - endpointName: mein-service-entwicklung-dvag
    domain: mein-service.entwicklung.dvag
    paths:
      - path: /api        # Backend-Container
        serviceName: mein-service
        port: 8080
      - path: /           # Frontend-Container
        serviceName: mein-service
        port: 4200

    # neu – einmal, nicht je Container
    portalIntegration:
      name: mein-service
      type: frontend

Sind mehrere Endpoints erforderlich, beispielsweise wegen unterschiedlicher Prefix-Rewrites oder der maximalen Anzahl an Pfaden, erhalten alle zusammengehörigen Endpoints denselben Namen:

endpoints:
  - endpointName: mein-service-entwicklung-dvag
    domain: mein-service.entwicklung.dvag
    paths:
      - path: /api
        serviceName: mein-service
        port: 8080
      - path: /
        serviceName: mein-service
        port: 4200
    portalIntegration:
      name: mein-service
      type: frontend

  - endpointName: mein-service-module-entwicklung-dvag
    domain: mein-service.entwicklung.dvag
    paths:
      - path: /modul-a
        serviceName: mein-service
        port: 4201
      - path: /modul-b
        serviceName: mein-service
        port: 4202
    portalIntegration:
      name: mein-service   # derselbe Name – dieselbe Subdomain
      type: frontend

Die übrigen Felder des Blocks müssen für alle Endpoints mit demselben Namen übereinstimmen. Das Backend wird in beiden Beispielen unter demselben Namen wie das Frontend bereitgestellt.

Ein Service ohne eigenen Namen kann im Portal nicht separat eingebunden werden. Frontends, die unabhängig voneinander in Portale eingebunden werden sollen, benötigen daher jeweils einen eigenen Namen und eine eigene Subdomain.

Phase 2: Dependencies eintragen

Unter dependencies werden die Services eingetragen, die das Microfrontend direkt benötigt: eigene Backends mit separatem Namen sowie andere Microfrontends, die es einbindet.

Abhängigkeiten dieser Services werden nicht zusätzlich eingetragen. Die Auflösung erfolgt rekursiv: Wird ein Microfrontend eingebunden, werden auch dessen Dependencies und deren weitere Dependencies berücksichtigt.

Dein eigenes Backend

Für das eigene Backend gilt die in Phase 1 gewählte Namensstruktur:

• Derselbe Name wie das Frontend: Das Backend wird gemeinsam mit dem Frontend bereitgestellt und nicht als Dependency eingetragen.
• Eigener Name: Das Backend wird unter dependencies eingetragen, damit es gemeinsam mit dem Frontend eingebunden wird.

Umgekehrt gilt das nicht: Ein Backend deklariert seine Frontends nicht.

Andere Microfrontends

Weitere Microfrontends, die das eigene Frontend einbindet, werden ebenfalls als direkte Dependencies eingetragen. Voraussetzung ist, dass deren Identifier bereits deklariert und deployt wurden.

Die verfügbaren Identifier sind in der Portal-Topologie aufgeführt. Ein dort noch nicht vorhandener Name kann nicht referenziert werden und führt zu einem fehlgeschlagenen Deployment. In diesem Fall muss das zuständige Team den Identifier zunächst deklarieren und deployen.

Token Exchange

Das Feld tokenExchangeClientId wird derzeit nicht benötigt. Das ZuB-Team konfiguriert den Token Exchange für die entsprechenden Routen. Aktuell betrifft das nur Aufrufe an Generali und andere Drittanbieter. Eigene Backends erhalten den JWT, den das Auth-Gateway an den Request anhängt.

Perspektivisch ist ein Token Exchange auch für eigene Backends vorgesehen. Bis dahin bleibt das Feld ungesetzt.

Felder

Regeln für den Namen

Der Name bleibt über die Umgebungen hinweg unverändert:

# values-entwicklung.yaml
- endpointName: mein-mfe-entwicklung-dvag
  domain: mein-mfe.entwicklung.dvag
  portalIntegration:
    name: mein-mfe
    type: frontend

# values-abnahme.yaml
- endpointName: mein-mfe-abnahme-dvag
  domain: mein-mfe.abnahme.dvag
  portalIntegration:
    name: mein-mfe
    type: frontend

Der Name ist öffentlich sichtbar, wird von anderen Teams als Dependency referenziert und sollte deshalb dauerhaft stabil bleiben.

Checkliste für die Values

• Der Block steht in den Gateway-Values am Endpoint, nicht bei den Containern
• Jeder Endpoint mit einem Frontend hat einen portalIntegration-Block mit type: frontend
• Jeder Endpoint mit einem Backend hat einen portalIntegration-Block mit type: backend
• Endpoints, die zusammen unter eine Subdomain sollen, tragen denselben name
• name lautet in allen Umgebungen gleich – anders als endpointName und domain
• dependencies nennt nur, was du direkt brauchst – dein Backend, falls es einen eigenen Namen trägt, und Microfrontends, die du nachlädst
• Jede Dependency steht in der Portal-Topologie, ist also bereits deployt
• Nach dem Deploy taucht der eigene Name in der Portal-Topologie auf

Phase 3: Frontend umstellen und ausrollen

In Phase 3 wird das Frontend einmalig auf die cookiebasierte Authentifizierung umgestellt. Die erforderlichen Codeänderungen sind unter Authentifizierung im Frontend umstellen beschrieben.

Der anschließende Rollout erfolgt schrittweise über ENT → INT → ABN → PROD. Vor dem Deployment in eine Zielumgebung muss der Umstellungsstand des Portals berücksichtigt werden. Falls das Frontend weitere Microfrontends einbettet, ist außerdem zu prüfen, ob diese in der Zielumgebung bereits ohne übergebenen JWT betrieben werden können. Der jeweilige Umstellungsstand ist unter Umgestellte Frontends dokumentiert.

Checkliste vor dem Deployment

• Frontend angepasst gemäß Authentifizierung im Frontend umstellen
• Portal in der Zielumgebung ist laut Aktuell bekannte Portale umgestellt
• Falls weitere Microfrontends eingebettet werden: Unter Umgestellte Frontends geprüft, dass diese in der Zielumgebung ohne übergebenen JWT betrieben werden können
• Umstellungsstand des eigenen Frontends unter Umgestellte Frontends aktualisiert