Migration auf Security Server 25

Themenübersicht

Bei einer Migration auf Security Server 25 sind derzeit insbesondere folgende Themen zu beachten:

• Java 25, Container-Image und Helm
• Datenbank-Upgrade (Schema 29 auf 33)
• Authentifizierung, CORS und Keycloak-Integration
• Datenbankkonfiguration und Connection-Pool
• REST-API und neue HSM-Endpunkte
• Entfernte Komponenten

Weitere Themen werden mit zukünftigen Produktversionen und neuen Erkenntnissen ergänzt.

Überblick über die Änderungen

Die folgenden Änderungen können bestehende Installationen beeinträchtigen, wenn sie nicht berücksichtigt werden:

Java 25, Container-Image und Helm

Hintergrund

Security Server 25 basiert auf Java 25 und Spring Boot 4.0.7 (Jakarta EE). Die bisherige Version lief auf Java 11 mit Spring Boot 2.6.6. BouncyCastle wurde von Version 1.83 auf 1.84 aktualisiert.

Auswirkungen

Die UID des Container-Benutzers bleibt unverändert, daher sind Berechtigungen auf eingebundenen Volumes nicht betroffen. Die mitgelieferten JDBC-Treiber für MSSQL (11.2.0) und Oracle (ojdbc8) bleiben gleich.

Die Standard-JAVA_OPTS enthalten zusätzlich -Xmx512m -Xms256m --add-opens=java.base/sun.security.util=ALL-UNNAMED.

Erforderliche Anpassungen

Container und Helm

1. Passen Sie die Image-Referenz an (.../aep/b2b/aep-securityserver).
2. Passen Sie die Health-Probes im Helm-Chart an:

1. Es sind nur noch die Actuator-Endpunkte health und prometheus erreichbar. Prometheus bleibt unter /fss/api/prometheus.
2. Wenn Sie JAVA_OPTS überschreiben, behalten Sie die Option --add-opens=java.base/sun.security.util=ALL-UNNAMED bei. Erhöhen Sie -Xmx bei großen Keystores.
3. Wenn Sie einen eigenen Entrypoint verwenden, hat sich die Launcher-Klasse zu org.springframework.boot.loader.launch.JarLauncher geändert (bisher org.springframework.boot.loader.JarLauncher).
4. Der Cluster-Modus bleibt unverändert (-Dcluster.node=... oder CLUSTER_USE_CLUSTERNODE_HOSTNAME=true, -Dcluster.service.period=...).

Installation ohne Docker (ZIP)

• Das Artefakt heißt jetzt aep-securityserver-rest-<version>.zip (bisher securityserver-rest-<version>.zip).
• Installieren Sie eine Java-25-Laufzeitumgebung. Das Startskript start.sh verwendet die neue Launcher-Klasse.
• Die Service-Dateien liegen jetzt unter etc/init.d (SysV, bisher etc_init.d) und neu unter etc/systemd/securityserver (systemd).

Maven-Koordinaten

Für Nutzer der Java-Client-Bibliothek: Die groupId ist jetzt de.arvato-systems.aep, die artifactIds beginnen mit aep-securityserver- (z. B. aep-securityserver-client). Bisher war die groupId fastlane-securityserver mit artifactIds wie com.nextlevel.fastlane.security.server.client. Die Java-Pakete bleiben unverändert.

Überprüfung

• GET /fss/api/actuator/health/readiness liefert UP.
• Die Pods starten ohne Neustarts. Beim ersten Start läuft das Datenbank-Upgrade, das Startup-Probe berücksichtigt dies mit bis zu 72 Fehlversuchen.
• Der Prometheus-Endpunkt und Ihre Dashboards funktionieren mit den geänderten Pfaden.

Datenbank-Upgrade

Hintergrund

Security Server 25 hebt das Datenbankschema von Version 29 auf Version 33 an. Die Upgrade-Skripte (secserverUpdateToVersionNN.sql) werden vom mitgelieferten Upgrade-Manager ausgeführt. Unterstützt werden PostgreSQL, Oracle und MSSQL.

Auswirkungen

Die Versionsnummern unterscheiden sich von der bisherigen Linie: Dort war Version 29 die Umbenennung von email in address. In Security Server 25 liegt diese Umbenennung bei Version 32, die Versionen 29 bis 31 enthalten HSM- und Sequenz-Änderungen. Die neuen Skripte sind für diesen Fall wiederholbar ausgelegt.

Folgen:

• Kein Downgrade. Die bisherige Version benötigt sequence_next_hi_value, die nach Version 31 nicht mehr existiert. Ein Rollback ist nur durch Wiederherstellen der Datensicherung möglich.
• Keine gemischten Versionen. Betreiben Sie alte und neue FSS-Instanzen nie gleichzeitig gegen dieselbe Datenbank. Im Cluster-Betrieb stoppen Sie zuerst alle alten Knoten und starten dann die neuen. Ein Rolling Update über beide Generationen hinweg wird nicht unterstützt.
• Das Upgrade läuft beim ersten Start der neuen Version. Der Datenbankbenutzer benötigt dafür DDL-Rechte (ALTER, CREATE TABLE, CREATE INDEX).

Erforderliche Anpassungen

1. Erstellen Sie eine Datensicherung der FSS-Datenbank.
2. Spielen Sie die Sicherung in eine Testumgebung ein und starten Sie Security Server 25 dagegen. Testen Sie das Upgrade zuerst an einer Kopie Ihrer Produktivdatenbank.
3. Stoppen Sie für die Produktion alle alten Instanzen, bevor Sie die neue Version starten.

Überprüfung

• Die Logs enthalten keine Fehler der Upgrade-Befehle. Diese protokollieren bei manchen Fehlern nur und fahren fort, lesen Sie die Logs daher aufmerksam.
• Im Cluster-Betrieb: Fügen Sie auf einem Knoten ein Testzertifikat hinzu und prüfen Sie, dass die übrigen Knoten es innerhalb des Poll-Intervalls übernehmen.

Authentifizierung, CORS und Keycloak-Integration

Hintergrund

Die Werte für aep.security.auth-method bleiben unverändert: no-secure, basic, oauth2-token-roles (Keycloak) und oauth2-token-roles-allowed (Azure B2C). Auch die Rollennamen (FSS-CertificateManager-Read/Write, FSS-ClientManager-*, FSS-RuleManager-*, FSS-Crl, FSS-Message) bleiben gleich. Die Integration von Keycloak wurde jedoch ersetzt (neue Klasse KeycloakSecurityConfiguration).

Auswirkungen

• Profile secure und nosecure: Das Image liefert Standardwerte mit (aep.security.auth-method: no-secure). Die Profile setzen bereits keycloak.enabled und schließen die CRISP-Security-Autokonfiguration aus. Sie müssen für diese beiden Profile weder auth-method noch spring.autoconfigure.exclude setzen. aep.security.auth-method ist nur für basic, oauth2-token-roles oder oauth2-token-roles-allowed erforderlich.
• CORS: Der Standardwert für aep.security.cors.pattern ist jetzt eine Liste von Arvato-Domänen (bisher http://*,https://*). Browserbasierte Clients anderer Herkunft werden abgelehnt.
• Bouncr/APIM: aep.security.apim.internalApiKey, aep.security.bouncr.instanceId und aep.security.bouncr.host haben als Standardwert "fill in the correct value".
• Keycloak: Die bisherige Keycloak-Adapter-Integration wurde ersetzt. keycloak.json wird weiterhin gelesen.
• Es gibt ein neues optionales Spring-Profil crisp für CRISP-Umgebungen. Alle anderen Kunden können es ignorieren.
• SecurityGatewayProperties ist unverändert (gleiche Properties und Namen). Ihre vorhandenen -D-Properties und HSM-Pool-Einstellungen (HSM_*) können Sie weiterverwenden.

Erforderliche Anpassungen

1. Setzen Sie aep.security.cors.pattern auf die Herkunft(en) Ihrer Oberfläche.
2. Wenn Sie oauth2-token-roles-allowed nutzen, tragen Sie echte Werte für aep.security.apim.internalApiKey, aep.security.bouncr.instanceId und aep.security.bouncr.host ein.
3. Wenn Sie oauth2-token-roles (Keycloak) nutzen, prüfen Sie die Anmeldung und die Rollenzuordnung mit Ihrem Realm.
4. Prüfen Sie eigene application*.yml-Dateien gegen die Property-Änderungen von Spring Boot 3 und 4. Umbenannte oder entfernte spring.*- und management.*-Schlüssel werden stillschweigend ignoriert und nicht abgelehnt.

Überprüfung

• Anmeldung mit jedem von Ihnen genutzten Clienttyp.
• Aufrufe aus Ihrer Browser-Oberfläche werden nicht durch CORS blockiert.

Datenbankkonfiguration und Connection-Pool

Hintergrund

Die Datenbankverbindung wird über hibernate.cfg.xml und Umgebungsvariablen konfiguriert. Mit Spring Boot 4 wird Hibernate 6 eingesetzt, der Standard-Connection-Pool ist jetzt HikariCP (c3p0 ist veraltet).

Auswirkungen

Erforderliche Variablen: DB_DRIVER, DB_URL, DB_USERNAME, DB_PASSWORD, DB_DIALECT.

• Der Entrypoint bricht jetzt ab, wenn DB_DRIVER oder DB_DIALECT leer sind oder eine numerische oder boolesche Pool-Einstellung ungültig ist. Bisher gab es keine Prüfung.
• Neue optionale Pool-Einstellungen: DB_POOL_MIN_SIZE (5), DB_POOL_MAX_SIZE (20), DB_POOL_HIKARI_*, DB_POOL_UCP_*, DB_VALIDATION_QUERY.
• Platzhalter in hibernate.cfg.xml werden nur ersetzt, solange die Datei noch DB_URL_TO_REPLACE enthält.

Erforderliche Anpassungen

1. Verwenden Sie die neuen Variablennamen DB_URL und DB_USERNAME.
2. Setzen Sie DB_DRIVER und DB_DIALECT.
3. Wenn Sie eine eigene hibernate.cfg.xml einbinden, gehen Sie von der neuen Vorlage aus und prüfen Sie Pool- und Dialekt-Eigenschaften.
4. Die Eigenschaft hbm2ddl.auto muss nicht gesetzt werden. Das Schema wird durch die Upgrade-Skripte verwaltet.

Überprüfung

• Der Container startet ohne Fehlermeldung des Entrypoints (Required environment variable ... is missing or empty).
• Die Datenbankverbindung wird aufgebaut und das Datenbank-Upgrade läuft durch.

REST-API und neue HSM-Endpunkte

Hintergrund

Alle bestehenden Endpunkte behalten Pfade, Parameter und Rollen. Port (2222), Basispfad (/fss/api/v1/) und Swagger (/fss/api/swagger-ui.html) bleiben gleich.

Auswirkungen

Spring 6 und neuer gleicht einen abschließenden Schrägstrich standardmäßig nicht mehr ab (/pfad/ gegenüber /pfad). Verwenden Sie die dokumentierten Pfade ohne abschließenden Schrägstrich.

Erforderliche Anpassungen

Für bestehende Clients sind keine Anpassungen erforderlich, sofern sie die dokumentierten Pfade verwenden und Uploads als multipart/form-data senden.

Überprüfung

• Testen Sie je Protokoll (AS2, AS4, S/MIME, MBSE) das Verschlüsseln, Entschlüsseln, Signieren und Prüfen einer Beispielnachricht.
• Testen Sie eine Zertifikatsliste, eine CRL-Prüfung und gegebenenfalls eine HSM-Schlüsseloperation.

Entfernte Komponenten

Hintergrund

Mit Security Server 25 wurden Komponenten entfernt oder ersetzt, die nicht mehr zum Funktionsumfang gehören.

Auswirkungen

• ServiceRuntime-Launcher (connector.serviceruntime): Es gibt nur noch das Spring-Boot-REST-Deployable.
• Java-11-Build: Der Snapshot-Build für Java 11 entfällt. Java 25 ist der einzige Build.
• TCN-Sockets für den TR-03109-CA-/LDAP-Client (TcnSocket, SmTcnLdapSocketFactory und zugehörige Klassen) wurden entfernt. Die Unterstützung für HTTP- und SOCKS-Proxys bei CRL- und CA-Aufrufen bleibt bestehen.
• Neu: TLS-Signatur mit HSM-gehaltenen Schlüsseln (HsmTlsStreamSigner, HsmEnabledSignature) und die Klassen smartenergy.jcajce für BouncyCastle-TLS im TR-03109-Modul.

Erforderliche Anpassungen

• Wenn Sie die CA über ein TCN-Gateway erreichen, prüfen Sie die Konnektivität vor der Umstellung.
• Wenn Sie den ServiceRuntime-Launcher einsetzen, wechseln Sie auf das Spring-Boot-Deployable.

Überprüfung

• Der Zugriff auf die CA und das Abrufen von CRLs funktionieren in Ihrer Umgebung.

Empfohlenes Vorgehen bei der Migration

1. Sichern Sie die Datenbank und Ihre aktuelle Konfiguration (hibernate.cfg.xml, application*.yml, Helm-Values, JAVA_OPTS).
2. Passen Sie die Konfiguration an:
   • Image-Name oder JDK 25
   • Probe-Pfade
   • aep.security.cors.pattern
   • Bouncr-/APIM-Werte, falls genutzt
   • DB-Variablen (DB_URL, DB_USERNAME)
3. Spielen Sie die Datensicherung in eine Testumgebung ein und starten Sie Security Server 25 dagegen. Prüfen Sie, dass das Upgrade durchläuft.
4. Führen Sie die Funktionstests der Abschnitte „Überprüfung“ aus.
5. Produktionsumstellung: Stoppen Sie alle alten Instanzen, deployen Sie die neue Version, warten Sie auf die Readiness und prüfen Sie die Logs auf Upgrade-Fehler.
6. Bewahren Sie die Datensicherung auf, bis ein vollständiger Zertifikatswechsel ohne Probleme durchlaufen wurde.