Benutzerjobs (Active Directory)

SwissMentor erkennt Personen, für die ein Benutzerkonto nötig ist, und legt dafür Benutzerjobs an. Die IT holt die offenen Jobs per PowerShell ab und legt die Konten im Verzeichnis an. SwissMentor vergibt den Benutzernamen. Nach der Aktion im Verzeichnis markiert das Skript den Job als erledigt.

SwissMentor schreibt nicht selbst ins Active Directory und nicht nach Microsoft Entra ID. Das Sekretariat erzeugt nur Jobs. Konten entstehen erst, wenn die IT ein Skript ausführt.

Mitgeliefert ist ein Skript für das lokale Active Directory (Import-ADUserFromSMUserJobs). Dieselbe Jobschnittstelle kann ein eigenes Skript gegen Microsoft Entra ID (Microsoft Graph) fahren. Die Anmeldung an SwissMentor über Entra ist ein anderes Thema, siehe Microsoft Entra ID Authentifizierung.

Voraussetzungen

• Windows-Rechner oder Server mit dem PowerShell-Modul Active Directory (RSAT)
• Rechte im Active Directory für die Ziel-OU und die gewünschten Gruppen
• Ein Administrator-Konto in SwissMentor für die API-Anmeldung
• Einstellung Benutzererstellung und -deaktivierung in einem externen User Job ausführen muss aktiv sein. Sonst schliesst SwissMentor die Jobs sofort, ohne dass das Skript sie sieht.

Einstellungen in SwissMentor

1. Als Administrator anmelden.
2. Administration > Systemkonfiguration öffnen.
3. Authentifizierung > Providers > Microsoft Entra ID wählen.

Die relevanten Schalter stehen derzeit in dieser Gruppe, auch wenn Sie Entra ID nicht als Anmeldeverfahren nutzen.

Einstellung	Bedeutung
Benutzererstellung und -deaktivierung in einem externen User Job ausführen	Muss aktiv sein. Offene Jobs bleiben stehen, bis das PowerShell-Skript sie abarbeitet.
Automatische Benutzergenerierung aktiviert	Legt in SwissMentor gleichzeitig den Login mit dem gleichen Benutzernamen an. Für den Abgleich SwissMentor und AD in der Regel einschalten.
Automatische Benutzergenerierung: Benutzertyp	SMUSER für klassisches AD bzw. LDAP. AZURE-AD, wenn der Login in SwissMentor als Entra-Benutzer geführt wird.
Automatische Benutzergenerierung: Prefix für den automatisch generierten Benutzernamen	Wird nur bei Typ AZURE-AD an den Namen gehängt (z.B. @schule.ch).

Wann entstehen Jobs

Ein Job entsteht nicht von allein für jede Person ohne Benutzername. SwissMentor legt ihn an, wenn ein definierter Vorgang das verlangt:

• Kursanmelde-Einladung (Serienmail-Typ Kursanmeldung): legt einen Job vom Typ Erstellen an, sofern die Person noch kein Konto hat bzw. nach einer Sperre wieder aktiviert wird.
• Prozessschritte an der Person: temporäre Sperre, langfristige Sperre, Entsperren.
• Sicherheit & Benutzer > Benutzerverwaltung > Filter Benutzer von ehemaligen Teilnehmern: Aktion Benutzer (per User-Job) deaktivieren.
• GraphQL-API (nur Administrator): Mutation createSMUserJob mit Typ CreateInAd, DeactivateInAd, UnlockPerson, TemporaryLockPerson oder LongTermLockPerson. Damit können Sie gezielt Personen ohne Login nachziehen.

Die Aktion Benutzer Massenerstellung unter Sicherheit & Benutzer > Benutzerverwaltung legt interne SwissMentor-Logins an. Sie erzeugt keine AD-Benutzerjobs.

Ein bereits erledigter Job derselben Art wird nicht einfach überschrieben. Wiederholte Sperren, Entsperren und eine erneute Erstellung nach vorheriger Sperre erzeugen einen neuen offenen Job. Eine zweite Kurseinladung für eine bereits aktive Person erzeugt keinen zweiten Erstell-Job.

Job-Typen

Typ im Job	Auslöser	Wirkung im Active Directory
CREATE	Einladung, API CreateInAd	Neues AD-Konto, optional Gruppen, Profilpfad, Home-Laufwerk
DEACTIVATE	Ehemalige Teilnehmer, API DeactivateInAd	Konto deaktivieren, Beschreibung «Disabled by SwissMentor»
TMPRRYLOCK / TEMPORARYLOCK	Prozessschritt temporäre Sperre	Konto deaktivieren
LNGTRMLOCK / LONGTERMLOCK	Prozessschritt langfristige Sperre	Konto deaktivieren
UNLOCK	Prozessschritt Entsperren	Konto wieder aktivieren

Unbekannte Typen lässt das Skript stehen und schreibt nur ins Log.

Benutzernamen

SwissMentor vergibt den Namen, nicht das Active Directory und nicht ein CSV.

• Muster: vorname.nachname in Kleinbuchstaben, Umlaute ersetzt (ä zu ae), Leerzeichen entfernt.
• Maximal 20 Zeichen. Längere Namen werden auf den ersten Buchstaben des Vornamens plus Punkt plus Nachname gekürzt.
• Bei Kollision hängt SwissMentor 01, 02 usw. an.
• Das Initialpasswort ist ein zufälliges 12-Zeichen-Passwort. Es bleibt für dieselbe Person über Folgejobs gleich.
• Im Feld Remarks steht bei Erstell-Jobs oft der Kursname. Das Skript übernimmt den Text als AD-Beschreibung.

Das AD-Konto erhält:

• sAMAccountName: der SwissMentor-Benutzername
• User Principal Name und E-Mail: Benutzername plus die von Ihnen gesetzte Endung (z.B. @schule.ch)
• Passwort nie ablaufend, Passwortänderung durch den Benutzer ausgeschaltet

Wenn Ihre Organisation die Usernames selbst in Microsoft 365 vergibt und erst danach nach SwissMentor zurückschreiben will, passt dieser Weg nicht. Dafür bleibt die GraphQL-API (Benutzername an der Person setzen).

PowerShell-Modul einrichten

Das Modul heisst SwissMentor und liegt in der PowerShell Gallery. Es braucht das Modul PSGraphQL in der Version 1.12.1.

Install-Module -Name PSGraphQL -RequiredVersion 1.12.1 -Force
Install-Module -Name SwissMentor
Import-Module SwissMentor

Anmeldung an SwissMentor. Die URL ist die Basisadresse ohne /graphql. Das Konto muss Administrator sein.

$passwort = Read-Host -Prompt "Passwort" -AsSecureString
Connect-SwissMentor -Url "https://ihre-schule.swissmentor.com" -UserName "admin" -Password $passwort

Ohne -Password fragt das Cmdlet interaktiv nach.

Jobs abarbeiten

Import-ADUserFromSMUserJobs holt alle offenen Jobs, führt die passende AD-Aktion aus und schreibt doneAt (oder error) nach SwissMentor zurück. Typischer Aufruf:

Import-ADUserFromSMUserJobs `
    -Path "C:\Logs\SwissMentorAD\" `
    -DryMode $false `
    -OU "OU=Lernende,DC=schule,DC=ch" `
    -Groups @("M365-Lernende", "Lernende") `
    -UserPrincipalNameEnding "@schule.ch"

Zuerst mit -DryMode $true prüfen. Dann legt das Skript keine Konten an (WhatIf), schreibt aber trotzdem ins Log.

Parameter	Pflicht	Bedeutung
Path	ja	Ordner für das Logfile. Mit abschliessendem Backslash angeben.
DryMode	nein	$true = nur simulieren.
OU	nein	Distinguished Name der Ziel-OU. Ohne Angabe verwendet AD die Standard-OU.
Groups	nein	AD-Gruppen, in die neue Konten aufgenommen werden.
UserPrincipalNameEnding	nein	Suffix für UPN und E-Mail, inkl. @.
ProfilePath	nein	Basispfad für das Windows-Profil. Der Benutzername wird angehängt.
CreateHomedirectory	nein	$true legt das Home-Verzeichnis an. Dann sind DriveLetter und HomeDirectoryPath Pflicht.
DriveLetter	nein	Laufwerksbuchstabe, z.B. H:.
HomeDirectoryPath	nein	Basispfad für Home-Verzeichnisse. Der Benutzername wird angehängt.

Das Logfile heisst ADUserImportLog plus Zeitstempel und liegt in Path.

Für den Regelbetrieb eignet sich eine geplante Aufgabe (Task Scheduler) auf einem Management-Server. Intervall nach Bedarf, z.B. stündlich in Anmeldephasen.

Microsoft Entra ID statt lokales AD

SwissMentor hat keine eingebaute Benutzersynchronisation nach Entra ID. Der Server legt dort keine Konten an.

Die Jobs selbst sind verzeichnisneutral. Sie enthalten Benutzername, Initialpasswort, Typ und Person. Das mitgelieferte Skript spricht nur das lokale AD an (New-ADUser, Disable-ADAccount). Für Entra schreibt die IT ein eigenes Skript, typisch so:

1. Connect-SwissMentor und Get-UndoneSMUserJobs (Modul SwissMentor).
2. Pro Job Microsoft Graph aufrufen, z.B. New-MgUser / Update-MgUser aus dem Modul Microsoft.Graph.
3. Job mit Update-SMUserJob als erledigt oder fehlerhaft zurückmelden.

Lizenz, Gruppen und Naming in Entra bleiben Sache der Schule. SwissMentor gibt weiterhin den Benutzernamen vor (vorname.nachname). Wer die Namen in Entra selbst vergeben und erst danach nach SwissMentor zurückschreiben will, nutzt diesen Weg nicht.

Fehler und Wiederholung

• Gelingt die AD-Aktion, setzt das Skript doneAt. Der Job gilt als erledigt.
• Fehlt das AD-Konto bei Sperre oder Entsperren (nie angelegt oder bereits gelöscht), schliesst das Skript den Job trotzdem. Im Job steht der Fehlertext.
• Andere AD-Fehler (Rechte, OU nicht gefunden, Name schon vergeben) belassen den Job offen. Der nächste Lauf versucht es erneut. Der Fehlertext steht am Job.
• Konnte SwissMentor nach erfolgreicher AD-Aktion nicht aktualisiert werden, steht das im Log. Das AD-Konto existiert dann bereits. Den Job in SwissMentor von Hand prüfen.

Offene Jobs sehen Sie über GraphQL (getUndoneSMUserJobs, nur Administrator) oder indem Sie das Skript im DryMode laufen lassen und das Log lesen.

Verantwortlichkeit

Benutzerjobs trennen Fachprozess und Verzeichnisdienst:

1. Sekretariat oder Prozess in SwissMentor löst den Bedarf aus (Einladung, Sperre, API).
2. SwissMentor erzeugt den Job mit Name und Passwort.
3. Nur die IT, auf einem Rechner mit AD-Rechten, führt das Skript aus.

Solange das Skript nicht geplant oder manuell gestartet wird, ändert sich im Active Directory nichts.