Skip to main content

LDAP/AD-Synchronisation mittels Job

Sie können die Kontakt- und Nutzerdaten in KIX Pro mit Daten aus dem LDAP/Active Directory befüllen. Diese Daten dienen der Verwendung als

  • Kontakte im Ticket- und Asset-Bereich

  • Kundennutzer ("User" mit "IsCustomer")

  • Agentennutzer ("User" mit "IsAgent").

Je nach verfügbarer LDAP-Quelle kann die Datensynchronisation auf verschiedenen Wegen erfolgen:

  • Synchronisations-Script bzw. -Daemon via Konsole-Kommando und SysConfig-Schlüssel

  • automatisiert über event- oder zeitbasierte Synchronisations-Jobs

Voraussetzung: Mindestens ein LDAP-basierter Verzeichnisdienst, welcher vom Backend des KIX erreichbar ist.

Achtung

Änderungen an den Kontaktdaten müssen dann ausschließlich im LDAP/AD erfolgen. In KIX vorgenommene Änderungen werden mit der Synchronisation überschrieben.

Informationen zur Anbindung von LDAP/AD-Hosts finden Sie auch unter:Authentifizierung/Autorisierung und Anbindung Active Directory

Synchronisations-Skript oder -Daemon verwenden

Konsole-Kommando

Console::Command::Maint::Auth::Sync::Synchronize

SysConfig-Schlüssel 

Daemon::SchedulerCronTaskManager::Task###AuthSynchronize

Sie können ein Skript bzw. Daemon zur Vereinfachung der AD-Anbindung verwenden, wenn alle Kontakte aus dem LDAP auch als Nutzer in KIX vorhanden sein sollen. Das Einrichten eines LDAP2Contact-Jobs kann somit entfallen. 

Das Konsole-Kommando Console::Command::Maint::Auth::Sync::Synchronize startet ein Synchronisations-Script, welches die im KIX verfügbaren Kontakte ausschließlich aus LDAP-Quellen bezieht und diese gleichzeitig als Nutzer im System zur Verfügung stellt. Bei Ausführung des Kommandos werden alle konfigurierten Auth.-Sync.-Backends abgefragt. Die daraus ermittelten Nutzer und Kontakte werden in KIX angelegt und ihren Berechtigungskontexten sowie -rollen zugeordnet (s. Authentifizierung/Autorisierung und Anbindung Active Directory). Die Konsole finden Sie im Menü System > Konsole.

Soll der Abgleich periodisch automatisiert erfolgen, können Sie den SysConfig-Schlüssel: Daemon::SchedulerCronTaskManager::Task###AuthSynchronize aktivieren (Menü System > SysConfig). Bitte beachten Sie die Zeitplanung, mit der die Ausführung erfolgt. 

Anmerkung

Wird der SysConfig-Schlüssel Daemon::SchedulerCronTaskManager::Task###AuthSynchronize gültig gesetzt, reicht ein Reload der Frontend Konfiguration nicht aus. Es muss der Daemon neu gestartet werden. Nutzen Sie dafür das Konsole-Kommando: Console::command::admin::daemon::Reload.

Automatische Deaktivierung nicht mehr verfügbarer Kontakte

Sie können das Synchronisations-Script bzw. -Daemon auch für das automatische Deaktivieren von Nutzern und Kontakten verwenden, die nicht mehr in den LDAP-Quellen vorhandenen sind. Dies kann bspw. bei unvollständigen Offboarding-Prozessen vorkommen, in welchen angrenzende Tools nicht informiert werden.

Da diese Einträge in KIX nicht mehr aktualisiert werden, findet auch keine Deaktivierung statt. Die Deaktivierung kann manuell erfolgen.

Alternativ kann das Kommando Console::Command::Maint::Auth::Sync::Synchronize mit der Option --invalidate-unsynced ausgeführt werden. Das Skript deaktiviert alle Nutzer und Kontakte, die nicht mehr aus einer der Auth.-Sync-Quellen bezogen werden können.

Damit Systemzugänge oder manuell angelegte Nutzer diesem Verhalten nicht unterliegen, können ausgewählte Login-Kenner ausgeschlossen werden. Diese Login-Kenner werden im SysConfig-Schlüssel Maint::Auth::Sync::Synchronize::Skip mittels regulärer Ausdrücke definiert. Entfernen Sie keinesfalls die initialen Einträge!

Synchronisations-Job einrichten

Sie können spezifische LDAP-Quellen direkt anbinden, um die darin enthaltenen Kontaktdaten periodisch zu synchronisieren ohne auf die Authentifizierungssynchronisation zurückzugreifen. Richten Sie dazu einen Synchronisations-Job wie nachfolgend beschrieben ein. 

Pro Job können mehrere LDAP/AD-Hosts in unterschiedlichen Formaten angegeben werden. Zudem können auch Verzeichnisdienste abgefragt werden, die eine Größenbeschränkung der Ergebnismenge verwenden ("max size exceeded").

Durch Angabe der Seitengröße (Request-Page-Size) kann eine blockweise Verarbeitung erfolgen.

  1. Navigieren Sie im Explorer zu Automatisierung > Jobs. 

    Im Contentbereich wird eine Tabelle geöffnet, welche alle im System angelegten Jobs auflistet.

  2. Klicken Sie in der Tabelle auf Neuer Job.

    Es wird ein Formular-Dialog geöffnet, in dem Sie schrittweise den neuen Job anlegen können.

    Nutzen Sie die kleinen blauen Pfeil- oder Punktschaltflächen, um zum nächsten Schritt zu gelangen oder um zwischen den Schritten zu wechseln.

    1. Job Information

      • Wählen Sie unter JobTyp die Option "Synchronisation".

      • Vergeben Sie dem Job einen aussagekräftigen Namen.

      • Optional: Beschreiben Sie den Job im Feld "Kommentar".

      • Setzen Sie den Job auf "gültig".

    2. Ausführungsplan

      • Wählen Sie aus, wann die Synchronisation erfolgen soll (Wochentage und/oder Uhrzeit).

    3. Aktionen

      • Wählen Sie die Macro-Action LDAP zu Kontakt aus.

        Es werden weitere Eingabefelder angezeigt.

        • Tragen Sie die Verbindungsdaten zum LDAP/AD-Server ein sowie die Attribute, welche mit dem LDAP/AD-Server synchronisiert werden sollen.

        • Siehe: Konfigurationsparameter

      • Sie können optional weitere Hosts angeben.

        • Klicken Sie auf button_plus.png.

          Mit jedem Klick wird eine weitere Action geöffnet.

        • Wählen Sie erneut "LDAP zu Kontakt" aus und tragen Sie auch hier die Verbindungsdaten und Attribute ein.

      • Zur besseren Übersicht können Sie die Eingabefelder der Aktionen ein- und ausklappen. Klicken Sie dazu auf die kleine Pfeilschaltfläche neben dem Plus-Symbol. dialog_arrow-up_triangle.pngdialog_arrow-down_triangle.png

  3. Speichern Sie den Job.

Die Synchronisation wird zum angegebenen Zeitpunkt ausgeführt.

Anmerkung

Wird ein LDAP zu Kontakt Synchronisations-Job ausgeführt und existiert der Nutzer bereits, dann wird der gefundene Nutzer aktualisiert und der Job fährt mit dem nächsten Nutzereintrag fort.

Konfigurationsparameter

Informationen zu den Parametern finden Sie auch unter: Attribute der Konfiguration

Parameter

Bedeutung

Überspringen

Ist hier das Häkchen gesetzt, wird die entsprechende Aktion nicht ausgeführt.

Damit können Sie einzelne Aktionen von der Synchronisation (zeitweise) ausschließen, ohne den Job neu zu konfigurieren.

Sind mehrere Aktionen im Job konfiguriert (z. B. zwei verschiedene LDAP-Server), laufen die anderen Aktionen normal weiter.

Host

FQDN welches der LDAP-Server für die Synchronisation nutzt oder kommaseparierte Liste wenn mehrere Hosts angesprochen werden sollen.

Beispiele:

  • ldap.example.org

  • ldap1.example.org,ldap2.example.org

BaseDN

Einstiegspunkt in die Verzeichnisstruktur.

Beispiel: dc=meinUnternehmen.dc=de

Contact / User Sync Map

JSON-String, der das Mapping von KIX-Attributen zu AD-/LDAP-Attributen beinhaltet.

Das Mapping muss folgende Form haben:

{
  "KIXAttributName" : "LDAPAttributName",
  "KIXAttributName" : "LDAPAttributName"
}

Alle im Mapping angegebenen Attribute müssen existieren. Anderenfalls kann keine korrekte Zuordnung erfolgen. Achten Sie auch auf korrekte Schreibweise.

Der Kontakteintrag wird auf Basis der aus dem LDAP/AD ermittelten oder fixierten Werte erstellt bzw. aktualisiert.

Die Angabe folgender Attribute ist dazu mindestens erforderlich:

  • Email

  • Firstname

  • Lastname

  • UserLogin

Achtung

Achtung!: Sind diese Angaben im LDAP-/AD-Eintrag nicht gesetzt (leer), kann kein Kontakteintrag erzeugt oder aktualisiert werden. 

Beispiel einer UserSync Map

"ContactUserSync": {
   "Email": "mail",
   "Email1": "SET:mail@example.com",
   "Email3": "mail",
   "Email5": "automatedmail",
   "Title": "title",
   "Firstname": "givenname",
   "Lastname": "sn",
   "Street": "streetAddress",
   "City": "l",
   "Zip": "postalCode",
   "Phone": "telephoneNumber",
   "Mobile": "mobile",
   "Fax": "facsimileTelephoneNumber",
   "UserLogin": "sAMAccountName",
   "PrimaryOrganisationID": "SET:123",
   "OrganisationIDs": [
      "department",
      "SET:13"
   ],
   "ImgThumbNail": "BINARY:jpegPhoto",
   "DynamicField_Source": "SET:ActiveDirectory1",
   "DynamicField_XYZ": "department",
   "DynamicField_ZIPCity":"CONCAT: postalCode}-{l}-DE"
}

UID

Name des LDAP-Attributes, welches zur eindeutigen Identifikation eines LDAP-Eintrages verwendet wird (Nutzerlogin).

Zum Beispiel: UID | sAMAccountname

Sollte kein UserLogin in der Sync Map angegeben werden, wird auf Basis der UID in der KIX Datenbank ein Nutzerlogin erstellt und auf invalid gesetzt. UID und UserLogin können ohne Probleme auf das selbe Attribut zeigen.

Tipp

Durch Setzen des Attributs "AuthAttr" im SysConfig-Schlüssel Authentication###000-Default können Sie einen alternativen Kenner für das UserLogin setzen.

Ist dieser bspw. auf "mail" gesetzt, kann sich ein Nutzer mit seiner im System hinterlegten Mailadresse anmelden.

Werden zudem die Nutzerdaten mit dem LDAP per Job synchronisiert, kann der Nutzer sich immer mit seiner aktuellen Mailadresse anmelden, auch wenn diese sich z. B. aufgrund von Namensänderung geändert hat.

Sollte die Anmeldung via Mailadresse fehlschlagen, wird die UID/das im System hinterlegte Nutzer Login als Fallback für die Authentifizierung verwendet.

Bitte beachten Sie:

Die Aktualisierung eines Kontaktattributs "Email" ist nur dann möglich, wenn in KIX ein Nutzereintrag vorhanden ist. Anderenfalls wird bei Änderung einer Email-Adresse im AD/LDAP ein neuer Kontakt angelegt.

Parameter

JSON-String für LDAP-Verbindungsparameter, z. B.:

Default:
{
    "port": "389",
    "version": "3",
    "timeout": "120",
    "async": "0"
}

Suchnutzer DN

User DN des Nutzers mit dem sich KIX mit dem LDAP Server verbindet, um die Suche durchzuführen

Beispiel: cn=kix,cn=user,dc=meinUnternehmen,dc=de

Suchnutzer Password

Passwort des Nutzers mit dem sich KIX mit dem LDAP Server verbindet, um die Suche durchzuführen

Beschränkung auf GroupDN

Erlaubt die Einschränkung der abzufragenden Einträge auf Objekte, die in der angegebenen Gruppe enthalten sind. Dies kann erforderlich sein, wenn die Gruppenmitgliedschaft nicht über einen direkten Filter auf dem Kontakteintrag eingeschränkt werden kann.

Access Attribute

Definiert das LDAP-Attribut, das zum Überprüfen der Gruppenmitgliedschaft verwendet wird. Verwendet memberUid, wenn nichts angegeben ist.

Beispiel: member| memberUid| ...

User Attribute

Legt fest, ob der Distinguished Name des Benutzers ("DN") oder das im Parameter "UID" definierte LDAP-/AD-Attribut zur Überprüfung der Gruppenmitgliedschaft verwendet wird.

Immer filtern

Permanenter LDAP Filter, der für alle Anfragen angewandt wird.

Syntax: (&(mail=*)(sAMAccountName=*))

Beispiele:

  • alle nicht-deaktivierten Nutzerkonten:

    (&(objectClass=user)(! (userAccountControl:1.2.840.113556.1.4.803:=2)))

  • alle Nutzereinträge, bei denen "departmentNumber" und "mail" gesetzt ist:

    (&(objectClass=user)(departmentNumber=*)(mail=*))

Sie können auch Gruppenfilter eingetragen.

Weitere Beispiele finden Sie unter: http://www.selfadsi.de/ldap-filter.htm

Zeichensatz

Zeichensatz, in den die LDAP-Suchergebnisse konvertiert werden.

Default: utf-8

Seitengröße

Sie können bei Bedarf die Gesamtanzahl der zu synchronisierenden Daten in mehrere Datenpakete zu je n Datensätzen aufsplitten.

Bspw. wenn Sie vom Server die Nachricht erhalten, dass der Antwortdatensatz zu groß ist ("max size exceeded"). 

Tragen Sie hier die Anzahl der Datensätze ein, die pro Anfrage (Request) übertragen werden. Die Verarbeitung erfolgt dann blockweise in Paketen mit bspw. 20 Datensätzen.

Debug

Debug-Ausgaben de-/aktivieren.

Mögliche Werte: yes | no

Ist der Parameter aktiv, werden wesentliche Schritte des LDAP-/AD-Datenabgleichs im Log des Jobs (Job-Historie) vermerkt. 

Hinweis

  • Diese Option sollte nur vorübergehend aktiviert werden, da sonst die Historieneinträge sehr umfangreich werden und entspr. Speicherbedarf erzeugen.

  • Der SysConfig-Schlüssel Automation::MinimumLogLevel muss auf den Wert "Debug" gesetzt sein. Anderenfalls werden nur die von der Macro Action gelieferten Fehlermeldungen erfasst, alle anderen Debug-Informationen jedoch nicht.

Dry Run

Trockenlauf (Testlauf) de-/aktivieren.

Ist der Parameter aktiviert, erfolgt kein tatsächlicher Datenabgleich. Die aus der LDAP-/AD-Quelle ermittelten Daten werden jedoch im Job-Log vermerkt, als würde ein Update stattfinden. Der Datenabgleich kann somit im Vorfeld zu Testzwecken simuliert werden. 

Hinweis

Diese Option sollte wie Debug nur vorübergehend aktiviert werden, da sonst die Historieneinträge sehr umfangreich werden und entsprechend Speicherbedarf erzeugen.

Es wird weiterhin empfohlen, diese Funktion in Verbindung mit AlwaysFilter zu verwenden um spezifische oder eine geringe Anzahl von LDAP-Einträgen zu prüfen.

Anmerkung

  • Ist im Mapping das User-Attribut "Login" enthalten, wird auch ein User synchronisiert.

  • Ein vorhandener Kontakt wird beim Ausführen des Jobs, basierend auf dem Mapping, aktualisiert.

  • Ein nicht vorhandener Kontakt wird beim Ausführen des Jobs neu erstellt.

Hinweis

  • Die Nutzeranmeldung ist von der Synchronisation nicht direkt betroffen, jedoch die Funktion des "AuthSync".

  • Beim automatischen Import ist auf Datenbeschränkungen des AD zu achten (blockweises Einlesen).

  • Single-Point-of-Trust ist das externe System.

Konfigurationshinweise

Sie können für bestimmte KIX-Attribute an einem Kontakt/Nutzer einen voreingestellten Wert anstelle eines LDAP-Attributes angeben. Dies erfolgt über das Keyword "SET:", welches vor dem zu setzenden Wert eingebunden wird. Das Keyword ist caseinsensitive.

Beispiel: SyncMap mit fixierten Parametern

{
"Email": "mail",
"Title": "title",
"Firstname": "givenname",
"Lastname": "sn",
"Street": "streetAddress",
"City": "l",
"Zip": "postalCode",
"Phone": "telephoneNumber",
"Mobile": "mobile",
"Fax": "facsimileTelephoneNumber",
"UserLogin": "sAMAccountName",
"IsAgent": "SET:1",
"IsCustomer": "SET:0",
"PrimaryOrganisationID": "department"
}
In diesem Abschnitt: