LDAP Connector

The LDAP connector implements the DirX Identity Java Connector Integration Framework’s DxmConnector interface and connects to an LDAP server through the Netscape LDAP interface. It can be used for Tcl-based workflows in the C++-based Server and realtime workflows in the Java-based (IdS-J) Server. Like all framework-based agents, it gets SPML requests from the Identity side and converts them to the appropriate Netscape LDAP interfaces on the LDAP server side and vice versa.

Overview

The connector implements the API methods "add(…)", "modify(…)", "delete(…)" and "search(…)". They represent the corresponding SPML requests "AddRequest", "ModifyRequest", "DeleteRequest" and "SearchRequest".

Request and Response Handling

This section describes the supported requests and attributes for the LDAP connector.

AddRequest

In an add request, the identifier, which is always expected to be a DN, is mandatory. All object classes and all attributes contained in the schema of the LDAP server can be passed in the add request.

Example request:

<?xml version="1.0" encoding="UTF-8" ?>
<spml:batchRequest xmlns="urn:oasis:names:tc:SPML:1:0"
  xmlns:spml="urn:oasis:names:tc:SPML:1:0"
  xmlns:dsml="urn:oasis:names:tc:DSML:2:0:core"
 requestID="batch-1"
  processing="urn:oasis:names:tc:SPML:1:0#sequential"
 execution="urn:oasis:names:tc:SPML:1:0#synchronous"
  onError="urn:oasis:names:tc:SPML:1:0#exit">
  <spml:addRequest requestID="add-1">
     <spml:identifier type="urn:oasis:names:tc:SPML:1:0#DN">
        <spml:id>cn=my class,cn=supplier groups,cn=groups,cn=Extranet Portal,cn=TargetSystems,cn=my-company</spml:id>
     </spml:identifier>
     <spml:attributes>
        <spml:attr name="objectclass" xmlns="urn:oasis:names:tc:DSML:2:0:core">
            <dsml:value>dxrTargetSystemGroup</dsml:value>
        </spml:attr>
        <spml:attr name="uniqueMember" xmlns="urn:oasis:names:tc:DSML:2:0:core">
           <dsml:value>cn=my-company</dsml:value>
        </spml:attr>
        <spml:attr name="dxrState" xmlns="urn:oasis:names:tc:DSML:2:0:core">
           <dsml:value>ENABLED</dsml:value>
        </spml:attr>
    </spml:attributes>
  </spml:addRequest>
</spml:batchRequest>

ModifyRequest

In a modify request, the identifier is also mandatory. All object classes and their attributes contained in the schema of the LDAP server can be modified.

Example request:

<?xml version="1.0" encoding="UTF-8" ?>
<spml:batchRequest xmlns="urn:oasis:names:tc:SPML:1:0"
xmlns:spml="urn:oasis:names:tc:SPML:1:0"
xmlns:dsml="urn:oasis:names:tc:DSML:2:0:core"
requestID="batch-1"
processing="urn:oasis:names:tc:SPML:1:0#sequential"
execution="urn:oasis:names:tc:SPML:1:0#synchronous"
onError="urn:oasis:names:tc:SPML:1:0#exit">
<spml:modifyRequest requestID="mod-2">
<spml:identifier
  type = "urn:oasis:names:tc:SPML:1:0#DN">
  <spml:id>cn=standard class,cn=supplier groups,cn=groups,cn=Extranet Portal,cn=TargetSystems,cn=my-company</spml:id>
</spml:identifier>
<spml:modifications>
  <spml:modification name="dxrGroupMemberAdd" operation="delete">
     <dsml:value>cn=YYYJimmy Sails 23e,ou=accounts,ou=extranet,o=sample-ts</dsml:value>
  </spml:modification>
  <spml:modification name="dxrGroupMemberAdd" operation="add">
     <dsml:value>cn=XXXJimmy Sails 23e,ou=accounts,ou=extranet,o=sample-ts</dsml:value>
     <dsml:value>cn=Jimmy Sails 23e,ou=accounts,ou=extranet,o=sample-ts</dsml:value>
  </spml:modification>
</spml:modifications>
</spml:modifyRequest>
</spml:batchRequest>

Rename/Move Functionality

If the operational attributes of the modify request contain the attribute dxrPrimaryKeyOld the object in the LDAP system is renamed or moved from the position represented by the DN value of dxrPrimaryKeyOld to the position of the DN value passed with the identifier. If only the RDN part of the DNs are different it is a rename, if other parts of the DNs differ, for example an OU, a move operation is performed.

Usually, the check for the last RDN (rename) is case insensitive. So, you are not able to change, for example, the ou=RedFlag to ou=Redflag. If you want to enable such a rename (case sensitive), you must provide the operational attribute caseExactRDNComparison with the value true in your modify request. Here is a sample request (ou=RedFlag → ou=Redflag):

<spml:modifyRequest requestID="mod-2">
<spml:identifier
    type = "urn:oasis:names:tc:SPML:1:0#DN">
    <spml:id>ou=Redflag,cn=Custom,cn=BusinessObjects,cn=My-Company</spml:id>
</spml:identifier>
   <spml:operationalAttributes>
       <spml:attr name="dxrPrimaryKeyOld">
           <dsml:value type="string">ou=RedFlag,cn=Custom,cn=BusinessObjects,cn=My-Company</dsml:value>
       </spml:attr>
       <spml:attr name="caseExactRDNComparison">
           <dsml:value type="string">true</dsml:value>
       </spml:attr>
   </spml:operationalAttributes>
<spml:modifications>
    <spml:modification name="description" operation="replace">
           <dsml:value>erster modify</dsml:value>
    </spml:modification>
</spml:modifications>
</spml:modifyRequest>

Single Modification Processing

If multiple values are to be deleted or added within a modification request - like in the sample request above - and the request fails with one of the following LDAP error codes in the situations previously described, the LDAP connector by default performs single modifications for each value and then logs the values and operations that failed.

LDAP error codes and situations resulting in single modifications:

  • ATTRIBUTE_OR_VALUE_EXISTS (add dn value or value that already exists in DirX; add value that already exists in AD)

  • NO_SUCH_ATTRIBUTE (delete dn value or value that does not exist in DirX; delete value that does not exist in AD)

  • ENTRY_ALREADY_EXISTS (add dn value that already exists in AD)

  • UNWILLING_TO_PERFORM (delete dn value that does not exist in AD)

  • NO_SUCH_OBJECT (add dn value for object that does not exists in AD)
    This is the situation when members are tried to be added to a group in Active Directory, but the member objects do not exist yet in the directory.

Single modification processing can be turned off with the connection section property perform_single_mod. If not specified it is turned on. Since the ADS connector is derived from the LDAP connector this property can also be specified in an ADS connector’s connection section.

LDAP Relaxed Update Control

If an LDAP server supports the LDAP Relaxed Update Control - the DirX LDAP server supports it since version 8.1B - the LDAP connector uses this control when performing modifications. The LDAP server returns SUCCESS in the ATTRIBUTE_OR_VALUE_EXISTS or NO_SUCH_ATTRIBUTE situations described above. In those cases, the LDAP connector no longer performs the single modifications itself because a SUCCESS code is returned and the LDAP server performs the operation. In all cases, one of the five error codes shown above is returned. The LDAP connector performs single value modifications and logs the failed values.

DeleteRequest

In a delete request, the identifier is also mandatory. Any type of object can be deleted. The delete request does not require additional attributes.

SearchRequest

In an SPML search request, the LDAP connector supports the standard elements searchBase and filter and the operational attributes scope, sizeLimit, pageSize, pagedTimeLimit, sortAttribute, sortOrder and noattrs (if set to FALSE or not existing either all attributes or the ones specified are retrieved).

Example request:

<?xml version="1.0" encoding="UTF-8" ?>
<spml:searchRequest  xmlns="urn:oasis:names:tc:SPML:1:0"
      xmlns:spml="urn:oasis:names:tc:SPML:1:0"
      xmlns:dsml="urn:oasis:names:tc:DSML:2:0:core"
      requestID="search_01"
      >
 <spml:searchBase type = "urn:oasis:names:tc:SPML:1:0#DN">
    <spml:id>ou=Intranet,o=sample-ts</spml:id>
 </spml:searchBase>
      <spml:filter>
            <dsml:present name="objectClass" />
      </spml:filter>
 <spml:operationalAttributes>
    <dsml:attr name="scope">
       <value>subtree</value>
    </dsml:attr>
    <dsml:attr name="sortAttribute">
       <value>cn</value>
    </dsml:attr>
    <dsml:attr name="sortOrder">
       <value>ASCENDING</value>
    </dsml:attr>
    <dsml:attr name="pageSize">
       <value>0</value>
    </dsml:attr>
 </spml:operationalAttributes>
 <spml:attributes>
    <dsml:attribute name="cn"/>
    <dsml:attribute name="sn"/>
     <dsml:attribute name="givenName"/>
     <dsml:attribute name="company"/>
     <dsml:attribute name="mail"/>
     <dsml:attribute name="st"/>
     <dsml:attribute name="street"/>
     <dsml:attribute name="employeeNumber"/>
     <dsml:attribute name="telephoneNumber"/>
 </spml:attributes>
</spml:searchRequest>

Configuration

Here is a sample configuration snippet for the LDAP connector (without SSL connection):

<connector
role="connector"
className="siemens.dxm.connector.ldap.LdapConnector"
name="Ldap Connector" version="1.00">
<connection type="LDAP"
user="CN=metatest,CN=Users,DC=mydomain,DC=mchp,DC=mycompany,DC=de"
password="XXXyyy###111"
server="myserver"
port="389"
ssl="false"
<property name="debugfile" value="dbgOut.xml"/>
<property name="perform_single_mod" value="true"/>
<property name="check_password_history" value="false"/>
<mvproperty name=”binaryattributes”>
       <value>customer LDAP attribute type 1</value>
       <value>customer LDAP attribute type n</value>
</mvproperty>
</connection>
</connector>

Supported Connection Parameters

The LDAP connector supports the following properties from the standard properties of the <connection> element of the XML configuration file:

port - the port number of the LDAP server.

server - the server name or IP address of the LDAP server.

user - the user name in DN form used for the connection.

password - the password for this user used for binding to the LDAP server.

ssl - whether (true) or not (false) to use server-side or client-side SSL/TLS.

For client-side SSL, the following additional parameters are available:

authentication=“CLIENT_SSL”

keystore – the file name of the key store

keystorepassword – the password for accessing the key store

keystorealias - optionally an alias name of the relevant entry in the key store

truststore - the file name of the truststore

truststorepassword – the password for accessing the trust store

Non-standard supported properties are:

debugfile - (optional); if this property is configured, it outputs each received request and response to this file in SPML format.

perform_single_mod - (optional) whether (true) or not (false) single modifications for multi-value attributes in specific erroneous situations are performed. (See the section "Single Modification Processing" for details.)

check_password_history - (optional) whether (true) or not (false) the connector checks password history. If this property is configured and set to true, the LDAP connector first checks whether the connected LDAP server supports the LDAPAdsPolicyHintsControl. If it does, the LDAP connector uses this control on modify operations with the result that password history is checked for both password reset operations and password change operations.

binaryattributes - (optional); specifies a customer specific list of LDAP attribute types.

LDAP SSL Setup

This section describes LDAP SSL setup.

Setting up a Server-side SSL Connection to an LDAP Directory

Use the "keytool" of the Java Runtime Environment to import your certificate into the Cert store.

To set up the SSL connection, see the section in "Core Component → Using LDAP → SSL/TLS" in the online help (not available as PDF documentation).

Setting up a Client-side SSL Connection to an LDAP Directory

To set up client-side SSL, you must provide a (file based) keystore containing the client’s certificate and private key and a (file-based) truststore containing the related CA certificates.

Setting up an SSL Connection to the Active Directory Domain Controller (DC)

Note: setting up this connection is not a trivial task and requires knowledge of the Microsoft Windows Active Directory. The following description contains some information from the Microsoft documentation. If you encounter any problems, please refer to the latest Microsoft documentation.

To establish the SSL connection:

1. Install a Certificate Authority on your Windows domain controller

Get the Microsoft documentation about "How to Install/Uninstall a Public Key Certificate Authority for Windows" and perform the steps described. Pay attention to the following issues:

During installation:

  • Choose to install an enterprise CA (not a stand-alone CA).

  • In the Certificate Authority Identifying Information window, you only need to enter the CA Name field: enter the name of your server, either in fully-qualified form, like kellner13.iam.mycompany.de, or just the first part, which is the server name short form. This value acts as the CN part of the DN composed automatically by the tool and shown in a field below. Check whether the composed DN contains the correct CN and DC parts conforming to your environment. A certificate containing this name will be created under a filename also containing this name.

  • Check the shared folder field and then specify a shared folder under which all configuration information for the CA is stored. Otherwise, all information - including generated root CA certificate - will be stored in Active Directory.

Possible errors during installation:

  • If the error message Provider could not perform the action since the context was acquired as silent. 0x80090022 (-2146893790) is logged, the cause is the policy System Cryptography: Force strong key protection for user keys stored on the computer under Control Panel\Administrative Tools\Local Security Policy\Local Policies\Security Options. If you change the default User must enter a password each time they use a key to User input is not required when new keys are stored and used, the installation runs successfully.

After installation:

  • You will find the root CA certificate under the shared folder you specified. This certificate is computer-related. You can copy it to any place in the network file system and import it to the truststore that is used by your client application. With this certificate, your client (in this case, the LDAP connector) can connect to this computer over SSL. If the client wants to establish an SSL connection with another computer in the Windows domain, this computer must be assigned another certificate, which must then also be imported into your truststore. Certificates can be automatically assigned by setting a group policy in Windows.

2. Import the certificate into your truststore

This section first describes how to import the certificate for Java clients into a Java truststore.

If you want to establish an SSL connection to the Active Directory Server with the C++-based ADS Agent, you must import the certificate into the Windows certification store; for example, with the Internet Explorer:

Menu Tools → Internet Options → Content → Certificates → Trusted Root Certification → Authorities → Import

You must also set the UseEncryption flag in the AdsAdmin bind profile of your Ads Connected Directory and you must specify the full qualified AD server name in the search base for export or in the ADsPath for import.

For Java clients:

Import the root CA certificate created by the CA installation into the truststore used by the LDAP connector (or your Java client) with the keytool.exe tool, which is part of the Java Runtime Environment (JRE). The certificate is to be imported to:

  • The truststore under the Java Development Kit (JDK) the LDAP connector runs with if it runs in an Integrated Development Environment (IDE) like Eclipse. For example, D:\java\lib\security\cacerts.

  • The truststore in the directory dxi_java_home*/lib/security/cacerts* if it runs in the DirX Identity environment under the Java-based Server.

Setting keytool command line parameters:

Depending on the environment the LDAP connector is supposed to run, change to the directory containing the cacerts store and copy the certificate file (and keytool.exe if you don’t want to specify the complete pathname in the command line) to it. Then call the keytool from the command prompt of the directory with the following parameters:

keytool -keystore storename -import -alias alias__name_ -file certfile_name

For example:

keytool -keystore cacerts -import -alias jupiter_cert -file jupiter_certorg.crt.

You are prompted for the password of the cacerts store, which is by default changeit.

To list the certificates in the cacerts store, call:

keytool -keystore cacerts -list

before and after you import your certificate.

To delete an old certificate in the store, call:

keytool -keystore cacerts -delete -alias jupiter_cert

Setting SSL trace parameters:

Setting the following debug parameter in your javac command line:

-Djavax.net.debug=all

will trace detailed SSL errors and messages, which helps you determine the reason if the SSL connection does not work. For example, the path of the key store in use is also traced, so you can see whether or not you imported the certificate into the right store.

Specifying a truststore:

If you explicitly specify a truststore in the javac command line, for example:

-Djavax.net.ssl.trustStore= D:\jdk\jre\lib\security\cacerts

this store is used.

Binary Attributes

To map binary attributes correctly between DirX Identity and a connected system (including a file system) specify the ;binary suffix only for attributes that contain an ASN.1 prefix in their binary data. These are the attributes with either the schema syntax Certificate, like the attribute userCertificate, or with the schema syntax CrossCertPair or CRL or similar. For attributes containing only raw binary data - without an ASN.1 prefix - which are those of schema syntax Octet String, specify the attribute name with the suffix ;raw in the mapping if it does not belong to the standard LDAP attribute schema. If it belongs to the standard schema - for example jpegPhoto - a suffix is not required but does not do any harm if specified. If you are not sure whether it belongs to the standard LDAP schema, you should specify the ;raw suffix. This is also true for Active Directory attributes with raw binary data. Consequently, if Active Directory is part of the workflow, those attributes - for example thumbnailPhoto - must also be specified with the ;raw suffix because the ADS connector is derived from the LDAP connector and inherits the functionality that interprets the suffix. The suffix - if required - must always be specified in both realtime mapping directions.

The LDAP connector knows the following (builtin) list of binary attributes:

"audio",
"authorityrevocationlist",
"cacertificate",
"certificaterevocationlist",
"consumerknowledge",
"crosscertificatepair",
"deltarevocationlist",
"entryaci",
"jpegphoto",
"mhsdeliverableclasses",
"mhsdlarchiveserv",
"mhsdlmembers",
"mhsdlpolicy",
"mhsdlsubscriptionserv",
"mhsoraddreswithcapabilities",
"ntsecurityidentifier",
"photo",
"prescriptiveaci",
"pwdhistory",
"queryoptimizerconfig",
"queryoptimizerstatistic",
"subentryaci",
"supportedalgs",
"usercertificate",
"userpassword",
"userpkcs12",
"usersmimecertificate"

Non-Leaf Objects

The LDAP Connector supports the deletion of non-leaf objects. Even though non-leaf objects are specific to Active Directory this feature is implemented in the LDAP Connector, because it is realized through the LDAP control LDAPAdsDeleteSubtreeControl. The LDAP connector manages all LDAP controls because any other LDAP Server can support them too.

Non-leaf objects in Active Directory are no container objects, like OUs, but objects that are usually expected to be leaf objects, like users. Nevertheless, sometimes these objects are non-leaf objects because they have subentries in certain cases. For example, Active Directory creates subentries for mailbox-enabled users in special situations. Those subentries are only shown by the "Active Directory Users and Computers" tool if the "Users, Contacts, Groups and Computers as containers" setting is checked in the View menu entry.

If such a non-leaf object is to be deleted the LDAP Connector - as parent class of the instantiated ADS Connector class - automatically deletes this object with all its subentries.

LDAP Session Tracking

Session tracking was introduced to improve LDAP audit logging. For each LDAP operation, it enables the user to identify the DirX Identity component, the directory user and the client address of the computer where DirX Identity is running.

If your DirX Directory installation supports the LDAP session tracking control the various DirX Identity components, like DirX Identity Manager, Web Center, Policy Agent, Provisioning or Request workflows and several more, extend the LDAP audit records with some session tracking related items. The three most important items are:

  • SID-Name, which contains the name of the invoking component,

  • SID-Info, which contains the DN of the bind user, and

  • SID-IP, which contains the IP address of the machine the component runs on.

The LDAP Connector supports session tracking the following way:

In the open method, the LDAP Connector checks if the property for the source component name, also referred to as source application name, is passed in the context. The context class consists of a lot of properties filled by the Connector framework in dependence on the context the LDAP Connector is instantiated from.

If the source application name is set in the context, the LDAP Connector creates an LDAP session tracking control (LDAPSessionIdentifierControl) with the source application name, the bind user DN and the computer name, and appends it to every subsequent LDAP operation (open, add, modify, delete and search). If the DirX LDAP Server supports the LDAP session tracking control it can be found afterwards inside the LDAP audit records.

For example, if a real-time provisioning workflow instantiated the LDAP Connector the source application name has the following format:

  • DXI {JoinFromDXI | JoinToDXI} workflowInstanceID workflowName,
    for example DXI JoinFromDXI 1495c804a6e$-724d Ident_ADS_Realtime.