3. Konfiguration#

Der Connector liest seine Konfiguration aus zwei Quellen. Die Einstellungsdatei /etc/asm-connections.json enthält die Konten in Apple School Manager, die Schulen, die der Connector in jedes dieser Konten synchronisiert, und alle Einstellungen, die steuern, welche Benutzer der Connector exportiert und wie er ihre Attribute abbildet. Die App-Einstellungen im App Center enthalten den Zeitplan der Synchronisation und einige Schalter für den täglichen Betrieb.

Vorsicht

Apple School Manager verwendet die E-Mail-Adresse eines Benutzers als Apple Account. Stellen Sie sicher, dass jeder synchronisierte Benutzer eine primäre E-Mail-Adresse hat. Für Benutzer ohne primäre E-Mail-Adresse kann Apple School Manager kein Konto anlegen. Siehe E-Mail-Adressen.

3.1. Einstellungsdatei#

Die Einstellungsdatei /etc/asm-connections.json hat drei Abschnitte:

accounts: Die Konten in Apple School Manager, jedes mit seinen Zugangsdaten und den Einstellungen für die Schüler und Lehrer, die das Konto erhält. Siehe Konten in Apple School Manager.
schools: Die zu synchronisierenden Schulen, jede mit dem Konto, das sie erhält, und den Einstellungen für ihre Klassen. Siehe Schulen.
defaults: Einstellungen, die für jedes Konto und jede Schule gelten, sofern ein Konto- oder Schuleintrag sie nicht selbst setzt. Siehe Voreinstellungen.

Quellcode 3.1 Zwei Konten in Apple School Manager in /etc/asm-connections.json#

{
    "accounts": {
        "north": {
            "username": "sftp-user-north",
            "password_file": "/etc/asm-north.secret"
        },
        "south": {
            "username": "sftp-user-south",
            "password_file": "/etc/asm-south.secret",
            "student": {"anonymize": false}
        }
    },
    "defaults": {
        "student": {"password_policy": 6}
    },
    "schools": {
        "gym123": {"account": "north"},
        "gs456": {
            "account": "south",
            "course_name_pattern": "{name}",
            "student": {"ldap_filter": "(uid=a*)"}
        }
    }
}

Ein Schüler oder Lehrer, der zu mehreren Schulen desselben Kontos gehört, erscheint im Upload in dieses Konto nur einmal. Die Einstellungen für Schüler und Lehrer gelten daher pro Konto, die Einstellungen für Klassen und die LDAP-Filter pro Schule.

Für jede Einstellung verwendet der Connector den Wert aus dem Konto- oder Schuleintrag, danach den Wert aus defaults und danach die eingebaute Voreinstellung.

Die Installation legt die Datei mit Leserechten nur für den Benutzer root an. Bearbeiten Sie sie mit einem Texteditor. Der Connector liest die Datei zu Beginn jedes Laufs, daher wirkt eine Änderung ab der nächsten Synchronisation. Er prüft die vollständige Datei, bevor er etwas hochlädt. Die folgenden Probleme brechen den Lauf mit einer Fehlermeldung ab, die die Datei und den Eintrag nennt:

Eine fehlende Datei oder eine Datei ohne Konto oder ohne Schule.
Ein fehlender oder unbekannter Schlüssel oder ein Wert vom falschen Typ.
Eine Schule, die auf ein Konto verweist, das die Datei nicht definiert.
Eine fehlende oder leere Passwortdatei.
Ein Benutzername, der bei mehr als einem Konto vorkommt.
Eine Schule, die nicht existiert, wenn die Datei den Eintrag * enthält. Eine falsch geschriebene Schule würde ihre Benutzer sonst an das Konto dieses Eintrags schicken.
Kein Konto, das eine existierende Schule erhält.

Die folgenden Probleme schreiben nur eine Warnung in die Logdatei. Der Connector lädt in die übrigen Konten hoch:

Ein Konto, auf das keine Schule verweist. Das Konto erhält keinen Upload.
Eine Schule, die nicht existiert, wenn die Datei keinen Eintrag * enthält. Ein Konto ohne existierende Schule erhält keinen Upload.

Schlägt der Upload in ein Konto fehl, lädt der Connector trotzdem in die übrigen Konten hoch und endet am Schluss mit einem Exit-Status ungleich null.

3.1.1. Konten in Apple School Manager#

Der Abschnitt accounts ordnet jedem Konto einen Namen Ihrer Wahl zu. Der Name darf nur Buchstaben, Ziffern, ., _ und - enthalten. Meist gibt es ein einziges Konto. Wenn die Schulen auf Ihrem UCS@school-System zu verschiedenen Einrichtungen mit jeweils eigenem Konto in Apple School Manager gehören, legen Sie einen Eintrag pro Konto an. Der Connector lädt dann in jedes Konto ein eigenes Archiv hoch, jeweils beschränkt auf die Schulen, die auf dieses Konto verweisen.

So fügen Sie ein Konto hinzu:

Speichern Sie das SFTP-Passwort des Kontos in einer eigenen Datei, die nur root lesen kann. SFTP-Zugangsdaten ermitteln beschreibt, wo Sie das Passwort finden. Jedes Konto hat eigene SFTP-Zugangsdaten und braucht deshalb eine eigene Passwortdatei. Die Beispiele benennen die Datei nach dem Konto, etwa /etc/asm-north.secret. Das Konto aus Zugangsdaten eingeben kann /etc/asm.secret behalten.
Quellcode 3.2 Passwort eines Kontos speichern#
```
$ install -m 600 /dev/null /etc/asm-north.secret
$ editor /etc/asm-north.secret
```
Fügen Sie das Konto dem Abschnitt accounts der Einstellungsdatei hinzu.
Ordnen Sie dem Konto mindestens eine Schule zu, wie in Schulen beschrieben.

Ein Kontoeintrag nimmt die folgenden Schlüssel auf. Alle Schlüssel außer username und password_file sind optional und können auch in defaults stehen.

Tab. 3.1 Schlüssel eines Kontoeintrags#
Schlüssel	Voreinstellung	Beschreibung
`username`	Erforderlich	Der SFTP-Benutzername des Kontos.
`password_file`	Erforderlich	Pfad zur Datei mit dem SFTP-Passwort des Kontos.
`email_prepend_domain`	Leer	Siehe E-Mail-Adressen.
`student.anonymize`, `staff.anonymize`	`true`	Siehe Anonymisierung.
`student.anonymize_values`, `staff.anonymize_values`	Siehe Anonymisierung	Siehe Anonymisierung.
`student.person_id_attribute`, `staff.person_id_attribute`	`entryUUID`	Siehe Identifikation von Benutzern.
`student.password_policy`	`4`	Siehe Passwortrichtlinie für Schüler.
`student.grade_level_attribute`	`null`	Siehe Jahrgangsstufe von Schülern.

3.1.2. Schulen#

Der Abschnitt schools führt die zu synchronisierenden Schulen mit ihrem Kürzel auf und ordnet jede von ihnen einem Konto zu. Der Connector synchronisiert nur Schulen, die der Abschnitt aufführt.

Um die Kürzel nachzuschlagen, öffnen Sie Schul-Administration ‣ Schulen in der UMC. Das Kürzel ist der Name des Schulobjekts, zum Beispiel gym123.

Der Eintrag * steht für jede Schule, die der Abschnitt nicht namentlich aufführt. Bei einem einzigen Konto synchronisiert er alle Schulen in dieses Konto.

Wenn der Abschnitt eine Schule aufführt, die es nicht gibt, bricht der Connector ab, bevor er etwas hochlädt. Andernfalls ginge eine falsch geschriebene Schule an das Konto des Eintrags * statt an das gemeinte Konto.

Quellcode 3.3 Jede Schule in ein Konto, eine Schule mit eigenem LDAP-Filter#

"schools": {
    "*": {"account": "north"},
    "gym123": {
        "account": "north",
        "staff": {"ldap_filter": "(uid=t*)"}
    }
}

Ein Schüler oder Lehrer, der zu mehreren Schulen gehört, erscheint im Upload in ein Konto nur mit den Schulen, die zu diesem Konto gehören. Gehört keine seiner Schulen zu dem Konto, überspringt der Connector ihn für dieses Konto.

Ein Schuleintrag nimmt die folgenden Schlüssel auf. Alle Schlüssel außer account sind optional und können auch in defaults stehen.

Tab. 3.2 Schlüssel eines Schuleintrags#
Schlüssel	Voreinstellung	Beschreibung
`account`	Erforderlich	Name des Kontos im Abschnitt `accounts`, das die Schule erhält.
`course_name_pattern`	`{ou}-{name}`	Siehe Namen von Kursen und Klassen.
`class_number_empty`	`true`	Siehe Namen von Kursen und Klassen.
`student.ldap_filter`, `staff.ldap_filter`	Leer	Siehe Benutzer mit einem LDAP-Filter auswählen.

3.1.3. Voreinstellungen#

Der Abschnitt defaults nimmt jeden optionalen Schlüssel eines Konto- und eines Schuleintrags auf. Ein Wert in defaults gilt für alle Konten und Schulen, die den Schlüssel nicht selbst setzen.

Quellcode 3.4 Niemanden anonymisieren, außer den Schülern des Kontos north#

"defaults": {
    "student": {"anonymize": false},
    "staff": {"anonymize": false}
},
"accounts": {
    "north": {
        "username": "sftp-user-north",
        "password_file": "/etc/asm-north.secret",
        "student": {"anonymize": true}
    }
}

3.1.4. Update von einer früheren Version#

Bis Version 5.1.1 enthielten App-Einstellungen und UCR-Variablen die Konfiguration. Das Update auf Version 6.0.0 überträgt ihre Werte in die Einstellungsdatei und entfernt die UCR-Variablen. Sie müssen nichts tun. Das Passwort bleibt in /etc/asm.secret, und die Einstellungsdatei verweist darauf. Das Konto erhält den Namen default.

Tab. 3.3 Bisherige App-Einstellungen und UCR-Variablen#
Bisherige Einstellung	Schlüssel in der Einstellungsdatei
`asm/username`	`accounts.default.username`
`asm/password`	`accounts.default.password_file`
`asm/school_whitelist`	Ein Eintrag pro Schule in `schools` oder der Eintrag `*`, wenn die Liste leer war
`asm/attributes/user/email/prepend_domain`	`defaults.email_prepend_domain`
`asm/attributes/ROLE/anonymize`	`defaults.ROLE.anonymize`
`asm/attributes/ROLE/anonymize/ATTRIBUTE`	`defaults.ROLE.anonymize_values.ATTRIBUTE`
`asm/attributes/ROLE/person_id/mapping`	`defaults.ROLE.person_id_attribute`, ohne das führende `%`
`asm/attributes/student/password_policy`	`defaults.student.password_policy`, `null` für das bisherige `-`
`asm/attributes/student/grade_level`	`defaults.student.grade_level_attribute`
`asm/attributes/course-name-pattern`	`defaults.course_name_pattern`
`asm/attributes/classes/class_number_empty`	`defaults.class_number_empty`
`asm/ldap_filter/students`, `asm/ldap_filter/staff`	`defaults.student.ldap_filter`, `defaults.staff.ldap_filter`
`asm/ldap_filter/students/SCHOOL`, `asm/ldap_filter/staff/SCHOOL`	`schools.SCHOOL.student.ldap_filter`, `schools.SCHOOL.staff.ldap_filter`

Ersetzen Sie ROLE durch staff oder student, ATTRIBUTE durch ein Attribut aus Anonymisierung und SCHOOL durch das Schulkürzel.

Das Update verwirft einen LDAP-Filter für eine Schule, die nicht auf der bisherigen Schulliste stand, weil der Connector diese Schule nicht synchronisiert hat. Außerdem lässt es Schulen weg, die nicht mehr existieren, sowohl aus der bisherigen Schulliste als auch aus den LDAP-Filtern, und gibt für jede einen Hinweis aus.

Ohne asm/username hat das Update kein Konto, dem es Schulen zuordnen kann. Es behält asm/school_whitelist und die UCR-Variablen asm/ldap_filter/students/SCHOOL und asm/ldap_filter/staff/SCHOOL und gibt für jede einen Hinweis aus. Übertragen Sie ihre Werte in die Einstellungsdatei, wenn Sie das Konto anlegen.

Wenn /etc/asm-connections.json bereits existiert, lässt das Update die Datei und die UCR-Variablen unverändert.

3.2. App-Einstellungen#

Um die App-Einstellungen zu öffnen, wählen Sie die App im App Center aus und klicken Sie auf App-Einstellungen. Die App-Einstellungen gelten für alle Konten gleichermaßen.

Tab. 3.4 App-Einstellungen des Apple School Manager Connector#
Einstellung	Voreinstellung	Beschreibung
`asm/sync_daily`	`False`	Führt die Synchronisation einmal am Tag aus. Siehe Synchronisation zeitlich planen.
`asm/sync_daily/hour`	Nicht gesetzt	Die Stunde des Tages, zu der die tägliche Synchronisation läuft. Gültige Werte sind `0` bis `23`.
`asm/run_on_appsetting_save`	`False`	Führt die Synchronisation sofort aus, nachdem Sie die App-Einstellungen gespeichert haben.
`asm/store_zip`	`False`	Behält das hochgeladene ZIP-Archiv in `/var/lib/asm/`, statt es nach dem Upload zu löschen.
`asm/last_upload`	Nicht gesetzt	Schreibgeschütztes Statusfeld. Zeigt an, wann der Connector zuletzt ein Archiv in eines der Konten hochgeladen hat.
`asm/last_upload/ACCOUNT`	Nicht gesetzt	Zeigt an, wann der Connector zuletzt ein Archiv in das Konto `ACCOUNT` hochgeladen hat. Nicht Teil der App-Einstellungen.

3.3. Synchronisation zeitlich planen#

Der Connector läuft nicht von selbst. Entweder starten Sie ihn manuell, wie in Synchronisation ausführen beschrieben, oder Sie lassen ihn von einem Cron-Job einmal am Tag ausführen.

Um die tägliche Ausführung zu aktivieren:

Öffnen Sie die App-Einstellungen.
Wählen Sie asm/sync_daily aus.
Wählen Sie die Stunde in asm/sync_daily/hour aus.
Klicken Sie auf Änderungen anwenden.

Der Connector schreibt den Cron-Job nach /etc/cron.d/asm-upload. Der Job läuft in Minute 0 der gewählten Stunde. Wenn Sie die tägliche Ausführung ohne gültige Stunde aktivieren, schreibt der Connector statt eines Jobs einen Kommentar in die Cron-Datei, und es findet keine Synchronisation statt.

3.4. Einstellungen im Detail#

Die folgenden Abschnitte beschreiben die optionalen Schlüssel der Einstellungsdatei. Schlüssel, die mit student oder staff beginnen, gehören in ein Objekt dieses Namens, wie in "student": {"anonymize": false}.

3.4.1. E-Mail-Adressen#

Apple School Manager verwendet die E-Mail-Adresse eines Benutzers als Apple Account. Der Connector exportiert die primäre E-Mail-Adresse jedes Benutzers in UCS@school. Benutzer ohne primäre E-Mail-Adresse werden ohne E-Mail-Adresse exportiert, und Apple School Manager kann für sie keinen Apple Account anlegen.

email_prepend_domain: Pro Konto. Fügt den Wert als Subdomain vor der Domain jeder E-Mail-Adresse ein. Mit dem Wert apple exportiert der Connector die Adresse jane@example.com als jane@apple.example.com. Voreinstellung: leer.

3.4.2. Anonymisierung#

Wenn Sie die Namen und E-Mail-Adressen Ihrer Benutzer nicht übertragen möchten, können Sie diese anonymisieren. Die Anonymisierung ersetzt die Werte der Attribute first_name, middle_name, last_name, email_address und sis_username durch Werte, die Sie konfigurieren.

Vorsicht

Ein anonymisierter Benutzer hat keine E-Mail-Adresse, es sei denn, Sie konfigurieren dafür einen Ersatzwert. Ohne E-Mail-Adresse kann Apple School Manager für den Benutzer keinen Apple Account anlegen.

Die Anonymisierung und die Einrichtung aus Keycloak als Identity Provider für ASM schließen sich gegenseitig aus. Wenn Sie Keycloak als Identity Provider für Apple School Manager verwenden, deaktivieren Sie die Anonymisierung.

student.anonymize, staff.anonymize: Pro Konto. Aktiviert die Anonymisierung für Schüler und Lehrer. Voreinstellung: true.
student.anonymize_values, staff.anonymize_values: Pro Konto. Ersatzwerte für die anonymisierten Attribute. Ein Wert, der mit % beginnt, bezeichnet ein LDAP-Attribut, und der Connector exportiert den Wert dieses Attributs aus dem LDAP-Objekt des Benutzers. Ein Wert ohne führendes % wird wörtlich exportiert. null lässt die Spalte leer. Sie müssen nur die Attribute aufführen, deren Voreinstellung Sie ändern möchten.

Tab. 3.5 Ersatzwerte für anonymisierte Attribute#
Schlüssel in `anonymize_values`	Voreinstellung	Erforderlich
`first_name`	`%uid`	Ja
`middle_name`	`null`	Nein
`last_name`	`-`	Ja
`email_address`	`null`	Nein
`sis_username`	`%uid`	Nein

Quellcode 3.5 Schüler mit einem festen Nachnamen anonymisieren#

"student": {
    "anonymize": true,
    "anonymize_values": {"last_name": "Student"}
}

3.4.3. Identifikation von Benutzern#

Apple School Manager identifiziert einen Benutzer anhand der Spalte person_id. Der Connector füllt sie mit einem LDAP-Attribut des Benutzers, das sich nicht ändert, wenn Sie den Benutzer umbenennen.

student.person_id_attribute, staff.person_id_attribute: Pro Konto. LDAP-Attribut, das einen Schüler oder einen Lehrer identifiziert. Voreinstellung: entryUUID.

Vorsicht

Ändern Sie diese Schlüssel nicht in einer laufenden Installation. Apple School Manager behandelt einen Benutzer mit einer neuen person_id als anderen Benutzer und verliert die Zuordnung zum bestehenden Konto.

3.4.4. Passwortrichtlinie für Schüler#

Apple School Manager erstellt das Passwort für einen neuen Schüler selbst. Die Passwortrichtlinie legt fest, wie lang dieses Passwort ist.

student.password_policy: Pro Konto. Länge des Passworts, das Apple für einen neuen Schüler erstellt. Gültige Werte sind 4, 6, 8 und null. null bedeutet, dass Apple School Manager die Voreinstellung der Schule verwendet. Voreinstellung: 4.

Apple School Manager unterstützt keine Passwortrichtlinie für Lehrer.

3.4.5. Jahrgangsstufe von Schülern#

student.grade_level_attribute: Pro Konto. LDAP-Attribut, das die Jahrgangsstufe eines Schülers enthält. Der Connector exportiert seinen Wert in der Spalte grade_level. Voreinstellung: null, wodurch die Spalte leer bleibt.

3.4.6. Namen von Kursen und Klassen#

UCS@school stellt dem Namen einer Schulklasse das Schulkürzel voran, zum Beispiel gym123-1a. Der Connector leitet den Kursnamen aus diesem Namen ab.

course_name_pattern: Pro Schule. Muster für den Kursnamen. Der Connector ersetzt {ou} durch das Schulkürzel und {name} durch den Klassennamen ohne Schulpräfix. Voreinstellung: {ou}-{name}.
class_number_empty: Pro Schule. Lässt die Spalte class_number leer. Apple School Manager bildet den Namen einer Klasse aus dem Kursnamen und der Klassennummer, daher würde eine gleichlautende Klassennummer den Kursnamen nur wiederholen. Voreinstellung: true.

3.4.7. Benutzer mit einem LDAP-Filter auswählen#

Wenn die Schulliste aus Schulen nicht fein genug ist, können Sie die Benutzer mit einem LDAP-Filter auswählen. Der Connector wendet den Filter zusätzlich zur Schulliste an.

student.ldap_filter, staff.ldap_filter: Pro Schule. LDAP-Filter für die Schüler oder die Lehrer der Schule. Ein Filter in defaults gilt für jede Schule, die keinen eigenen setzt. Voreinstellung: leer, wodurch jeder Benutzer ausgewählt wird.

Quellcode 3.6 Nur die Schüler von gym123 mit primärer E-Mail-Adresse synchronisieren#

"gym123": {
    "account": "north",
    "student": {"ldap_filter": "(mailPrimaryAddress=*)"}
}

Der Connector kombiniert den Filter mit seiner eigenen Auswahl der Schüler oder Lehrer der Schule, daher muss der Filter nur die Attribute der gewünschten Benutzer beschreiben. Um zu prüfen, welche Benutzer ein Filter auswählt, bevor Sie ihn setzen, kombinieren Sie ihn mit der Rolle der Benutzer und führen Sie ihn mit univention-ldapsearch aus:

Quellcode 3.7 Die Schüler von gym123 auflisten, auf die der Filter zutrifft#

$ univention-ldapsearch -LLL \
  '(&(ucsschoolRole=student:school:gym123)(mailPrimaryAddress=*))' uid

Vorsicht

Ein ungültiger LDAP-Filter bricht den Upload in das Konto dieser Schule ab. Der Connector lädt in diesem Fall nichts in dieses Konto hoch, daher bleiben dessen Daten in Apple School Manager so, wie sie nach dem letzten erfolgreichen Lauf waren. Die anderen Konten erhalten ihren Upload trotzdem.

Apple School Manager Connector 6.0.0 Dokumentation

Konfiguration

Inhalt

3. Konfiguration#

3.1. Einstellungsdatei#

3.1.1. Konten in Apple School Manager#

3.1.2. Schulen#

3.1.3. Voreinstellungen#

3.1.4. Update von einer früheren Version#

3.2. App-Einstellungen#

3.3. Synchronisation zeitlich planen#

3.4. Einstellungen im Detail#

3.4.1. E-Mail-Adressen#

3.4.2. Anonymisierung#

3.4.3. Identifikation von Benutzern#

3.4.4. Passwortrichtlinie für Schüler#

3.4.5. Jahrgangsstufe von Schülern#

3.4.6. Namen von Kursen und Klassen#

3.4.7. Benutzer mit einem LDAP-Filter auswählen#