Benutzer Import & Export

Auris bietet ein Massen-Import- und -Export-System für Benutzerdaten. Import ist nützlich für die Migration von einem bestehenden Identity Provider, das Onboarding einer Gruppe von Mitarbeitern aus einem HR-System oder das Seeden von Benutzern in einem neuen Tenant. Export ist nützlich für die Erstellung von Backups, das Audit deiner Benutzerbasis oder die Migration zu einem anderen System.

Beide Operationen sind asynchron. Auris verarbeitet die Datei im Hintergrund und stellt einen Job-Status-Endpunkt bereit, so dass du auf den Abschluss warten oder einen Fortschrittsindikator anzeigen kannst.

Import-Formate

Auris akzeptiert zwei Dateiformate für den Benutzer-Import.

CSV-Format

Die erste Zeile muss eine Kopfzeile sein. Die Reihenfolge der Spalten spielt keine Rolle, aber die Spaltennamen müssen exakt übereinstimmen.

email,username,firstName,lastName,password,roles
[email protected],alice,Alice,Rossi,TempPass123!,member
[email protected],bob,Bob,Marley,,member|billing-admin
[email protected],,Carol,White,,,

Spaltenreferenz:

JSON-Format

Die Datei muss ein JSON-Array von Benutzerobjekten enthalten. Felder stimmen mit den CSV-Spaltennamen überein.

[
  {
    "email": "[email protected]",
    "username": "alice",
    "firstName": "Alice",
    "lastName": "Rossi",
    "password": "TempPass123!",
    "roles": ["member"]
  },
  {
    "email": "[email protected]",
    "roles": ["member", "billing-admin"]
  }
]

Import-Prozess

curl -X POST https://auth.yourdomain.com/api/users/import \
  -H "Authorization: Bearer $TOKEN" \
  -H "x-tenant: your-tenant" \
  -F "[email protected]"

{
  "ok": true,
  "data": {
    "id": "import_01HX...",
    "fileName": "benutzer.csv",
    "format": "CSV",
    "status": "PENDING",
    "totalRows": 0,
    "processedRows": 0,
    "successCount": 0,
    "errorCount": 0,
    "createdAt": "2025-06-10T14:00:00Z"
  }
}

{
  "ok": true,
  "data": {
    "id": "import_01HX...",
    "status": "PARTIAL",
    "totalRows": 150,
    "processedRows": 150,
    "successCount": 147,
    "errorCount": 3,
    "errors": [
      {
        "row": 12,
        "email": "[email protected]",
        "reason": "E-Mail-Adresse existiert bereits in diesem Tenant"
      },
      {
        "row": 67,
        "reason": "Pflichtfeld fehlt: email"
      },
      {
        "row": 103,
        "email": "ungueltige-email",
        "reason": "Ungültiges E-Mail-Adressformat"
      }
    ]
  }
}

Import-Verhalten

Wie Auris Grenzfälle beim Import behandelt:

Doppelte E-Mails: Wenn ein Benutzer mit derselben E-Mail bereits im Tenant existiert, wird die Zeile übersprungen und als Fehler gezählt. Der bestehende Benutzerdatensatz wird nicht geändert.

Fehlende Passwörter: Benutzer, die ohne Passwort erstellt werden, werden in einem deaktivierten-Anmeldedaten-Zustand provisioniert. Sie müssen den “Passwort vergessen”-Flow verwenden oder eine von einem Admin ausgelöste Passwort-Reset-E-Mail erhalten, um Zugang zu erhalten.

Rollenzuweisung: In der Importdatei aufgeführte Rollen werden nach der Benutzererstellung zugewiesen. Wenn ein Rollenname im Tenant nicht existiert, wird die Zeile als partieller Fehler markiert — der Benutzer wird erstellt, aber die Rollenzuweisung schlägt fehl.

Keycloak-Synchronisation: Jeder erfolgreich importierte Benutzer wird sowohl in der Auris-Datenbank als auch im zugrundeliegenden Keycloak-Realm erstellt. Die beiden Datensätze sind über keycloakId verknüpft.

Transaktionsmodell: Auris verarbeitet Zeilen einzeln statt in einer einzigen Transaktion. Ein Fehlschlag in Zeile 50 macht die Zeilen 1–49 nicht rückgängig.

Import-Jobs auflisten

Benutzer exportieren

Benutzer-Export generiert eine Datei mit allen aktiven (nicht gelöschten) Benutzern im Tenant. Die Operation ist asynchron: Du löst den Export aus und lädst die Datei herunter, wenn die Generierung abgeschlossen ist.

Export auslösen

{
  "format": "JSON"
}

Antwort:

{
  "ok": true,
  "data": {
    "id": "export_01HX...",
    "format": "JSON",
    "status": "PENDING",
    "totalUsers": 0,
    "expiresAt": "2025-06-17T14:00:00Z",
    "createdAt": "2025-06-10T14:00:00Z"
  }
}

Auf Abschluss warten

Datei herunterladen

curl https://auth.yourdomain.com/api/users/export/export_01HX.../download \
  -H "Authorization: Bearer $TOKEN" \
  -H "x-tenant: your-tenant" \
  -o benutzer-export.json

Exportierte Felder

Der Export enthält:

Console-Anleitung

Die Console-Import/Export-Schnittstelle ist unter Einstellungen → Import/Export verfügbar.

Importieren:

1. Eine .csv- oder .json-Datei in die Upload-Zone ziehen und ablegen oder klicken, um die Dateiauswahl zu öffnen.
2. Die Console zeigt eine Vorschau der ersten 10 Zeilen zur Validierung vor dem Einreichen an.
3. Nach dem Einreichen verfolgt ein Fortschrittsbalken die Verarbeitung. Der Balken wird alle paar Sekunden durch Abfragen aktualisiert.
4. Wenn der Job abgeschlossen ist, zeigt eine Ergebniszusammenfassung die Erfolgsanzahl, Fehleranzahl und einen Link zum Fehlerdetails-Dialog.

Exportieren:

1. Exportformat auswählen (CSV oder JSON).
2. Auf “Benutzer exportieren” klicken. Die Console zeigt den Job-Status.
3. Wenn der Export abgeschlossen ist, erscheint eine “Herunterladen”-Schaltfläche. Darauf klicken, um die Datei zu speichern.
4. Frühere Exporte werden mit ihrem Status, Erstellungsdatum und Ablaufdatum aufgeführt.

Erforderliche Berechtigungen

Verwandte Seiten

• Benutzer verwalten — Individuelles Benutzer-CRUD über API und Console
• SCIM 2.0-Provisionierung — Automatisierte laufende Synchronisation von einem externen IdP
• Console: Import/Export — Vollständige Console-Anleitung mit Screenshots