LdapDataProvider

---

Der LdapDataProvider lädt die Daten eines Object bzw. einer ObjectCollection direkt aus einem LDAP- oder LDAPS-Verzeichnis — zum Beispiel aus einem Active Directory. Damit lassen sich Personen-, Gruppen- oder Standortdaten aus dem Verzeichnis in einem Formular auswählen, ohne sie vorher in eine Datenbank oder Datei zu exportieren.

Der Provider ist ein service-basierter DataProvider: Die Abfrage läuft serverseitig über den DataService, analog zum SqlDataProvider und HttpDataProvider.

Konfiguration

Neben Mapping bzw. Code und den optionalen SearchParameters (siehe Datenschnittstelle) wird der LdapDataProvider über das Options-Element konfiguriert:

<LdapDataProvider DisplayName="Mitarbeitende">
  <SearchParameters>
    <Text Id="lastName" Label="Nachname" />
  </SearchParameters>
  <Options>
    <Server>ldaps://dc01.example.com</Server>
    <UserName>CN=Service,OU=Accounts,DC=example,DC=com</UserName>
    <Password>{EncryptedPassword}</Password>
    <BaseDn>OU=Users,DC=example,DC=com</BaseDn>
    <Filter>(&amp;(objectClass=user)(sn={lastName}*))</Filter>
    <Attributes>cn,sn,givenName,mail,telephoneNumber</Attributes>
  </Options>
  <Mapping>
    <Map Source="givenName" Target="FirstName" />
    <Map Source="sn" Target="LastName" />
    <Map Source="mail" Target="Email" />
  </Mapping>
</LdapDataProvider>

Options

Element	Beschreibung
Server (optional)	LDAP-Server. Zulässig sind ein reiner Hostname, host:port, ldap://host[:port] (Standardport 389) oder ldaps://host[:port] (SSL/TLS, Standardport 636). IPv6-Literale werden unterstützt — ohne Port direkt (fe80::1), mit Port in Klammern ([2001:db8::1]:636). Ohne Angabe wird die Domäne des aktuellen Computers verwendet, über Plain-LDAP auf Port 389; für ldaps:// muss der Server explizit gesetzt werden.
UserName (optional)	Distinguished Name oder User Principal Name für den Simple Bind, z.B. CN=Service,OU=Accounts,DC=example,DC=com oder service@example.com. Nur zusammen mit Password gültig, siehe Authentifizierung.
Password (optional)	Passwort für den Simple Bind. Wird gleich verschlüsselt wie der ConnectionString des SqlDataProvider (siehe Verschlüsselung). Nur zusammen mit UserName gültig.
BaseDn (optional)	Distinguished Name der Suchbasis, z.B. OU=Users,DC=example,DC=com. Ohne Angabe wird der defaultNamingContext aus der RootDSE des Servers ermittelt.
Filter (erforderlich)	LDAP-Suchfilter nach RFC 4515, z.B. (&(objectClass=user)(sn={lastName}*)). {platzhalter}-Tokens werden durch die Werte der SearchParameters ersetzt (siehe Platzhalter im Filter).
Attributes (optional)	Kommagetrennte Liste der zurückzugebenden Attribute, z.B. cn,sn,givenName,mail. Ohne Angabe werden alle Benutzerattribute geliefert (keine operationalen Attribute).
Scope (optional)	Suchtiefe relativ zum BaseDn: Base (nur der Basiseintrag), OneLevel (nur direkte Kindelemente) oder Subtree (gesamter Teilbaum, Standard).
SizeLimit (optional)	Maximale Anzahl zurückgegebener Einträge. 0 (Standard) überlässt die Begrenzung dem Server.
IgnoreCertificateErrors (optional)	Wenn true: Bei ldaps:// werden Zertifikatsfehler ignoriert (z.B. selbstsignierte Zertifikate). Standard false — die Zertifikatsprüfung ist also aktiv.

Authentifizierung und automatische Ermittlung

Läuft der primedocs Server in derselben Active-Directory-Domäne wie das Verzeichnis, genügt der Filter — Server, Anmeldeinformationen und Suchbasis werden zur Laufzeit ermittelt. Das entspricht dem Verhalten der LdapSyncSource im UserSync.

• Mit Anmeldeinformationen: UserName und Password wirken nur paarweise. Ist nur eines der beiden gesetzt, meldet die Konfigurationsvalidierung einen Fehler, und die Abfrage bricht zur Laufzeit ab. Verbunden wird über einen Simple Bind.
• Ohne Anmeldeinformationen: Werden beide weggelassen, authentifiziert sich der Provider als das Konto, unter dem der Serverprozess läuft (Windows-Authentifizierung, Negotiate). Ein Dienstkonto in der Konfiguration ist dann nicht nötig.

Minimale Konfiguration für dieses Szenario:

<LdapDataProvider DisplayName="Mitarbeitende">
  <Options>
    <Filter>(&amp;(objectClass=user)(objectCategory=person))</Filter>
  </Options>
  <Mapping>
    <Map Source="givenName" Target="FirstName" />
    <Map Source="sn" Target="LastName" />
    <Map Source="mail" Target="Email" />
  </Mapping>
</LdapDataProvider>

Wenn die automatische Ermittlung fehlschlägt

Situation	Verhalten
Server fehlt und die Domäne des Computers ist nicht ermittelbar (Rechner nicht in der Domäne, Nicht-Windows-System, fehlende Berechtigung)	Die Abfrage bricht mit dem Hinweis ab, <Server> explizit zu konfigurieren.
BaseDn fehlt und die RootDSE des Servers liefert keinen defaultNamingContext	Die Abfrage bricht mit dem Hinweis ab, <BaseDn> explizit zu konfigurieren.
Nur UserName oder nur Password gesetzt	Konfigurationsfehler: «UserName and Password must be configured together — omit both to authenticate as the current process account (Negotiate).»

Platzhalter im Filter

Im Filter werden {platzhalter}-Tokens durch den Wert des gleichnamigen Suchparameters ersetzt. Im Beispiel oben füllt der Suchparameter lastName den Platzhalter {lastName}.

Die eingesetzten Werte werden nach RFC 4515 escaped. Eine Benutzereingabe kann die Filterstruktur damit nicht verändern (Schutz vor LDAP-Injection) — Zeichen wie *, (, ) oder \ werden als Literal behandelt und wirken nicht als Filteroperator.

Wildcards gehören in den Filter

Weil Eingaben escaped werden, wirkt ein vom Benutzer eingegebener * nicht als Wildcard. Soll eine «beginnt mit»-Suche möglich sein, gehört der Stern in den Filter selbst: (sn={lastName}*).

Ergebnis und Mapping

Jeder gefundene Verzeichniseintrag wird zu einem Eintrag der Objektsammlung. Für die Zuordnung auf das Schema stehen — wie bei den übrigen service-basierten Providern — Mapping (deklarativ, siehe Mapping) oder Code (JavaScript) zur Verfügung; die beiden schliessen sich gegenseitig aus.

Beim Zugriff auf die Attribute gilt:

• Der Distinguished Name des Eintrags steht immer als dn zur Verfügung, auch wenn Attributes gesetzt ist.
• Mehrwertige Attribute (z.B. memberOf) werden zu einem Wert zusammengefügt, getrennt durch "; ".

Binäre Attribute

Binäre Attribute wie objectGUID oder objectSid werden als UTF-8 dekodiert und sind deshalb nicht sinnvoll nutzbar. Für eine stabile Identifikation eignet sich dn.

Sicherheit

• ldaps:// verwenden, sobald ein Dienstkonto konfiguriert ist. Beim Simple Bind über Klartext-LDAP (ldap://, Port 389) wird das Passwort unverschlüsselt übertragen; der Server protokolliert in diesem Fall eine Warnung. Ohne konfigurierte Anmeldeinformationen entfällt die Warnung, weil kein Passwort übertragen wird.
• Dienstkonto mit minimalen Rechten einsetzen — Lesezugriff auf den benötigten Teilbaum genügt. Ohne Anmeldeinformationen gilt dasselbe für das Konto des Serverprozesses.
• IgnoreCertificateErrors nur in Testumgebungen aktivieren. Ist die Option gesetzt, protokolliert der Server eine Warnung, weil das Serverzertifikat nicht geprüft wird.

Einschränkungen

• Als Bind-Verfahren stehen Simple Bind (mit UserName/Password) und Negotiate (ohne Anmeldeinformationen, als Konto des Serverprozesses) zur Verfügung. Ein anonymer Bind wird nicht unterstützt.
• Die automatische Server-Ermittlung verwendet immer Plain-LDAP auf Port 389. Für eine verschlüsselte Verbindung muss Server mit ldaps:// gesetzt werden.
• StartTLS wird nicht unterstützt; verschlüsselte Verbindungen laufen über ldaps://.
• Kürzt der Server das Ergebnis (überschrittenes Grössenlimit), werden die bis dahin gelieferten Einträge verwendet und eine Warnung protokolliert.

Verwendung in Connect Session Templates

Der LdapDataProvider steht auch als Initializer in Connect Session Templates zur Verfügung, um ein Formular beim Öffnen bereits mit Verzeichnisdaten vorzubefüllen. Dabei werden die Query-Parameter der aufrufenden URL automatisch als Suchdaten weitergereicht und lösen die {platzhalter}-Tokens im Filter auf. Wie bei den übrigen Initializern erfolgt die Transformation im Code-Element; Mapping wird dort nicht unterstützt.

Beispiel-XML-Konfiguration

Auswahl einer Kostenstellenverantwortlichen aus dem Active Directory, eingeschränkt auf eine Organisationseinheit:

<ObjectCollection Id="Approver" Label="Genehmigende Person">
  <Schema>
    <Text Id="FullName" Label="Name" />
    <Text Id="Email" Label="E-Mail" />
    <Text Id="Phone" Label="Telefon" />
    <Text Id="Department" Label="Abteilung" />
  </Schema>
  <Summary>
    <Field Id="FullName" />
    <Field Id="Department" />
  </Summary>
  <DataProviders>
    <LdapDataProvider DisplayName="Active Directory">
      <SearchParameters>
        <Text Id="name" Label="Name" />
      </SearchParameters>
      <Options>
        <Server>ldaps://dc01.example.com</Server>
        <UserName>service@example.com</UserName>
        <Password>{EncryptedPassword}</Password>
        <BaseDn>OU=Finance,OU=Users,DC=example,DC=com</BaseDn>
        <Filter><![CDATA[(&(objectClass=user)(!(userAccountControl:1.2.840.113556.1.4.803:=2))(|(sn={name}*)(givenName={name}*)))]]></Filter>
        <Attributes>displayName,mail,telephoneNumber,department</Attributes>
        <Scope>Subtree</Scope>
        <SizeLimit>50</SizeLimit>
      </Options>
      <Mapping>
        <Map Source="displayName" Target="FullName" />
        <Map Source="mail" Target="Email" />
        <Map Source="telephoneNumber" Target="Phone" />
        <Map Source="department" Target="Department" />
      </Mapping>
    </LdapDataProvider>
  </DataProviders>
</ObjectCollection>

tipp

Enthält der Filter Zeichen wie &, < oder >, empfiehlt sich ein <![CDATA[ … ]]>-Block — so bleibt der Filter lesbar und muss nicht als XML-Entity geschrieben werden (&).