LDAP Connector

This adapter establishes a connection to an LDAP server (Lightweight Directory Access Protocol) to query contact data - if required via LDAP Secure. Various operations can be executed via adapter-specific XML documents as input data.

The configuration for LDAP Secure with self-signed certificates can be done in the configuration file X4config.xml, see LDAPS configuration.

Properties

Operation

Determines which operation the adapter executes

Possible values: Execute: Execute adapter

Parameters

`Adapter`	Main class of the adapter (do not change!) Possible values: `de.softproject.integration.adapter.ldap.Ldap`: Main class (default)
`java.naming.factory.initial`	Name of the class providing the LDAP service Possible values: Any class name, e.g. `com.sun.jndi.ldap.LdapCtxFactory`
`java.naming.provider.url`	URL of the LDAP(S) server Possible values: Any URL
`java.naming.security.authentication`	Authentication method Possible values: Any valid string (e.g. `simple`)
`java.naming.security.principal`	Name of the user or authentication application (depending on the authentication method). Possible values: Any valid string (e.g. `cn=S. User, ou=NewHires, o=JNDITutorial`)
`java.naming.security.credentials`	Associated password of the user or authentication application (depending on the authentication type). Possible values: Any string (e.g. `mysecret`)
`java.naming.referral`	Defines how redirects should be handled. Possible values: `ignore`: Ignore redirects `follow`: Automatically follow all redirects `throw`: Throw a ReferralException for each forwarding (see Throwing a ReferralException)
`attributesAsElements`	Output attributes of an object Possible values: `true`: Output attributes of an object `false`: Do not output object attributes (default)
`acceptAllCertificates`	Disables the security settings by accepting any certificate. Possible values: `true`: Any certificate will be accepted. `false`: Only self-signed certificates will be accepted (default).
`acceptAllHostnames`	Disables the security settings by accepting any host name contained in the certificate. Possible values: `true`: Accepts any host name. `false`: Security settings are disabled (default).

Status values

`1`	The operation was executed successfully.
`2`	Operation `Compare` required. LDAP entry matches the information in the input XML document.
`3`	Operation `Compare` required. LDAP entry does not match the information in the input XML document.
`-1`	The operation failed due to a technical error.

Throw ReferralException

If redirects are to be processed manually, then the following steps must be followed:

Catch exception.
Read forwarding information by using ReferralException.getReferralInfo() and e.g. ask the user if the forwarding should be followed.
1. If the referral is to be followed, read the referral context with ReferralException.getReferralContext() and call the original context method again with the same arguments that should be used for the original call.
2. If the referral is not to be followed, call ReferralException.skipReferral().
  1. If this method returns true, then it means that multiple redirects should be followed.
    If that is the case, call ReferralException.getReferralContext() to continue. If a context method calls the result, then an exception is thrown again for the next redirect. Handle this exception from step 1.
  2. If the method returns false, then there are no more references and this procedure can be terminated.

More information at https://docs.oracle.com/javase/jndi/tutorial/ldap/referral/throw.html.

Input

This function adapter expects specific input XML structures that contain LDAP commands. These input XML structures can be generated dynamically via XSL mappings depending on the processed data.

search command

You can use the LDAP search command to search for entries in the LDAP directory.

Input

The LDAP Adapter expects the following input XML structure to execute the search command:

HTML/XML

<?xml version="1.0" encoding="UTF-8"?>
<ldap>
    <search>
        <!-- Distinguish Name - base node in LDAP tree where to start search -->
        <name>OU=Accounts,DC=softproject,DC=local</name>
        <!-- Search filter - required -->
        <!-- filter that is applied on search result -->
        <filter>objectclass=user</filter>
        <!-- Search control settings -->
        <controls>
            <!-- Search scope. -->
            <!-- Keywords: object, subtree, onelevel -->
            <!-- object - Results from search will contain one or zero element. -->
            <!-- One element if the named object satisfies the search -->
            <!-- filter specified in search. -->
            <!-- subtree - Search the entire subtree rooted at the named object. -->
            <!-- onelevel - Search one level of the named context. -->
            <scope>subtree</scope>
            <!-- Time limit (ms) - for request duration -->
            <timeLimit>5000</timeLimit>
            <!-- List of attributes that should be returned, separated by colon. -->
            <attributes>uSNCreated,givenname,displayName,cn</attributes>
            <!-- Count limitation for result -->
            <countLimit>100</countLimit>
        </controls>
    </search>
</ldap>

Output

The successfully executed adapter outputs the following XML document:

HTML/XML

 <ldap name="dc=sp-linux" filter="(objectclass=*)" scope="subtree"
    attributes="cn,sn" countLimit="4">
    <entry dn="dc=sp-linux" />
    <entry dn="cn=Manager,dc=sp-linux">
        <cn>Manager</cn>
    </entry>
    <entry dn="o=softproject,dc=sp-linux" />
    <entry dn="sn=Tester,o=SoftProject,dc=sp-linux">
        <sn>Tester</sn>
        <cn>John</cn>
    </entry>
    </ldap>

add command

You can use the LDAP add command to add entries to the LDAP directory.

Input

The LDAP Adapter expects the following input XML structure to execute the add command:

HTML/XML

<ldap>
    <add>
        <name>sn=Tester, o=SoftProject, dc=sp-linux</name>
        <!--dn-->
        <attributes>
            <objectClass>person</objectClass>
            <sn>Tester</sn>
            <cn>John</cn>
        </attributes>
        <!--list of attributes that will be added-->
    </add>
    </ldap>

Output

The successfully executed function adapter does not output an XML document after the add command is executed, but only the status 1 (successful) or in case of error the status -1 (Error).

modify command

With the LDAP command modify you can change entries in the LDAP directory. Thereby, as in a transaction, either all entries are changed or, in case of an error, no changes are made to the entries.

Input

The LDAP Adapter expects the following input XML structure to execute the modify command:

HTML/XML

<ldap>
    <modify>
        <name>dc=sp-linux</name>
        <!--dn-->
        <add>
            <o>Tester</o>
        </add>
        <replace>
            <o>SoftProject</o>
        </replace>
        <remove>
            <o>SoftProject</o>
        </remove>
    </modify>
    </ldap>

Example of a password replace:

XML

<ldap>
 	<modify>
 		<name>dc=sp-linux</name>
 		<add>
 			<o>Tester</o>
 		</add>
 		<replace>
 			<unicodePW base64="true">dGVzdCE=</unicodePW>
 		</replace>
	</modify>
</ldap>

Output

The successfully executed function adapter does not output an XML document after the modify command is executed, but only the status 1 (successful) or in case of error the status -1 (Error).

modifyDN (RDN) command

With the LDAP command modifyDN (RDN) you can edit entries in the LDAP directory.

Input

The LDAP Adapter expects the following input XML structure to execute the modifyDN RDN command:

HTML/XML

<ldap>
    <modifyDN-RDN>
        <oldName>sn=Tester, o=SoftProject, dc=sp-linux</oldName>
        <!--dn-->
        <newName>sn=TestUser, o=SoftProject, dc=sp-linux</newName>
        <!--dn-->
    </modifyDN-RDN>
    </ldap>

Output

The successfully executed function adapter does not output an XML document after the modifyDN RDN command is executed, but only the status 1 (successful) or in case of error the status -1 (Error).

delete command

You can use the LDAP delete command to delete entries in the LDAP directory.

Input

The LDAP Adapter expects the following input XML structure to execute the delete command:

XML

<ldap>
	<delete>
		<name>sn=Tester, o=SoftProject, dc=sp-linux</name>
		<!--dn-->
	</delete>
</ldap>

Output

The successfully executed function adapter does not output an XML document after executing the delete command, but only status 1 (successful) or in case of error status -1 (Error).

compare command

You can use the LDAP command to compare entries in the LDAP directory.

Input
The LDAP Adapter expects the following input XML structure to execute the compare command:

HTML/XML

<ldap>
    <compare>
        <name>sn=Tester, o=SoftProject, dc=sp-linux</name>
        <!--dn-->
        <attributes>
            <objectClass>person</objectClass>
            <sn>Tester</sn>
            <cn>John</cn>
        </attributes>
        <!--list of attributes that will be compared by values-->
        <controls>
            <scope>subtree</scope>
            <!--keywords: object,subtree,onelevel-->
            <timeLimit />
            <!--timeLimit (ms)-->
        </controls>
    </compare>
    </ldap>

Output

The successfully executed function adapter does not output an XML document after executing the compare command, but only the CompareTRUE status if the LDAP entry matches the information in the input XML document, or the CompareFALSE status otherwise.