Microsoft Entra ID Synchronisation#

In diesem Kapitel lernst du, wie du Benutzer und Mitarbeitende automatisch aus Microsoft Entra ID (früher Azure AD) mit ELIZA synchronisierst.

Lernziele#

Nach diesem Kapitel kannst du:

• Das Entra ID Sync-Tool einrichten und konfigurieren
• Benutzer und Mitarbeitende automatisch synchronisieren
• Organisationseinheiten-Zuordnungen konfigurieren
• Gruppen-Synchronisation einrichten
• Automatisierte Synchronisations-Jobs planen

Was ist Entra ID Synchronisation?#

Die Entra ID Synchronisation ist ein externes Tool, das Benutzerdaten zwischen Microsoft Entra ID (dem Identitätsdienst von Microsoft 365) und ELIZA automatisch abgleicht.

Vorteile der automatischen Synchronisation#

Was wird synchronisiert?#

• Benutzer: Login-Accounts werden aus Entra ID erstellt/aktualisiert
• Mitarbeitende: Personendaten werden automatisch gepflegt
• Gruppen (optional): Entra ID Gruppen können als ELIZA-Gruppen übernommen werden
• Organisationseinheiten (optional): Automatische Zuordnung basierend auf Firmendaten

Voraussetzungen#

Technische Anforderungen#

• ELIZA-Installation mit aktiviertem API-Zugang
• Microsoft 365 Tenant mit Entra ID (Azure AD)
• Python 3.10+ mit UV Package Manager
• Server-Zugriff für die Ausführung des Sync-Tools

Benötigte Zugangsdaten#

Berechtigungen in Microsoft Entra ID#

Die App Registration benötigt folgende Microsoft Graph API Berechtigungen (Application-Typ):

Diese Berechtigungen muessen vom Azure AD Administrator genehmigt werden (Admin Consent erforderlich).

Berechtigungen in ELIZA#

Der API Token benötigt folgende Berechtigungen:

• User: Lesen, Schreiben
• Mitarbeitende: Lesen, Schreiben
• Groups: Lesen, Schreiben (falls Gruppen-Sync aktiviert)

Einrichtung Schritt für Schritt#

Schritt 1: Azure AD App Registration erstellen#

1. Öffne das Azure Portal unter portal.azure.com
2. Navigiere zu Microsoft Entra ID - App registrations
3. Klicke auf + New registration
4. Fülle die Felder aus:
   • Name: ELIZA Sync (oder ein anderer beschreibender Name)
   • Supported account types: Accounts in this organizational directory only (Single tenant)
   • Redirect URI: Leer lassen (nicht benötigt)
5. Klicke auf Register
6. Notiere dir die folgenden Werte von der Overview-Seite:
   • Application (client) ID
   • Directory (tenant) ID

Schritt 2: Client Secret erstellen#

1. In der App Registration, gehe zu Certificates and secrets
2. Unter Client secrets, klicke auf + New client secret
3. Fülle aus:
   • Description: ELIZA Sync Secret
   • Expires: Wähle eine geeignete Laufzeit (z.B. 24 Monate)
4. Klicke auf Add
5. Wichtig: Kopiere den Value (Secret) sofort und speichere ihn sicher! Er wird nur einmal angezeigt.

Schritt 3: API-Berechtigungen konfigurieren#

1. Gehe zu API permissions in der App Registration
2. Klicke auf + Add a permission
3. Wähle Microsoft Graph
4. Wähle Application permissions (nicht Delegated!)
5. Suche und aktiviere:
   • User.Read.All
   • Group.Read.All
   • Directory.Read.All
6. Klicke auf Add permissions
7. Klicke auf Grant admin consent for [Tenant] (erfordert Admin-Rechte)
8. Bestätige mit Yes

Erfolgreich: Alle Berechtigungen sollten nun einen grünen Haken haben.

Schritt 4: ELIZA API Token erstellen#

1. Melde dich in ELIZA als Administrator an
2. Gehe zu Einstellungen - API Tokens
3. Klicke auf Neuer Token
4. Vergib einen Namen: Entra Sync
5. Aktiviere die benötigten Berechtigungen:
   • User (Lesen, Schreiben)
   • Mitarbeitende (Lesen, Schreiben)
   • Groups (Lesen, Schreiben) - falls Gruppen-Sync gewünscht
6. Klicke auf Speichern
7. Kopiere den Token und speichere ihn sicher

Schritt 5: Sync-Tool installieren#

Navigiere zum Sync-Tool-Verzeichnis und installiere die Abhängigkeiten:

cd pfad/zu/eliza.tools/entra_sync
uv sync

Schritt 6: Konfigurationsdatei erstellen#

1. Kopiere die Beispiel-Konfiguration:

cp config/entra_sync.yaml.example config/entra_sync.yaml

2. Öffne die Datei und trage deine Werte ein:

# Microsoft Entra ID Konfiguration
entra:
  tenant_id: "deine-tenant-id"
  client_id: "deine-client-id"
  client_secret: "dein-client-secret"

# ELIZA API Konfiguration
eliza:
  base_url: "https://firma.myeliza.ch"
  api_token: "dein-eliza-api-token"

# Synchronisations-Optionen
sync_options:
  create_users: true
  update_users: true
  create_mitarbeitende: true
  update_mitarbeitende: true
  sync_groups: false

Synchronisation durchführen#

Test mit Dry Run (Empfohlen!)#

Führe zuerst einen Dry Run durch, um zu sehen was passieren würde:

uv run python entra_sync.py --config config/entra_sync.yaml --dry-run --verbose

Der Dry Run:

• Ändert KEINE Daten in ELIZA
• Zeigt alle geplanten Aktionen an
• Hilft Konfigurationsfehler zu finden

Erste echte Synchronisation#

Wenn der Dry Run erfolgreich war:

uv run python entra_sync.py --config config/entra_sync.yaml --verbose

Begrenzte Synchronisation (zum Testen)#

Synchronisiere nur wenige Benutzer zum Testen:

uv run python entra_sync.py --config config/entra_sync.yaml --limit-users 5 --verbose

Excel-Export der Entra-Benutzer#

Exportiere alle Entra-Benutzer zur Überprüfung:

uv run python entra_sync.py --config config/entra_sync.yaml --export-excel entra_users.xlsx

Command Line Optionen#

Erweiterte Konfiguration#

Organisationseinheiten-Mapping#

Du kannst Entra ID Firmennamen auf ELIZA Organisationseinheiten mappen:

orgunit_mapping:
  "Firma AG": 1
  "Firma GmbH": 2
  "Tochtergesellschaft": 3

Feld-Mapping anpassen#

Konfiguriere welche Felder synchronisiert werden:

field_mapping:
  user:
    username: "userPrincipalName"
    email: "mail"
    first_name: "givenName"
    last_name: "surname"
  mitarbeitende:
    telefon: "mobilePhone"
    position: "jobTitle"
    abteilung: "department"

Filter für Benutzer#

Synchronisiere nur bestimmte Benutzer:

advanced:
  user_filter: "accountEnabled eq true"
  excluded_domains:
    - "external.firma.ch"
  excluded_users:
    - "admin@firma.ch"
    - "service@firma.ch"

Automatisierung mit Cron#

Für regelmässige Synchronisation kannst du einen Cron-Job einrichten:

Beispiel: Tägliche Synchronisation um 2:00 Uhr#

# Crontab bearbeiten
crontab -e

# Eintrag hinzufügen:
0 2 * * * cd /pfad/zu/entra_sync && /usr/bin/uv run python entra_sync.py --config config/entra_sync.yaml >> /var/log/entra_sync.log 2>&1

Beispiel: Alle 4 Stunden#

0 */4 * * * cd /pfad/zu/entra_sync && /usr/bin/uv run python entra_sync.py --config config/entra_sync.yaml >> /var/log/entra_sync.log 2>&1

Verwende absolute Pfade im Cron-Job und leite die Ausgabe in eine Log-Datei um.

Troubleshooting#

Häufige Fehler und Lösungen#

Logs analysieren#

Mit –verbose erhältst du detaillierte Informationen:

uv run python entra_sync.py --config config/entra_sync.yaml --dry-run --verbose 2>&1 | tee sync.log

Best Practices#

Empfohlene Vorgehensweise#

1. Immer erst Dry Run - Teste jede Konfigurationsänderung
2. Mit wenigen Benutzern starten - Verwende –limit-users 10
3. Backup erstellen - Sichere die ELIZA-Datenbank vor der ersten Sync
4. Logging aktivieren - Verwende –verbose und speichere Logs
5. Schrittweise vorgehen - Erst Benutzer, dann Mitarbeitende, dann Gruppen
6. Secrets sicher speichern - Verwende Environment Variables

Häufige Fehler vermeiden#

• Nie ohne Dry Run in Produktion synchronisieren
• Nie alle Benutzer auf einmal beim ersten Mal synchronisieren
• Secrets nicht in Git committen
• Kein Backup vor grossen Änderungen

FAQ#

Werden Passwörter synchronisiert?#

Nein, niemals. Die Synchronisation überträgt nur Profildaten wie Namen, E-Mail und Telefonnummern. Passwörter bleiben in Entra ID und werden bei der Anmeldung über OIDC/SAML geprüft.

Wie oft sollte ich synchronisieren?#

Empfehlung: Alle 4-6 Stunden für normale Organisationen. Bei häufigen Personaländerungen kann auch stündlich sinnvoll sein.

Kann ich eine Synchronisation rückgängig machen?#

Nur manuell. Es gibt keine automatische Rollback-Funktion. Deshalb: Immer erst einen Dry Run durchführen und regelmässig Backups erstellen.

Was passiert mit deaktivierten Benutzern in Entra ID?#

Standardmässig werden nur aktive Benutzer (accountEnabled eq true) synchronisiert. Du kannst dieses Verhalten in der Konfiguration anpassen.

Kann ich bestimmte Benutzer von der Synchronisation ausschliessen?#

Ja, über die excluded_users und excluded_domains Optionen in der erweiterten Konfiguration.

Zusammenfassung#

Die Entra ID Synchronisation ermöglicht:

• Automatische Benutzerverwaltung ohne manuellen Aufwand
• Konsistente Daten zwischen Microsoft 365 und ELIZA
• Zeitersparnis bei Onboarding und Offboarding
• Reduzierte Fehlerquote durch Automatisierung

Nächste Schritte:

1. Azure App Registration erstellen
2. ELIZA API Token generieren
3. Konfiguration erstellen
4. Dry Run durchführen
5. Erste Synchronisation starten
6. Automatisierung einrichten

Vorheriges Kapitel: Allgemeine Einstellungen | Zur Übersicht: Index