LDAP Connector

Usage

You can use the LDAP connector to insert, change, delete, and search for data on a Lightweight Directory Access Protocol (LDAP) server.

Connector types

The LDAP connector can be configured as a medium connector or an output connector:

Medium Connector

As a medium connector, the LDAP connector receives a query as a DSML message from its predecessor, sends the query to the LDAP server, receives a result from the LDAP server, and forwards the result to the subsequent module.
Output Connector

As an output connector, the LDAP connector receives a DSML message from its predecessor and sends the query to the LDAP server.

Principles

The LDAP connector establishes the connection to an LDAP server, reads a DSMLv2 request, and converts the statements contained therein into LDAP calls.

The Directory Services Markup Language (DSML) is an OASIS standard that specifies access to directories using an XML schema and SOAP transport mechanism and depicts the entire LDAP data model.

To establish the connection to an LDAP server and execute queries, you have to:

Create an LDAP connector with connection data for the LDAP server.

Use an XSLT converter to create a DSMLv2 request with the following syntax:

<batchRequest
   xmlns="urn:oasis:names:tc:DSML:2:0:core">
   <!-- Every single statement must contain a
         DN attribute! -->
   <modifyRequest
      dn="CN=Joe Smith, OU=Dev, DC=inubit,
      DC=com">…
   </modifyRequest>
   <addRequest>…</addRequest>
   <delRequest>…</delRequest>
</batchRequest>

The response depends on the configuration of the connector:
- In the case of an output connector, error or success messages are returned.
- In the case of a medium connector, the results are returned in the form of a DSMLv2 response:
  <batchResponse xmlns="urn:oasis:names:tc:DSML:2:0:core"> <modifyResponse>…</modifyResponse> <addResponse>…</addResponse> <delResponse>…</delResponse> </batchResponse>

Configuring the Number of Elements to be Fetched

Usage

To configure how many elements are to be fetched from the LDAP server at once

Functional Principle

Using the pageSize attribute in the XSLT stylesheet, you can configure how many elements the LDAP Connector shall fetch at once from the LDAP Server.

If there are more items than configured with the pageSize attribute on the LDAP server, the LDAPConnector.config.nextPage module variable exists. With this, you configure the condition at a Demultiplexer module to fetch the next items from the LDAP Server.

Prerequisites

You have configured a workflow containing an LDAP Connector, for example:

Proceed as follows

Open the workflow for editing.
Open the XSLT Connector for editing.
Open the Module Editor page.
In the searchRequest section of the XSLT stylesheet, add the pageSize attribute with the value to define the number of entries to be fetched at once from the LDAP Server.

The template to be used in the XSLT Connector is stored in the LDAP_Queries.xml INUBIT Repository file in the following folder:

/Global/System/Mapping Templates/LDAP Connector

The XSLT stylesheet should look like this:
Click Finish to save the changes.
For the Demultiplexer module, configure the connection condition back to the Joiner module as follows:
1. In the Conditions section, click on Add condition.
2. On the left, click the V icon.
3. Choose the LDAPConnector.config.nextPage module variable.
4. Choose exists from the operators list.
  
  The condition must look like this:
Click OK to save the changes.
Publish the workflow and the containing modules.

DSMLv2 Statements in LDAP Connector Requests

This section details the following DSMLv2 statements:

For all accesses to specific entries on an LDAP server, you require the unique names (distinguished names) of the objects in question.

DN attributes in statements

Each statement in a request must have a DN (distinguished names) attribute. The DN attribute is required in order to uniquely identify an entry in an LDAP directory. It describes the exact location of the entry in question in the directory hierarchy.

Further information:

DSML documentation and DSML-schema, refer to https://www.oasis-open.org/committees/dsml/docs/DSMLv2.doc
Complete definition of distinguished names, refer to https://www.ietf.org/rfc/rfc2253.txt

Modify in the LDAP Connector

In DSMLv2, all changes to attributes are specified by appending an operation attribute to an attr element. An operation can be add, delete, or replace.

Example

The statement below updates the telephone number of an employee named Bob Rush:

<modifyRequest
  dn="CN=Bob Rush,OU=Dev,DC=Example,DC=COM">
   <modification
      name="telephoneNumber"
      operation="replace">
      <value>536 354 2343</value>
      <value>234 212 4534</value>
   </modification>
</modifyRequest>

Search in the LDAP Connector

The statement searchRequest searches for data on the LDAP server.

Example Search and output

The system searches for all people named John in the path ou=Marketing, dc=inubit, dc=com. All found search objects are output, including all their attributes.

<searchRequest
  dn="ou=Marketing,dc=inubit,dc=com"
  scope="singleLevel"
   derefAliases="neverDerefAliases"
   sizeLimit="1000">
   <filter>
      <equalityMatch name="cn">
         <final>john</final>
      </equalityMatch>
   </filter>
</searchRequest>

Example Search and limit output

In the following example, the same search criteria are used as in the example above, but the output attributes are limited to the objectSid attribute only.

<searchRequest
   dn="ou=Marketing,dc=inubit,dc=com"
   scope="singleLevel"
   derefAliases="neverDerefAliases"
   sizeLimit="1000">
   <filter>
      <equalityMatch name="cn">
         <value>john</value>
      </equalityMatch>
   </filter>
   <attributes>
      <attribute name="objectSid" type="binary"/>
   </attributes>
</searchRequest>

If binary attributes are to be read by using the LDAP Connector, these attributes must already be distinguished and masked in the input message. To do this, you must insert the additional attribute `type="binary" `into the search request. Thus, the values for binary attributes from the LDAP system are then included in the XML output message as base64-encoded content.

Add in the LDAP Connector

You use <addRequest> to insert new objects and attributes.

Example

The statement for adding the object Alice Johnson `with the type `person is as follows:

<addRequest
   dn="OU=Marketing,DC=inubit,DC=com">
   <attr name="objectclass">
      <value>person</value>
   </attr>
   <attr name="objectclass">
      <value>organizationalPerson</value>
   </attr>
   <attr name="sn">
      <value>Johnson</value>
   </attr>
   <attr name="givenName">
      <value>Alice</value>
   </attr>
   <attr name="title">
      <value>Software Design Engineer</value>
   </attr>
</addRequest>

Delete in the LDAP Connector

You use the <delRequest> statement to delete data from the LDAP server.

Example

This statement deletes the object Alice from the LDAP database:

<delRequest dn="cn=Alice, ou=Marketing, dc=inubit,dc=com"/>

Dialog LDAP Connector Properties

In this dialog, you have the following options:

LDAP server

URL

LDAP: Replace <hostname> by the name or the IP address of the LDAP server. The ldap:// protocol name can be omitted.
LDAP over SSL: To establish a secured connection via SSL, replace the ldap protocol name with ldaps and replace <hostname> by the name or the IP address of the LDAP server.

LDAP START TLS: To establish a secured connection via START TLS, replace <hostname> by the name or the IP address of the LDAP server and select Enable Encryption. The ldap:// protocol name can be omitted.

If Enable Encryption is checked and the server URL starts with ldap://, START TLS is used. If the server URL starts with ldaps://, LDAP over SSL is used automatically and the Enable Encryption checkbox is ignored.

If the connection test fails with the predefined port number 389, ask the administrator of the LDAP server for the correct number.

SSL button

For securing the communication with SSL, refer to Dialog SSL Configuration.

Client authentication aliases are not applicable, so selecting an alias will have no effect.
Connection Pooling

Activate this option to reuse existing connections to the LDAP Server.
Enable Encryption

To enable encrypted connection with LDAP Server via START TLS or SSL, select Enable Encryption.

Authentication

Anonymous login

Select this option if the LDAP server supports anonymous login.
Use static login data
- Login/Password
  
  If you are not using anonymous login, enter your user ID and password for the LDAP server.
Select from Credentials Manager

include::module-guide:partial$use-credentials-manager-for-authentication.adoc[]f

Naming service

Class name

Pre-filled with the default Java class delivered with the INUBIT software. To use a different class for the LDAP naming and directory service, enter the name of the class in question.

Make sure that the specified class exists in the Java class path.

Further Settings

Referral handling

Specify how referrals to other directories are to be handled.
- Follow
  
  Follow any referral automatically
- Ignore (default)
  
  Ignore referrals
Connection test
- Test connection
  
  For testing whether the connection can be successfully established using your configuration.