CARA3 Migration
Referenz: [CARA3_Migrationshandbuch]
Versionsinformationen
In der folgenden Tabelle finden Sie die Änderungshistorie des vorliegenden Dokuments.
| Version | Bemerkung |
|---|---|
3.4.0 |
|
3.3.1 |
|
3.3.0 |
|
3.2.0 |
|
3.1.0 |
|
3.0.0 |
|
Migrationsanleitung
Im Folgenden sind die wichtigsten Schritte für die Migration auf eine neuere CARA-Version aufgeführt.
Update von Version 2.8.x auf 3.0.0
Keycloak
Das mitgelieferte Keycloak-Setup-Skript muss ausgeführt werden, um die Keycloak-Instanz initial aufzusetzen. Dabei werden unter anderem Keycloak-Clients für den Cara-Server und die CARA Admin UI angelegt. Zusätzlich wird auch ein Default Admin Benutzer angelegt, der einen initialen Zugriff auf das Admin-Frontend erlaubt. Nach dem Anlegen weiterer Benutzer kann dieser Benutzer deaktiviert werden.
Die Anmeldung am neuen Admin Operator Frontend ist nur noch mittels Keycloak möglich. Eine Anmeldung mittels RA-Zertifikat wird nicht mehr direkt unterstützt. Vorhandene RA-Zertifikate können aber gegebenenfalls zur TLS-Clientauthentifizierung gegenüber Keycloak verwendet werden.
Zur Anmeldung am Admin Operator Frontend muss der Benutzer die CARA-Rolle "Administrator" sowie mindestens eine Admin-Rolle besitzen. Im alten Admin Operator Frontend hatte ein Benutzer (= RA-Zertifikat) mit der Rolle "Administrator" standardmäßig alle Rechte und diese Rechte konnten durch die Zuweisung von Admin-Rollen eingeschränkt werden. Ab CARA 3.0 muss der Benutzer stattdessen die Admin-Rolle "SuperAdmin" mit allen Rechten besitzen, um uneingeschränkten Zugriff auf das Admin-Frontend zu haben.
Die vorhandenen RA-Zertifikate können samt zugeordneter Admin- und TcOp-Rollen nach Keycloak migriert werden. Bei Verwendung von Flyway geschieht das im Rahmen der Datenbank-Migration automatisch. Wenn kein Flyway verwendet wird, muss stattdessen das Kommando migrateAdminRolesAndUsersToKeycloak der CARA Admin-CLI ausgeführt werden, um die Migration auszuführen.
Bei der Migration werden für alle RA-Zertifikate, die die folgenden Bedingungen erfüllen, automatisch Benutzer in Keycloak angelegt:
-
Das Zertifikat muss zur ROOT-Domain gehören.
-
Das Zertifikat muss die "Administator" oder die "TrustCenter Operator"-Rolle besitzen.
-
Das Zertifikat muss noch gültig sein und darf noch nicht erneuert worden sein.
-
Für den zugehörigen Zertifikatsrequest muss ein Ident-Data-Eintrag mit einem der in
knownEmailIdentDataNameskonfigurierten Ident-Data-Key existieren. Username und E-Mail-Adresse des Benutzers werden mit dem Ident-Data-Wert vorbelegt.
Falls mehrere RA-Zertifikate für die gleiche E-Mail-Adresse existieren, werden die Admin- und TcOp-Rollen aller RA-Zertifikate zusammengeführt und zum angelegten Benutzer hinzugefügt.
Voraussetzung für die erfolgreiche Migration ist das Hinzufügen der notwendigen Konfigurationsparameter zu den application.properties des Cara-Servers bzw. der CARA Admin-CLI, siehe Konfiguration.
Für die Migration der RA-Zertifikate ist neben den Keycloak-Verbindungsparametern vor allem der Parameter knownEmailIdentDataNames relevant. Wenn Flyway verwendet wird und keine automatische Migration stattfinden soll, kann dieser Parameter auf einen ungültigen Wert gesetzt werden. Wenn kein passender Ident-Data-Eintrag existiert, findet auch keine Migration des jeweiligen RA-Zertifikats statt.
Zu beachten: Die Benutzer sind nach der Migration zunächst nur in Keycloak bekannt und müssen noch als Keycloak-Benutzer in die CARA-Datenbank synchronisiert werden. Es findet somit auch keine automatische Migration der CARA-Rollen des RA-Zertifikats statt. Dafür existieren die folgenden zwei Optionen:
-
Wenn das Property
application.openid.sync-on-first-login.enabledauftruegesetzt ist, wird ein Benutzer, der in Keycloak mindestens eine Admin-Rolle besitzt, beim ersten Login automatisch in die CARA-Datenbank synchronisiert und bekommt die CARA-Rolle "Administrator" zugewiesen. Wenn er in Keycloak mindestens eine TcOp-Rolle besitzt, bekommt er analog die CARA-Rolle "TrustCenter Operator" zugewiesen. -
Der Benutzer kann im Admin-Frontend manuell aus Keycloak in die CARA-Datenbank synchronisiert werden. Dabei können dem Benutzer die gewünschten CARA-Rollen explizit zugewiesen werden. Um sich im Admin Frontend anmelden zu können, muss ein Benutzer die CARA-Rolle "Administrator" und mindestens eine Admin-Rolle besitzen.
Weitere Benutzer können entweder direkt in Keycloak oder über das Admin-Frontend angelegt werden. Beim Anlegen von Benutzern in Keycloak ist zu beachten, dass diese der Gruppe CARA zugeordnet werden müssen. Damit bekommen sie in Keycloak automatisch die CARA_USER-Rolle, die für die Anmeldung an CARA ebenfalls notwendig ist.
Konfiguration
application.properties des Cara-Servers und der CARA Admin-CLI
In der folgenden Tabelle sind alle Konfigurationsparameter aufgelistet, die in Version 3.0.0 neu dazugekommen sind. Mit Ausnahme der beiden Properties application.openid.unsync.enabled und application.openid.sync-on-first-login.enabled gelten sie sowohl für den Cara-Server als auch für die CARA Admin-CLI. Die beiden genannten Properties sind nur für die Cara-Server-Konfiguration relevant.
Für die CARA Admin-CLI müssen die Properties nur dann konfiguriert werden, wenn das Kommando migrateAdminRolesAndUsersToKeycloak ausgeführt werden soll. Für alle anderen Kommandos werden sie weiterhin nicht benötigt.
| Parameter | Beschreibung |
|---|---|
Die nachfolgenden Settings mit den Präfixen |
|
|
Client-ID des Cara-Servers. |
|
Client Secret des Cara-Servers. |
|
Basis-URL der Keycloak Admin REST API. |
|
Optional. Pfad für den Truststore, der zur Pfadvalidierung des Keycloak-Server-Zertifikats verwendet wird. Wenn das Property nicht gesetzt ist, wird der Default Java-Truststore verwendet. |
|
Optional. Passwort für den Truststore, der zur Pfadvalidierung des Keycloak-Server-Zertifikats verwendet wird. |
|
Optional. Typ des Truststores, der zur Pfadvalidierung des Keycloak-Server-Zertifikats verwendet wird. Gültige Werte sind: |
|
TLS-Version, die zur Kommunikation mit dem Keycloak-Server verwendet wird. Gültige Werte sind: |
|
Timeout für die Verbindung zur Keycloak Admin REST API in Sekunden. |
|
Basis-URL des Keycloak-Realms. |
|
URL zum Abruf der öffentlichen Signaturschlüssel des Keycloak-Realms. Die Schlüssel werden als JSON Web Keys (JWKs) zurückgegeben. |
|
OAuth Provider. |
|
Client-ID des Cara-Servers. |
|
Client Secret des Cara-Servers. |
|
Authorization Grant Type. |
|
URL des Token-Endpunkts des Keycloak-Realms. |
|
|
|
|
|
Dieser Wert wird nur einmalig während der Migration der RA-Zertifikate zu Keycloak verwendet. Er sollte alle bekannten Ident-Daten-Namen enthalten, die eine RA-Zertifikats-E-Mail repräsentieren, und wird verwendet, um RA-Zertifikate als Keycloak-Benutzer automatisch zu migrieren. |
application.properties des Admin-Frontends
Für das neue Admin-Frontend stehen in Version 3.0.0 die folgenden Parameter zur Verfügung:
| Parameter | Beschreibung |
|---|---|
|
HTTP Server Port |
|
HTTP Server Bind Address |
|
Kontextpfad, unter dem das Admin-Frontend erreichbar sein soll. |
|
Cara-Server-URL. |
|
Basis-URL des Keycloak-Realms. |
Datenbank-Migration
In diesem Abschnitt sind die Datenbankskripte aufgelistet, die bei einem Update von Version 2.8.x auf Version 3.0.0 ausgeführt werden müssen. Bei Verwendung von Flyway werden die Skripte automatisch ausgeführt. Alternativ ist eine manuelle Aktualisierung der Datenbank notwendig.
Es sind zunächst die folgenden Migrationsskripte für das Update auf Version 2.9.0 auszuführen:
-
1_DeleteKeyCachingModule.sql -
2_DeleteOnlineProductionData.sql
Bei Version 2.9.0 handelt es sich um eine noch nicht veröffentlichte CARA-Version, die die Grundlage für die Version 3.0.0 bildet.
Anschließend sind für das Update auf Version 3.0.0 die folgenden Migrationsskripte auszuführen:
Die Migrationen müssen unbedingt in der hier genannten Reihenfolge ausgeführt werden. Wenn kein Flyway verwendet wird, muss nach Skript 1 stattdessen das Kommando migrateAdminRolesAndUsersToKeycloak der CARA Admin-CLI ausgeführt werden, bevor mit den restlichen SQL-Skripten fortgefahren wird.
|
-
1_AddOidcUser.sql -
MigrateAdminRolesAndUsersToKeycloak- hierbei handelt es sich um eine Java-Migration, die bei Verwendung von Flyway automatisch ausgeführt wird und ansonsten als Admin-CLI-Kommando verfügbar ist. -
3_ApplyNewNamingConventions.sql -
4_DropAdminRolesAndPermissions.sql -
5_AddOidcUserTemplate.sql
Template-Signer-Konfiguration zur Ausstellung von OIDC-Benutzer-Zertifikaten
Wenn das Admin Operator Frontend zur Ausstellung von Benutzer-Zertifikaten verwendet werden soll, die für die TLS-Clientauthentifizierung gegenüber Keycloak verwendet werden können, muss vorher der OIDC-Template-Signer konfiguriert werden. Das ist über das Admin Operator Frontend möglich. Die Konfiguration erfolgt auf der Seite System > OIDC-Template-Signer Definition. Es wird eine Kombination von Signer (CA-Zertifikat) und Template zur Ausstellung von Zertifikaten für Keycloak-Benutzer eingestellt. Es stehen nur Zertifikats-Templates zur Verfügung, bei denen OIDC="true" gesetzt ist. Ein passendes Template wird bei der Datenbank-Migration automatisch angelegt und kann bei Bedarf editiert werden. Es hat den Namen "CARA OIDC user".
| Bei Anpassung des Templates sollte darauf geachtet werden, dass die E-Mail-Adresse bevorzugt in der Subject Alternative Name (SAN) Extension als rfc822Name oder alternativ (deprecated) im Subject Distinguished Name (Subject DN) als Attribut "emailAddress" enthalten ist. Beim Ausstellen von Benutzer-Zertifikaten wird die E-Mail-Adresse des Benutzers dann automatisch in das entsprechende Feld eingetragen. Bei der TLS-Clientauthentifizierung an Keycloak wird die E-Mail-Adresse aus dem Zertifikat gelesen und auf einen passenden Benutzer gemappt. |
Truststore-Konfiguration
Wenn es möglich sein soll, sich mit TLS-Clientzertifikat am Keycloak anzumelden, muss das entsprechende (Root-)CA-Zertifikat des OIDC-Template-Signers in den Trustore von Keycloak (bzw. des vorgeschalteten Apache Servers) importiert werden.
Für die TLS-Clientauthentifizierung könnten auch beliebige andere Zertifikate einschließlich der bisher genutzten RA-Zertifikate verwendet werden, sofern die E-Mail-Adresse des Benutzers darin enthalten ist. Falls die verwendeten Zertifikate von einer anderen CA stammen, muss auch diese in den Truststore importiert werden.
Test der Anwendung
Nach dem Start des Cara-Servers kann die Swagger UI mit der CARA-WS-API unter der folgenden URL abgerufen werden:
<Cara-Server-URL>/swagger-ui/index.html
Die CARA-WS-API und Admin-API sind unter den URLs <Cara-Server-URL>/api/* bzw. <Cara-Server-URL>/admin/* verfügbar.
| Die Admin-API ist nur für die Nutzung durch das Admin-Frontend vorgesehen. Es handelt sich nicht um eine offene, für Kunden dokumentierte und zur Anwendungsentwicklung vorgesehene API. |
Update von Version 3.0.0 auf 3.1.0
-
Es gilt die allgemeine Verfahrensweise gemäß Abschnitt 4.1 des Dokuments
[Installationshandbuch_Admin]. -
Es sind keine SQL-Skripte auszuführen.
-
Es gibt keine Änderungen an Konfigurationsdateien, sofern nicht die Erreichbarkeit der OpenAPI-Spezifikation und Swagger UI abgeschaltet werden soll.
Abschaltung der Erreichbarkeit der OpenAPI-Spezifikation
Das bisher unterstütze Property api.documentation.public wurde entfernt. Stattdessen können die Springdoc-Standard-Properties springdoc.api-docs.enabled und springdoc.swagger-ui.enabled verwendet werden, um die Erreichbarkeit der OpenAPI-Spezifikation feingranular zu steuern. Beide müssen auf den Wert false gesetzt werden, damit weder die OpenAPI-Spezifikation noch die Swagger UI erreichbar ist. Die offizielle Dokumentation der unterstützen Springdoc Properties ist hier zu finden: springdoc.org/properties.html
Update von Version 3.1.0 auf 3.2.0
-
Es gilt die allgemeine Verfahrensweise gemäß Abschnitt 4.1 des Dokuments
[Installationshandbuch_Admin]. -
Es ist ein Datenbankskript auszuführen:
-
1_DropHsmPasswordMap.sql
-
-
Es müssen Änderungen an den Konfigurationsdateien vorgenommen werden wie im Folgenden dokumentiert.
-
Das Format der gespeicherten Passwörter für die Wiederherstellung von Logins für Generic HSM-Devices wurde verändert. Die vorhandenen gespeicherten Passwörter können deshalb nicht weiter verwendet werden und werden aus der Datenbank gelöscht. Damit die Funktionalität weiterhin genutzt werden kann, ist eine einmalige Neuanmeldung der HSM-Benutzer im Admin-Frontend notwendig.
application.properties des Cara-Servers
Elasticsearch
Bedingt durch das Update auf Spring Boot 3 haben sich die Properties für die Konfiguration von Elasticsearch verändert. Das Präfix der Properties wurde von management.metrics.export.elastic.* zu management.elastic.metrics.export.* geändert. Wenn Elasticsearch verwendet wird und die von CARA vorgegebenen Defaultwerte überschrieben werden sollen, müssen die Properties entsprechend angepasst werden.
Beispiel:
| Alter Parameter | Neuer Parameter |
|---|---|
|
|
Analog müssen auch alle anderen Properties angepasst werden. An dieser Stelle sei auf die allgemeine Spring Boot-Dokumentation verwiesen, siehe docs.spring.io/spring-boot/3.5/appendix/application-properties/index.html.
Spring Boot Actuator
Ebenso haben sich auch die Properties für den Zugriff auf die Spring Boot Actuator-Endpunkte verändert. Standardmäßig sind, wie bisher, alle Actuator-Endpunkte außer dem Health-Endpunkt deaktiviert.
| Alte Default-Konfiguration | Neue Default-Konfiguration |
|---|---|
|
|
Auch in diesem Fall sei für Details auf die allgemeine Spring Boot-Dokumentation verwiesen.
CARA Properties
Das Property hibernate.dialect für die Konfiguration der CARA Datenbank-Verbindung is obsolet und wird nicht mehr verwendet. Es kann aus application.properties entfernt werden. Gleiches gilt auch für die Datenbank-Konfiguration im LPM-Modul. Diese Anpassung ist optional.
Außerdem wurde folgendes Property umbenannt:
| Alter Parameter | Neuer Parameter |
|---|---|
|
|
Damit wird festgelegt, ob ein Keycloak-Benutzer, der noch nicht in CARA bekannt ist, beim ersten Login automatisch in die CARA-Datenbank synchronisiert wird. Voraussetzung hierfür ist, dass der Keycloak-Benutzer die Realm-Rolle CARA_USER und mindestens eine Admin-Rolle besitzt. Dann bekommt er bei der Synchronisation automatisch auch die Rolle "Administrator" zugewiesen und kann sich erfolgreich am Admin-Frontend anmelden.
Zusätzlich wurde folgendes Property neu eingeführt:
| Parameter | Beschreibung |
|---|---|
|
|
Update von Version 3.2.0 auf 3.3.0
-
Es gilt die allgemeine Verfahrensweise gemäß Abschnitt 4.1 des Dokuments
[Installationshandbuch_Admin]. -
Die Version enthält keine Datenbank-Aktualisierungen.
-
Die Version enthält keine neuen Konfigurationsparameter.
In Version 3.2.0 war es unter MariaDB 10.7+ nicht möglich, neue OIDC-Benutzer anzulegen. Das Problem konnte durch Setzen der System Property -Dhibernate.type.preferred_uuid_jdbc_type=BINARY behoben werden. Dieser Workaround ist nicht mehr notwendig und kann entfernt werden.
|