So importieren Sie viele Personen auf einmal

Der Import liest Personen aus einer CSV-Datei – etwa aus der Personalabteilung oder dem Verzeichnisdienst –, prüft jede Zeile, bevor etwas gespeichert wird, und legt die neuen Personen danach in einem Zug mit ihren Regeln an.

Was der Import nicht tut: Er ändert keine vorhandene Person, stellt keine Schlüssel aus und richtet keinen zweiten Faktor ein. Diese Schritte haben eigene Abläufe (siehe Hinweise).

Lösungsübersicht

stateDiagram-v2
    direction LR
    [*] --> Neu: Zeile gültig, Name unbekannt
    [*] --> Vorhanden: Name schon im Speicher
    [*] --> Fehler: Zeile ungültig
    Neu --> Angelegt: Übernehmen, Person und Regeln gespeichert
    Neu --> Teilweise: Person gespeichert, eine Regel abgewiesen
    Neu --> Fehlgeschlagen: Person abgewiesen
    Teilweise --> Angelegt: Übernehmen erneut
    Fehlgeschlagen --> Angelegt: Übernehmen erneut
    Vorhanden --> [*]: bleibt unverändert
    Fehler --> [*]: Datei berichtigen, neu einlesen

Abbildung: Stand einer Zeile. Links der Stand nach dem Einlesen, rechts nach „Übernehmen“. Nur „Neu“, „Teilweise“ und „Fehlgeschlagen“ bearbeitet „Übernehmen“; „Vorhanden“ und „Fehler“ schreiben nie etwas.

Stand	Bedeutung	Was „Übernehmen“ tut
Neu	gültige Zeile, keine Person dieses Namens vorhanden	legt die Person und ihre Regeln an
Vorhanden	eine Person dieses Namens ist bereits vorhanden	nichts; die Person bleibt unverändert
Fehler	die Zeile ist ungültig; der Hinweis nennt den Grund	nichts
Angelegt	Person und alle Regeln sind gespeichert	nichts mehr
Teilweise	die Person ist gespeichert, mindestens eine Regel hat der Dienst abgewiesen	ordnet die fehlenden Regeln erneut zu
Fehlgeschlagen	der Dienst hat die Person abgewiesen; der Hinweis zeigt seine Meldung	versucht die Person erneut

Die Datei

Die erste Zeile nennt die Spalten. Ihre Reihenfolge ist frei; Groß- und Kleinschreibung, Leerzeichen und Bindestriche im Spaltennamen zählen nicht.

Spalte	Pflicht	Inhalt	Prüfung vor dem Speichern
`Name`	ja	Vor- und Nachname	nicht leer, nicht zweimal in der Datei
`Windows-Konto`	nein	`DOMÄNE\Name` oder eine SID	keine; der Dienst löst das Konto beim Anlegen auf und weist ein unbekanntes ab
`SQL-Anmeldung`	nein	Name der Anmeldung in SQL Server	keine
`E-Mail`	nein	eine Adresse ohne Anzeigenamen, etwa `anna@example.org`; wird das Feld Mail-Adresse der Person, für Einladungsmails. Die Spalte darf auch `Mail-Adresse` heißen	grobe Form: genau ein `@`, ein Punkt dahinter, keine Leerzeichen, kein `<`
`Regeln`	nein	Namen von Regeln, getrennt durch Komma oder senkrechten Strich (`\|`)	jede Regel muss es geben; die Schreibweise wird an die des Speichers angeglichen

Weitere Spalten, etwa Abteilung, nennt die Zusammenfassung und übergeht sie. Nehmen Sie nur die Spalten in die Datei, die der Zugang braucht (siehe Datenschutz).

Name;Windows-Konto;E-Mail;Regeln
Anna Beispiel;FIRMA\abeispiel;anna@example.org;fachdaten-lesen
"Berg, Jörg";FIRMA\jberg;;fachdaten-lesen,fachdaten-pflege

Format. Eine CSV-Datei in UTF-8 mit Semikolon als Trennzeichen. Aus Excel speichern Sie sie mit Datei > Speichern unter und dem Dateityp „CSV UTF-8 (durch Trennzeichen getrennt)“. Die Datei wird nach RFC 4180 („Common Format and MIME Type for Comma-Separated Values (CSV) Files“, https://www.rfc-editor.org/rfc/rfc4180) gelesen: Ein Feld in Anführungszeichen darf Trennzeichen und Zeilenumbrüche enthalten, "" steht darin für ein Anführungszeichen. Abweichend von RFC 4180, das das Komma als Trennzeichen festlegt, trennt hier das Semikolon. Leerzeichen am Rand eines Feldes werden entfernt.

Umsetzung

Öffnen Sie Personen und Schlüssel und wählen Sie unter Weitere den Befehl Personen importieren … aus. Wählen Sie die Datei.
Rechts neben der Liste der Personen steht jede Zeile der Datei, nach Stand gruppiert, mit ihrer Zeilennummer in der Datei. Die Zeile darüber fasst zusammen, wie viele Zeilen neu, vorhanden und fehlerhaft sind, wie viele Anfragen Übernehmen an den Dienst stellt und wie lange das etwa dauert. Bis hierhin ist nichts gespeichert.

Im Bild: (1) Zusammenfassung, (2) Zeilen nach Stand, (3) Übernehmen, Andere Datei, Schließen.
Zeilen mit Fehler berichtigen Sie in der Datei und lesen sie mit Andere Datei … neu ein. Sie können auch zuerst übernehmen und die berichtigte Datei danach einlesen: Bereits angelegte Personen stehen dann auf Vorhanden.
Wählen Sie Übernehmen (n) aus; n ist die Zahl der Zeilen, die noch zu tun sind. Die Zeile über dem Raster zeigt die Person, die gerade an der Reihe ist. Anhalten hält nach der laufenden Anfrage an; Übernehmen setzt später dort fort.
Schließen gibt die Liste wieder frei und löscht die eingelesenen Zeilen.

Ergebnis: Die Zeilen stehen auf Angelegt; die Personen erscheinen in der Liste, jede mit ihren Regeln. Jede Anlage steht wie jede andere Änderung im Änderungsprotokoll (Bereich Protokoll).

Hinweise

Dauer und Anfragegrenze

Der Dienst kennt keine Sammelanfrage: Jede Person ist eine Anfrage, jede ihrer Regeln eine weitere. Er begrenzt die Anfragen je Aufrufer (Vorgabe 300 in 60 Sekunden, siehe HTTP: Verwaltung (Referenz), Abschnitt „Viele Vorgänge auf einmal“ (Dokumentation des Datendienstes)). Der Import hält deshalb mindestens 250 ms zwischen zwei Anfragen, also höchstens 240 je Minute; der Rest bleibt für die Anfragen, die die Seite selbst stellt. Daraus folgt die Schätzung der Zusammenfassung: 850 Personen mit je einer Regel sind 1 700 Anfragen, rund 7 Minuten (Richtwert aus der Anfragegrenze); über eine langsame Verbindung dauert es länger.

Meldet der Dienst trotzdem „zu viele Anfragen“ (HTTP 429), wartet der Import 60 Sekunden und wiederholt dieselbe Anfrage, höchstens dreimal; danach steht die Zeile auf Fehlgeschlagen und der Import fährt mit der nächsten fort.

Teilfehler und Wiederholen

Was vor einem Fehler gespeichert wurde, bleibt. Der Import merkt sich daher je Zeile, ob die Person schon angelegt ist und welche Regeln noch fehlen. Ein erneutes Übernehmen legt keine Person doppelt an, sondern setzt bei dem fort, was fehlt. Bricht die Verbindung während einer Anfrage ab, wiederholt die Anwendung sie, ohne dass der Dienst etwas doppelt speichert.

Abgleich über den Namen

Ob eine Person „vorhanden“ ist, entscheidet allein ihr Name, ohne Rücksicht auf Groß- und Kleinschreibung – der Name ist im Speicher eindeutig. Daraus folgen zwei Grenzen:

Zwei verschiedene Menschen gleichen Namens: Der zweite wird als Vorhanden übergangen. Geben Sie ihm einen unterscheidenden Namen (etwa mit Abteilung).
Eine vorhandene Person mit anderem Windows-Konto oder anderer E-Mail-Adresse in der Datei: Der Import ändert sie nicht und meldet den Unterschied nicht. Prüfen Sie solche Personen in ihrer Maske.

Keine Schlüssel, kein zweiter Faktor

Wer sich mit Windows-Konto oder SQL-Anmeldung anmeldet, braucht keinen Schlüssel. Schlüssel geben Sie danach gezielt aus, für viele am einfachsten per Einladungsmail. Den zweiten Faktor richten Sie für importierte Personen am besten ebenfalls per Einladungsmail ein, für viele auf einmal über die Karte Auswahl (So bearbeiten Sie viele Personen auf einmal). Selbst einrichten kann eine Person ihn bei der Anmeldung nur in einer Frist nach dem Ausstellen ihres Schlüssels (Einstellung totp_enrol_hours, Vorgabe 24 Stunden); wer sich nur mit Windows-Konto oder SQL-Anmeldung anmeldet, hat keinen Schlüssel und damit keine solche Frist (siehe So richten Sie den zweiten Faktor ein oder setzen ihn zurück).

Rechte für ganze Gruppen

Regeln, Datenbank-Identitäten und Anmelderegeln lassen sich einer Windows-Gruppe als Ganzem geben, siehe So ordnen Sie Windows-Konten und -Gruppen zu. Eine Person braucht nur, wer einen Schlüssel, einen zweiten Faktor oder eine Vorgabe-Identität bekommt. Verlangt eine Anmelderegel den zweiten Faktor für eine Gruppe, weist der Dienst jedes Mitglied ohne eigenen Personeneintrag ab: Für solche Gruppen ist der Import der Weg, alle Mitglieder als Personen anzulegen.

Der Dienst liefert keine Mitglieder einer Windows-Gruppe. Eine Liste dafür erzeugt der Verzeichnisdienst, etwa mit Get-ADGroupMember am Arbeitsplatz; als CSV mit den Spalten Name und Windows-Konto gespeichert, lässt sie sich hier einlesen. Spätere Ein- und Austritte in der Gruppe übernimmt weder der Dienst noch die Anwendung von selbst.

Datenschutz

Die Liste enthält personenbezogene Daten im Sinne von Art. 4 Nr. 1 DSGVO (Namen, Konten, E-Mail- Adressen). Für die Verarbeitung ist der Betreiber der Installation verantwortlich; die Anwendung unterstützt die Grundsätze der Datenminimierung und Speicherbegrenzung (Art. 5 Abs. 1 lit. c und e DSGVO) so:

Maßnahme	Umsetzung
Nur nötige Felder	gespeichert werden nur die Spalten der Tabelle oben; andere Spalten der Datei nennt die Zusammenfassung, übernommen werden sie nicht
Zwischenstand nicht aufbewahren	die eingelesenen Zeilen liegen nur in der lokalen Kopie der Anwendung im Benutzerprofil und werden beim Schließen des Imports, beim Abmelden und beim nächsten Anmelden gelöscht
Keine Kopie der Datei	die Anwendung kopiert die Datei nicht; sie bleibt, wo sie war

Die Quelldatei selbst bleibt in Ihrer Verantwortung: Löschen Sie sie nach dem Import, wenn sie nicht anderweitig gebraucht wird.

Bleibende Spur: Jede angelegte Person steht mit ihren Werten im Änderungsprotokoll des Dienstes, und das bleibt unbegrenzt – auch wenn die Person später gelöscht wird (siehe Sicherheit und Datenschutz). Importieren Sie deshalb nur Personen, die tatsächlich Zugang bekommen sollen, und nur die nötigen Spalten.