JNDI Connector

The JNDI Connector provides access to a variety of JNDI services; it uses the javax.naming and javax.naming.directory packages to work with different directory services. To reach a specific system, install the JNDI driver for that system, for example com.sun.jndi.ldap.LdapCtxFactory for LDAP. The driver is typically distributed as one or more jar or zip files. Place these file in a place where the Java™ runtime can reach them, for example, in the TDI_install_dir/lib/ext directory.

This Connector supports Delta Tagging at the Attribute level. This means that provided a previous Connector in the AssemblyLine has provided Delta information at the Attribute level, the JNDI Connector will be able to use it in order to make the changes needed in the target JNDI directory.

When using the JNDI Connector for querying an LDAP Server, a SizeLimitExceededException may occur if the number of entries satisfying the search criteria is greater than the maximum limit set by the LDAP Server. To work around this situation, either increase the LDAP Server's maximum result limit, or set the java.naming.batchsize provider parameter to some value smaller than the maximum limit of the server. For more information on the java.naming.batchsize parameter refer to: http://java.sun.com/products/jndi/tutorial/ldap/search/batch.html

Configuration

The Connector needs the following parameters:

JNDI Driver

The class name (the JNDI Naming factory) for the JNDI driver.

Provider URL

The URL for the connection, for example, ldap://host for the LDAP driver.

Authentication Method

Type of LDAP authentication. Can be one of the following:

• Anonymous - If this authentication method is set then the server, to which a client is connected, does not know or care who the client is. The server allows such clients to access data configured for non-authenticated users. The Connector automatically specifies this authentication method if no username is supplied. However, if this type of authentication is chosen and Login username and Login password are supplied, then the Connector automatically sets the authentication method to Simple.

• Simple - using Login username and Login password. Treated as anonymous if Login username and Login password are not provided. Note that the Connector sends the fully qualified distinguished name and the client password in cleartext, unless you configure the Connector to communicate with the LDAP Server using the SSL protocol.

• CRAM-MD5 - This is one of the SASL authentication mechanisms. On connection, the LDAP Server sends some data to the LDAP client (that is, this Connector). Then the client sends an encrypted response, with password, using MD5 encryption. After that, the LDAP Server checks the password of the client. CRAM-MD5 is supported only by LDAP v3 servers. It is not supported against any supported versions of Tivoli Directory Server.

• SASL - The client (this Connector) will use a Simple Authentication and Security Layer (SASL) authentication method when connecting to the LDAP Server. Operational parameters for this type of authentication will need to be specified using the Extra Provider Parameters option; for example, in order to setup a DIGEST-MD5 authentication we will need to add the following parameter in the Extra Provider Parameters field:

  java.naming.security.authentication:DIGEST-MD5

  For more information on SASL authentication and parameters see: http://java.sun.com/products/jndi/tutorial/ldap/security/sasl.html.

  Not all directory servers support all SASL mechanisms and in some cases do not have them enabled by default. Check the documentation and configuration options for the directory server you are connecting to for this information.

Login username

The principal name (for example, username).

Login password

The credentials (for example, password).

Use SSL

Uses secure sockets layer for communication with LDAP server.

Name parameter

Specify which parameter in the AssemblyLine entry is used for naming the entry. This is used during add, modify and delete operations and returned during read or search operations. If not specified, $dn is used.

Search Base

The search base used when iterating the directory. Specify a distinguished name. Some directories enable you to specify a blank string which defaults to whatever the server is configured to do. Other directory services require this to be a valid distinguished name in the directory.

Search Filter

The search filter to be used when iterating the directory.

Search Scope

The search scope to be used when iterating the data source. Possible values are:

subtree

Return entries on all levels from search base and below.

onelevel

Only return entries that are immediately below searchbase.

Referrals

Specifies how referrals encountered by the LDAP server are to be processed. The possible values are:

• follow - Follow referrals automatically.

• ignore - Ignore referrals.

• throw - Throw a ReferralException when a referral is encountered. We need to handle this in an error Hook.

Extra Provider Parameters

A list of extra provider parameters we want to pass to the provider. Specify each parameter:value on a separate line. For example:

java.naming.batchsize=100

Detailed Log

If this parameter is checked, more detailed log messages are generated.

Setting the Modify operation

The JNDI connector has a way to set a modify operation value when the connector is in Modify mode. We can also use the simple connector interface to directly add, remove or replace attribute values and attributes instead of setting modify operation.

There is no Config Editor provided to set the modify operation. You must manually add the operation value to each attribute in the work entry of the JNDI connector in Modify mode using the following interface:

di.com.ibm.di.entry.Attribute.setOper(char operation) operation

di.com.ibm.di.entry.Attribute.ATTRIBUTE_DELETE

This constant deletes the specified attribute values from the attribute.

The resulting attribute has the set difference of its prior value set and the specified value set. If no values are specified, it deletes the entire attribute. If the attribute does not exist, or if some or all members of the specified value set do not exist, this absence might be ignored and the operation succeeds, or an Exception might be thrown to indicate the absence. Removal of the last value might remove the attribute if the attribute is required to have at least one value.

di.com.ibm.di.entry.Attribute.ATTRIBUTE_REPLACE

This constant replaces an attribute with specified values.

If the attribute already exists, this constant replaces all existing values with new specified values. If the attribute does not exist, this constant creates it. If no value is specified, this constant deletes all the values of the attribute. Removal of the last value might remove the attribute if the attribute is required to have at least one value. This is the default modify operation.

di.com.ibm.di.entry.Attribute.ATTRIBUTE_ADD

This constant adds an attribute with the specified values.

If the attribute does not exist, this constant creates the attribute. The resulting attribute has a union of the specified value set and the prior value set.

Calling the Modify Interface

Adding a value to an attribute

public void addAttributeValue(String moddn, String modattr, String modval)

throws Exception where:

• moddn is the DN to which we want to add the attribute value

• modattr is the name of the attribute to which we want to add a value

• modval is the value we want to add to modattr

For example, if we want to add "cn=bob" to the members attribute of "cn=mygroup" you use the method as such:

thisConnector.connector.addAttributeValue("cn=mygroup","members","cn=bob");

An Exception is thrown when the underlying modify operation fails.

Replacing the attribute value

public void replaceAttributeValue(String moddn, String modattr, String modval)

throws Exception where:

• moddn is the DN to which we want to add the attribute value

• modattr is the name of the attribute to which you wish to add a value

• modval is the value we want to add to modattr

For example, if we want to replace the members attribute of "cn=mygroup" with "cn=bob" only, we use the method as such:

thisConnector.connector.replaceAttributeValue("cn=mygroup","members","cn=bob");

An Exception is thrown when the underlying modify operation fails.

Removing attribute

public void removeAttribute(String moddn, String modattr)

throws Exception where:

• moddn is the DN from which we want to remove all attribute values

• modattr is the attribute name for which we want to remove all values

For example, if we want to remove the members attribute of "cn=mygroup" we use the method as such:

thisConnector.connector.removeAttribute("cn=mygroup","members");

An Exception is thrown when the underlying modify operation fails.

Removing a certain attribute value from an attribute

public void removeAttributeValue(String moddn, String modattr, String modval)

throws Exception where:

• moddn is the DN from which we want to remove the attribute value

• modattr is the attribute name that you want to change

• modval is the value we want to remove from given attribute

An Exception is thrown when the underlying modify operation fails.

modify operation

modify operation can be set per Modify request. It causes modify operation for all attributes in the modify request entry to be set to the proper modify operation value. Property values and matching modify operation values:

Property value (String)	modify operation value
delete	di.com.ibm.di.entry.Attribute. ATTRIBUTE_DELETE
add	di.com.ibm.di.entry.Attribute. ATTRIBUTE_ADD
replace	di.com.ibm.di.entry.Attribute. ATTRIBUTE_REPLACE

This property can be set at any time while the Connector is running by setting the property modOperation from the scripts:

conn.setProperty("modOperation","delete");

This property does not affect the behavior of the any interfaces defined above. However, it does overwrite the existing modify operation set by di.com.ibm.di.entry.Attribute.setOper(char operation)

Skip Lookup in Update and Delete mode

The JNDI Connector supports the Skip Lookup general option in Update or Delete mode. When it is selected, no search is performed prior to actual update and delete operations. It requires a name parameter (for example, $dn for LDAP) to be specified in order to operate properly.

See also

JNDI overview,
JNDI Tutorial,
JNDI FAQ,
LDAP Connector.