Migration zum User Management

Cookies

Bestehende Cookies vom Login können nach einem Update zu Konflikten führen. Lösche die Cookies und versuche den Login erneut.

Migrationszeitpunkt

Die Migration muss direkt nach dem Deployment erfolgen, bevor sich die ersten User einloggen. So kann die Entstehung von korrupten Datenständen verhindert werden.

Nötige Berechtigungen

Damit die Migration durchgeführt werden kann, muss der Benutzer die Role RootAdministrator haben im User Management.

Die Migration erfolgt über einen Export der Benutzerdaten aus dem Admin UI und dem Import der entsprechenden Datei im User Management.

Export der Benutzerdaten aus dem Admin UI

UI > Settings > Export users > Json File speichern

Schema des Benutzerexports

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "data": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "subject": {
            "type": "string",
            "format": "uuid"
          },
          "userName": {
            "type": "string"
          },
          "active": {
            "type": "boolean"
          },
          "email": {
            "type": "string",
            "format": "email"
          },
          "claims": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "id": {
                  "type": "string",
                  "format": "uuid"
                },
                "type": {
                  "type": "string"
                },
                "value": {
                  "type": "string"
                }
              },
              "required": ["id", "type", "value"]
            }
          },
          "logins": {
            "type": "array",
            "items": {}
          },
          "multiFactorAuthenticationActivated": {
            "type": "boolean"
          }
        },
        "required": [
          "subject",
          "userName",
          "active",
          "email",
          "claims",
          "logins",
          "multiFactorAuthenticationActivated"
        ]
      }
    }
  },
  "required": ["data"]
}

Nachbearbeitung des .json Exports

Nachbearbeitung

Damit die Migration sauber funktioniert, müssen folgende Schritte unbedingt durchgeführt werden!

Mit IDP Version 2.0 werden Claim Arrays unterstützt. Solche Claims müssen entsprechen vor dem Import korrigiert werden.

Unterstützung Claim Arrays

bisher	neu (muss im .json Export bei jedem user korrigiert werden!)
"adminui.scope": "users settings resources"	"adminui.scope": ["users", "settings", "resources"]

Claim tenant

Im User Management wird jeder Benutzer einem tenant zugewiesen. Der Claim "tenant" muss im .json Export bei jedem User ergänzt werden. Wenn eine Applikation bisher einen solchen Claim mit einem anderen Key geführt hat, muss dies vom alten Wert auf "tenant" migriert werden.

Claim Import

Wenn im User Management keine ClaimDefinition besteht für einen Claim, werden alle Claims mit dem Scope "User" und bearbeitbar durch Rolle "User" importiert. Damit dies korrekt gehandelt wird, sollen ClaimDefinitions im vorhinein erfasst werden.

Claim adminui.scope

Verwendung AdminUI

Bei Verwendung des User Managements soll die Verwendung des AdminUI auf das Minimum beschränkt werden. Die Änderung von Usern im AdminUI anstatt im User Management kann im schlimmsten Fall zu Systemfehlern führen.

Mit der Verwendung des User Management kann das AdminUI (aus Benutzersicht) grösstenteils abgelöst werden. Um Systemfehler zu verhindern soll die Berechtigung für das AdminUI grundsätzlich allen Benutzern aussert System Admins entzogen werden. Dies kann direkt im .json Export geschehen, indem der Claim "adminui.scope" bei allen Usern gelöscht wird. Alternativ kann die Claim Definition nach dem Import im UserManagement gelöscht werden -> dadurch werden automatisch alle solchen Claims bei allen usern gelöscht. Anschliessen kann die Claim Definition neu erstellt werden.

Benutzerdaten importieren (ins User Management)

Import

Falls deine Benutzerdaten nicht aus dem Admin UI stammen, wird das .json Schema vermutlich nicht übereinstimmen mit dem erwarteten Schema. Kontrolliere, dass es übereinstimmt Hier ist ein Beispielschema. Falls trotzdem ein Fehler auftritt beim Import, wird eine Logdatei heruntergeladen mit den Fehlern pro User.

1. Auf Admin Bereich gehen
2. Import Users wählen
3. JSON hochladen

Import Vorgehen

Management > Admin > Aktionen > Benutzer importieren

Jeder User im importierten JSON wird folgendermassen verarbeitet.

1. Es wird überprüft, ob ein tenant Claim vorhanden ist. Falls nicht, wird der User übersprungen
2. Existiert Tenant, falls nicht, Tenant mit TenantName und TenantKey erstellen
3. Danach wird überprüft, ob User bereits existiert. Existierende User werden Übersprungen
4. User wird erstellt mit folgendem Claim Mapping:
5. given_name → FirstName
6. family_name → LastName
7. locale → Localization
8. gender → Gender
9. mobile → Mobile
10. phone_number → Phone
11. Alle zusätzlichen Claims werden nach folgenden Regeln verarbeitet. Falls Claim auf Entität mit gleichem Typ und Wert bereits vorhanden ist, wird der Schritt übersprungen (Keine Mehrfacherfassung)
12. Falls Claimdefintion nicht existiert wird für Typ eine erstellt (Scope → User, Type → text, Required → false, DefaultValue → )
13. Claim anhand Definition erstellen. (z.B. bei Scope Tenant, Claim am Tenant zuordnen)
14. Hat User Fehlende Claims (Required Claim Definitions, welche nicht in den Importdaten sind), werden diese dem User hinzugefügt.