Dokumentation für B2B-Migration-Tool

B2B-Migration-Tool

Schnelldokumentation für das Migrationstool

Das B2B-Migrationstool ist eine Jar-Kommandozeilenanwendung. Es unterstützt zwei Hauptfunktionalitäten:

  1. Migration von Datenbankbenutzern zu Keycloak
  2. Migration von Arbeitsvorräten
  3. Migration der Datenbankrollen zu Keycloak
  4. Migration von Datenbankmandanten zu Keycloak

Nachfolgend finden Sie die Beispielkonfigurationsdatei application.yml. Es müssen nicht alle Felder konfiguriert werden, je nach dem ob eine lokale oder eine Migration via SSH durchgeführt werden soll. Bitte beachten Sie dazu die Kommentare in der folgenen Beispielkonfiguration. Bitte kopieren Sie das komplette Dokument, um das Migrationstool zu starten:

spring:
  main:
    banner-mode: off

# Keycloak configuration  
keycloak:
  serverUrl: http://localhost:9789/auth
  realm: master
  username: realm username
  password: realm password
  clientId: admin-cli

database:
  # Database driver which based on the database type this application need  to connect. Example can refer to https://www.codejava.net/java-se/jdbc/jdbc-driver-library-download database-connection-url-for-common-databases
  driver: org.postgresql.Driver
  # Database URL connection
  url: jdbc:postgresql://localhost:portnumber/DatabaseName
  username: dbUsername123
  # should quote '' the password value
  password: 'password123'
  # below contains two select statement, where second statement is for migration which will check user enddate whether is expired. Please use either one
  selectTableSql: SELECT * FROM b2bbp_adm_account
  # selectTableSql: SELECT * FROM b2bbp_adm_account LEFT JOIN b2bbp_adm_account_date_range ON b2bbp_adm_account.userid = b2bbp_adm_account_date_range.userid
  # basicColumns are columns from db, where it must be provided and migrate to keycloak. Below contain two example of configuration one is for migration which will check user expiration enddate. Please use either one
  # basicColumns: username:userid;firstname:firstname;lastname:lastname;email:email;enddate:enddate;password:password;
  basicColumns: username:userid;firstname:firstname;lastname:lastname;email:email;password:password
  # attributesColumns are columns from db, where is not necessary to be provided for keycloak user attribute
  attributeColumns: organization;
  # attributeColumns:

ssh:
  # if database require SSH connection, then enable must be true
  enable: false
  # provide ldap username and password for ssh connection
  username: Ldap account
  password: Ldap password
  host: Ssh server
  port: 22
  remoteDbServer: Remote Database server name
  # Remote database server port number
  remoteDbPort: 5413
  # local db port must same as above database url port, else connection will fail
  localDbPort: 5437

output:
  filePath: ..\\..\\OutputDirectory\\Result.txt

Unten ist die Standardkonfiguration für die Datei application.yml, ohne eine Verbindung mit ssh herzustellen und die postgres-Datenbank zu verwenden

Für diese Konfiguration werden selectTableSql, basicColumns und attributeColumns nicht in der Datei application.yml definiert. Es werden automatische Standardwerte für selectTableSql bereitgestellt: “SELECT * FROM b2bbp_adm_account”. basis Spalten sind “username:userid;firstname:firstname;lastname:lastname;email:email;password:password;” und attribut Spalte ist “organization;”

spring:
  main:
    banner-mode: off

keycloak:
  serverUrl: update keycloak server. Example: http://localhost:9789/auth
  realm: update realm name
  username: update realm username
  password: update realm password
  clientId: update client name

database:
  driver: org.postgresql.Driver
  url: jdbc:postgresql://localhost:portnumber/DatabaseName
  username: update username
  password: update password

Datenbankbenutzer-Migration zu Keycloak

Um die neue B2B-Benutzeroberfläche verwenden zu können, müssen alle Benutzer und die dazugehörigen Rollen mit Keycloack verwaltet werden. Das bedeutet, dass die Benutzer und Rollen nicht mehr in der B2B-Datenbank gespeichert werden. Daher müssen die Benutzerdaten von der bisherigen Datenbank auf den keycloak-Server migriert werden. Anmerkung: Bei der Benutzermigration werden nur Benutzer ohne Kennwort migriert.

Anforderungen des Migrationstools

Bevor mit der Benutzermigration zu Keycloak begonnen werden kann, müssen einige Voraussetzungen erfüllt sein, die zur Einrichtung erforderlich sind.

  1. Keycloak Server - Version > 10.0.0
    • Keycloak-Zugriffsrechte erforderlich: Lesen und Schreiben.
    • Einrichten eines Keycloak-Benutzers für die Verwendung bei der Migration
  2. B2B-Datenbank mit Zugang
    • Datenbank-Zugriffsrechte erforderlich: Nur Lesen.
  3. Java - Version >= 1.8
  4. LDAP-Konto
  5. Erstellen einer eigenen Datei application.yml durch Kopieren des obigen Beispielinhalts

Anforderungen zur Passwort Migration

Falls gewünscht ist, neben den Usern auch die Passwörter aus der B2B-Datenbank nach Keycloak zu migrieren, so muss die von NLI bereitgestellte b2bbp-hash.jar unter keycloak/standalone/deployments/ hinterlegt werden. (Dies ist im Keycloak-Dockerimage automatisch gegeben.)

Keycloak-Benutzer einrichten

Um das Migrationstool erfolgreich auszuführen, muss ein Keycloak Server laufen, sowie entsprechnde Clients und Benutzer vorhanden sein. Folgende Schritte sind dazu notwendig:

  1. Wenn Keycloak neu eingerichtet ist und kein Realm vorhanden ist, erstellen Sie bitte einen neuen Realm, andernfalls können Sie einen bestehenden für die Benutzermigration verwenden.
    • Einen neuen Realm erstellen:
  2. Falls Sie mehrere Benutzer unter der gleichen E-Mail Adresse nutzen wollen, schalten Sie “Login with E-Mail” (Unter Realm Settings -> Login) aus und dann Erscheint eine Option “Duplicate emails”. Diese müssen Sie aktivieren.
  3. klicken Sie dann unter dem gewünschten Realm auf Clients, um einen neuen Client zu erstellen.
    • Nachdem der neue Client erstellt wurde, stellen Sie sicher, dass der Access Type = public und die Einstellung Direct Access Grants Enabled = ON ist.
  4. Nachdem Sie den Client erstellt haben, erstellen Sie eine neue Rolle
    • Nach dem Speichern aktivieren Sie für die neu hinzugefügte Rolle dann die Composite Roles EIN. Geben Sie dann in Client Roles “realm-management” ein und fügen Sie dann alle verfügbaren Rollen hinzu.
  5. Nachdem Sie eine neue Rolle erstellt haben, gehen Sie zum Reiter Users, um die Rolle dem Benutzer zuzuweisen. Es kann ein vorhandener Benutzer verwendet werden oder ein neuer Benutzer angelegt werden. Dieser Nutzer wird vom Migrationstool verwendet um die weiteren Migrationsschritte durchzuführen.
    • Falls Sie für die Migration einen neuen Benutzer anlegen möchten, müssen Sie sicherstellen, dass das Kennwort nach dem Anlegen des Benutzers korrekt eingestellt ist. Temporär sollte ausgeschaltet sein. Zur Probe sollten sich sich einmalig mit diesem User in Keycloak anmelden.
    • Gehen Sie dann zum Konfigurieren zur Registerkarte Role Mappings. Fügen Sie in Realm Roles die neu hinzugefügte Migrationsrolle zu Assigned Roles hinzu. Geben Sie dann unter Client Roles den neu hinzugefügten Client ein, z.B. migration-cli.

  6. Nach der Konfiguration sollten alle oben genannten Relams, Client- und Benutzereinstellungen in der Datei application.yml verwendet werden.

Schritte zum Ausführen des Migrationstools

Nachdem Sie die b2b-Migrations-Tool-Jar-Datei erhalten haben, starten Sie eine CMD-Eingabeaufforderung, um die Anwendung auszuführen. Folgen Sie dann den folgenden Schritten:

  1. Erforderlich ist die b2b-migration-tool jar-Datei und die passenden Datenbanktreiber jar-Datei z.B. Verknüpfung, Hinweis: die Migration kann mit jeder Datenbank durchgeführt werden, solange der richtige Treiber verwendet wird.
  2. Nachdem Sie beide Jar-Dateien erhalten haben, erstellen Sie einen Ordner, z.B. b2b-migration-tool, dann erstellen Sie zwei Ordner innerhalb des Verzeichnisses, z.B.:
    • Legen Sie dann beide jar-Dateien in den lib-Ordner
    • Und erstellen Sie dann die Datei application.yml und legen diese in den config-Ordner
  3. Nachdem die Einrichtung des Ordners abgeschlossen ist, starten Sie die Eingabeaufforderung und geben Sie folgenden Befehl ein: java -cp …filepath...\config\;…filepath...\lib* org.springframework.boot.loader.JarLauncher
  4. Nachdem Sie den obigen Befehl ausgeführt haben, wird ein Konsolenmenü angezeigt:
  5. Wählen Sie den 1. Punkt um die bisherigen Benutzer aus der Datenbank nach Keycloak zu migrieren
  6. Vergewissern Sie sich, ob die obige Datei application.yml korrekt konfiguriert wurde. Nur dann kann die Anwendung erfolgreich ausgeführt werden. Details können Sie dem obigen Beispiel der application.yml und der darin enthaltenen Kommentare entnehmen.
  7. Die application.yml enthält eine filePath-Konfiguration. Dort werdenim Fehlerfall weitere Informationen hinterlegt.

Migration von Arbeitsvorräten

Wenn Kunden die neue B2B-Benutzeroberfläche verwenden und erwarten, dass die bisherigen Arbeitsvorräte weiter verwendet werden können, dann hilft diese Migration bei der Migration von der alten Konfiguration zur neuen Konfiguration. Die alte Konfiguration bezieht sich auf die Definition eines Arbeitsvorrats, so wie dieser in der Tabelle b2bbp_adm_role_attribute gespeichert ist. Dann bereinigt das Migrationstool die Daten und migriert sie nach b2bbp_adm_extension mit dem neuen Datentyp = “WORKLISTS”. Anmerkung: Das Migrationstool migriert bisher nur den Worklist-Typ = “MSGMON”.

Anforderungen

Bevor mit der Migration der Arbeitsvorräte begonnen wird, sind einige Anforderungen zu erfüllen:

  1. B2B-Datenbank mit Zugang
    • Erforderliche Datenbank-Zugriffsrechte: Lesen und Schreiben.
  2. Java - Version >= 1.8
  3. LDAP-Konto
  4. Erstellen einer eigenen Datei application.yml durch Kopieren des obigen Beispielinhalts

Schritte

Nachdem Sie die b2b-Migrations-Tool-Jar-Datei erhalten haben, starten Sie eine CMD-Eingabeaufforderung, um die Anwendung auszuführen. Folgen Sie dann den folgenden Schritten:

  1. Erforderlich ist die b2b-migration-tool jar-Datei und die Datenbanktreiber jar-Datei, z.B. https://www.codejava.net/java-se/jdbc/jdbc-driver-library-download. Hinweis: die Migration kann mit jeder Datenbank durchgeführt werden, solange der richtige Treiber verwendet wird.
  2. Nachdem Sie beide Jar-Dateien erhalten haben, erstellen Sie einen Ordner, z.B. b2b-migration-tool, dann erstellen Sie zwei Ordner innerhalb des Verzeichnisses, z.B.:
    • Legen Sie dann beide jar-Datein in den lib-Ordner
    • Und erstellen Sie dann die Datei application.yml und legen diese in den config-Ordner
  3. Nachdem die Einrichtung des Ordners abgeschlossen ist, starten Sie die Eingabeaufforderung und geben Sie folgenden Befehl ein: java -cp …filepath...\config\;…filepath...\lib* org.springframework.boot.loader.JarLauncher
  4. Nachdem Sie den obigen Befehl ausgeführt haben, wird ein Konsolenmenü angezeigt:
  5. Wählen Sie die 2. Auswahl um die Arbeitsvorräte zu migrieren
  6. Für die Migration der Arbeitsvorräte ist nur die Konfiguration des Datenbanktreibers, der URL, des Benutzernamens, des Kennworts und des Ausgabedateipfads(filePath) erforderlich. Andere Konfigurationen sind nicht erforderlich.
  7. Wenn die Migration erneut ausgeführt wird, überschreibt sie die vorhandenen Daten mit den neuen Daten aus der alten Tabelle. Die application.yml enthält die filePath-Konfiguration, die der Benutzer konfigurieren kann, um zu wissen, welche alten Daten überschrieben wurden.

Automatische Rollenerstellung in keycloack mit Hilfe des Migrationstools

Diese Funktion dient dazu, um auf einfache Weise alle notwendigen Rollen in keycloak anzulegen, Gruppen automatisch zu erstellen und Rollen gem. der Konfigurationsdatei “group-roles.yml” entsprechenden Gruppen zuzuweisen.

Mit Hilfe des Parameters “defaultGroups” in der Konfigurationsdatei group-roles.yml können vorher festgelegte Standardgruppen automatisch allen Benutzern hinzugefügt werden. Dafür muss zunächst die Funktion “3 - Database role migration to keycloak” im Migrationstool ausgeführt werden und anschließend die Benutzermigration “1 - Database user migration to keycloak.”

Wenn den Benutzern eine Standardgruppe hinzugefügt wird, bedeutet dies, dass die Benutzer alle Rollen der Standardgruppe zugewiesen bekommen. In unserem Beispiel sind dies alle Rollen die unter der Gruppe “users” aufgelistet sind.

Schritte

Ähnlich wie die Schritte bei der Migration von Datenbankbenutzern zu Keycloak.

Erstellen Sie in Schritt 2 eine zusätzliche yml-Gruppenrollen-Datei “group-roles.yml” und legen Sie sie im config-Ordner ab.

Wählen Sie in Schritt 5 die drei um Rollen in der keyloack Datenbank anzulegen:

Beispiel

  1. Konfiguration für group-roles.yml 
    defaultGroups: [users]
groups:
  users:
    - b2bbp
    - B2BPortal-UI
    - B2B-Dashboard
    - FSS-CertificateManager-Read
    - RevisionManager-Read
    - B2B-IndexManagement
    - B2B-MessageMonitor-Read
    - B2B-MpidEditor-Read
    - FSS-RuleManager-Read
    - B2B-UserMessages-Read
    - B2B-ManualMarketCommunication
    - B2B-MessageMonitor-Write
    - B2B-MpidEditor-Write
    - B2B-SystemSwitch
    - FSS-CertificateManager-Write
  admins:
    - b2bbp
    - B2BPortal-UI
    - B2B-Dashboard
    - FSS-CertificateManager-Read
    - RevisionManager-Read
    - B2B-IndexManagement
    - B2B-MessageMonitor-Read
    - B2B-MpidEditor-Read
    - FSS-RuleManager-Read
    - B2B-UserMessages-Read
    - B2B-ManualMarketCommunication
    - B2B-MessageMonitor-Write
    - B2B-MpidEditor-Write
    - B2B-SystemSwitch
    - FSS-CertificateManager-Write
    - RevisionManager-Write
    - B2BAdmin-Dashboard
    - B2BAdmin-QueueMonitor-Read
    - B2BAdmin-CommunicationRelations-Read
    - B2BAdmin-SystemErrors-Read
    - FSS-RuleManager-Write
    - B2B-Errors
    - B2B-MessageMonitor-TechnicalDetails
    - B2B-SystemSwitch-Admin
    - B2BAdmin-Customizing
    - FSS-ClientManager-Read
    - B2B-UserMessages-Write
    - B2BAdmin-Customizing
    - B2BAdmin-LockTables
    - B2BAdmin-QueueMonitor-Write
    - B2BAdmin-CommunicationRelations-Write
    - B2BAdmin-SystemInfo
    - B2BAdmin-SystemErrors-Write

    Die Defaultgruppen müssen vorher in Keycloak bereits angelegt sein.

Die Liste der Rollen orientiert sich an den offiziellen B2B-Rollen.

  1. Die Rollen werden nach Durchführung der Rollenmigration in keycloack angelegt.
    a. Vor dem Lauf

    b. Nachdem das Tool ausgeführt wurde, sind sämtliche Rollen angelegt. Zusätzliche wurden die Gruppen users und admins angelegt. Alle Rollen, die in der group-roles.yml unter groups > users definiert wurden, sind automatisch der Gruppe users zugewiesen. Dasselbe gilt für die Gruppe admins.
  2. Führen Sie nun die Migration der B2B-Benutzer durch oder wiederholen Sie die Migration der B2B-Benutzer zu Keycloak falls diese bereits durchgeführt wurde

    a. Die Logik bei der Migration von Datenbankbenutzern zu Keycloak bleibt erhalten, wenn keine Konfiguration für die defaultGroups in der group-roles.yml vorgenommen wurde.
    b. Wenn eine unter defaultGroups konfigurierte Gruppe nicht vorhanden ist: Die Gruppe users1 existiert nicht unter groups > users sondern nur unter defaultGroups. Eine Benutzermigration wird zwar durhgeführt, das Migrationstool gibt aber eine entsprechende Fehlermeldung aus, dass die Gruppe users1 nicht vorhanden ist. Es werden dementsprechnd auch keine Rollen zugewiesen.
    c. Wenn die unter defaultGroups konfigurierte Gruppe unter groups > users vorhanden ist: Die Benutzermigration aus der B2B Datenbank zur keycloack Datenbank wird problemlos durchgeführt und die Gruppe users wird allen Benutzern in keycloak zugeordnet.

Migration von Mandanten/Tenants für die Mandantenfilterung

Damit Benutzer auch in der neuen UI auf die verschiedenen Systeme gem. der bisherigen Mandantenfilterung zugreifen können, muss eine weitere Migration “4 - Database tenant migration to keycloak” mit Hilfe des Migrationstools durchgeführt werden.

Die alte Konfiguration bezieht sich auf die AllowedSystem-Einträge in den B2B Rollenattributen in der alten Flex UI, welche den einzelnen Benutzern zugewiesen wurden.

Das Migrationstool migriert diese Einträge in eine neue Extension “TENANTS”. Falls diese Extension noch nicht vorhanden ist wird sie vom Migrationstool automatisch angelegt.

Diejenigen Attribute, deren Rollenattribut ID mit AllowedSystem beginnt, wurden bisher immer Rollen und diese Rollen via Rollenzuordung einem benutzer zugewiesen. Das Migrationstool wird die entsprechenden Attribute den gleichen Benutzern zuweisen, falls sie bereits zu Keycloak migrieren wurden.

Schritte

Ähnlich wie die Schritte bei der Migration von Datenbankbenutzern zu Keycloak, aber wählen Sie ab Schritt 5 die vierte Wahl “4 - Database tenant migration to keycloak”.
Wenn die Migration mehrfach ausgeführt wird, werden die vorhandenen Daten jeweils mit den neuen Daten überschrieben. Die application.yml enthält in der filePath-Konfiguration den Pfad zur Log-Datei, in der nach der Migration eingesehen werden, kann welche Daten übertragen wurden.

Beispiel

  1. Alte Daten
    a. Die Datenbanktabelle der Rollenattribute enthält Daten mit Rollenattribut-ID, die mit AllowedSystem beginnen. Diese Einträge entsprechen der Attribute ID und dem Wert aus der alten B2B UI in Tab Attribute in der Benutzerverwaltung

    b. Benutzer hat Rollenattribut id welche mit AllowedSystem beginnt

  2. Nach Ausführung des Migrationstools
    Die Daten werden in eine neue Extension “TENANTS” übertragen und in die Ausgabedatei result.txt geschrieben

    Nach dem Ausführen des Migrationstools wurde dem Benutzer Meckerb2bonly in keycloack das Attribut “tenants” sowie die passenden Werte gem. der bisherigen AllowedSystem-Konfuguration hinzugefügt.
View Me   Edit Me