Configuring Java CAPS Project Components for Communication Adapters

Configuring LDAP Adapter Connectivity Map Properties

The LDAP Adapter configuration parameters, accessed from the Connectivity Map, are organized into the following sections:

Connector Section Properties

The LDAP Adapter Connector Section Properties include the following parameters.

Table 56 LDAP Adapter— Connector Settings


Name	Description	Required Value
Connector Type	Lists the type of connector	The default is LDAP Connector.
Connector Class	Lists the Connector class.	The default connector class is com.stc.connector.ldapadapter.LDAPadapterConnection.

Where to Go Next

Connection Section Properties

Related Topics

Connection Section Properties

The LDAP Adapter Connection Section Properties allow you to define the connection to the LDAP system.

Table 57 LDAP Adapter— Connection Settings

Name

Description

Required Value

Authentication

Allows you to select the authentication to be used (none or simple). Select the desired authentication as follows:

None: No authentication, that is, an anonymous log-on. If you use this setting, ensure that the LDAP server supports anonymous log-ons.
Simple: Authentication is based on a user name and password. You must provide the user name and password in the appropriate fields (Principal and Credentials).

Select none or simple.

The default is none.

Credentials

Allows you to enter the credentials needed when using an authentication mechanism other than anonymous log-in (authentication = none).

The appropriate credentials, in the form of a valid password.

InitialContextFactory

Allows you to enter the factory to be used for creating the initial context for the LDAP server. By default the LDAP service provider provided by Sun, as part of the Java Software Developers’ Kit (SDK), is used.

A valid Java factory name; the default is:

com.sun.jndi.ldap.LdapCtxFactory.

It is recommended that you do not change this value unless you want to use an LDAP service provider other than the one provided by Sun.

Principal

Allows you to specify the principal needed when using an authentication mechanism other than anonymous log-in (authentication = none).

The fully qualified Distinguished Name (DN) of the user, for example:

CN=Administrator,CN=Users,
DC=stc,dc=com

ProviderURL

Allows you to specify the URL of the LDAP Server.

A valid URL with the protocol as ldap.

Where to Go Next

Referrals Section Properties

Related Topics

Referrals Section Properties

The LDAP Adapter Referrals Section Properties allow you to enter LDAP referral information.

Table 58 LDAP Adapter— Referrals Settings


Name	Description	Required Value
Credentials	Allows you to specify the credentials file to be used when following any referrals in the directory. The credentials file is created using the RCF command-line utility.	A valid file and path name available to the Service Bus.
Follow	Allows you to select whether referrals returned by an LDAP server must be followed.	Select Yes or No.. The default is Yes. Enter the desired value as follows: Yes: Follow referrals. No: Referrals are not followed.

Where to Go Next

Additional Referrals Section Notes

Related Topics

Additional Referrals Section Notes

Following are additional notes related to the properties found in the Referrals section.

A referral is an entity used to redirect a client’s request to another server. A referral contains the names and locations of other objects. It is sent by the server to indicate that the information the client has requested can be found at another location (or locations), possibly at another server or several servers.

When you execute a search operation, you may encounter a referral entry, which is just a pointer to where that information can be found. The pointer is usually in a form similar to the Provider URL configuration of the Adapter.

It consists of the following components:

Host name
Port number
Context name (optional)

You have the following options when you encounter a referral:

Ignore: Ignore the referral.
Follow: Follow the referral, that is, connect to the referred system and continue the search operation.
Throw: Throw a referral exception, which can be caught by the client and action taken as needed.

With the LDAP Adapter, you have the following properties you must set to work with referrals:

Credentials File: Enter a fully qualified path to a file. This file must contain the appropriate referral credentials information (this file has to be generated using the RCF command line utility as explained later in this section).
Follow: It is either Yes or No. Default is Yes.

The scenarios shown in the following table can arise depending on the properties provided for the referrals and the behavior of the Adapter, as explained for each of these scenarios.

Table 59 Referral Scenarios


Follow Setting	Credentials File	Adapter Operation
Follow is set to Yes.	The credentials file is not provided.	The Adapter uses the original credentials (user name and password) provided for the initial server and tries to connect to the referred system. The connection may fail if the referred system does not have the same credentials.
	The credentials file is provided and has the credentials entry for the referred host.	The connection to the initial server is configured to throw LdapReferralException when a referral is encountered which is subsequently caught by Adapter. The Adapter then establishes the connection to the referred system using the credentials information provided in the credentials file.
	The credentials file provided does not have the credentials entry for the referred host.	The connection to the initial server is configured to throw LdapReferralException when a referral is encountered, which is subsequently caught by the Adapter. The Adapter then establishes the connection to the referred system using an anonymous login. The connection may fail if the referred system does not allow an anonymous log-in.
Follow is set to No.	There is no credentials file.	Referrals are not followed, that is, the Adapter ignores any referral.

To create a credentials file, you can use the Referral Credentials File (RCF) command-line utility.

Note –

Running the RCF utility on the command line without any parameters displays how to use the utility.

To Create a Credentials File Using the RCF Utility

The file to be used for the RCF utility are located at the following locations:

netbeans_home\usrdir\modules\ext\ldapadapter\stcldap13.jar

<netbeans_home>\usrdir\modules\ext\ldapadapter\
stcldap14.jar

Copy and paste one of the above files to a folder and run the utility from this folder as follows:

netbeans_home\jdk\bin\java -cp ./stcldap13.jar
com.stc.connector.ldapadapter.utils.RCFUtil

The following menu displays:

C:\temp>java -cp ./stcldap13.jar
com.stc.connector.ldapadapter.utils.RCFUtil

Please specify the operation.

---+ RCFUtil +---

Interactive command line utility for creating and managing
file(s) containing credentials information to follow LDAP
referrals. File(s) generated can be used by the Java LDAP Adapter
for following referrals that required credentials different
from those used to create the connection to the initial LDAP
server.

Usage : java com.stc.connector.ldapadapter.utils.RCFUtilOPTIONS       -- <filename>

OPTIONS:

--create Create a new referral credentials file.
--add Add an entry to the referral credentials file.
--list Print a list of entries in the referral credentials file.
--remove Remove an entry from the referral credentials file.
--modify Modify an entry in the referral credentials file.
--decrypt When displaying credentials, decrypt the credentials.
--username <username>  Specify the username; if not specified,         
it’ll be prompted.
--password <password>  Specify the password; if not specified,         
it’ll be prompted.
--help Print this usage.

filename:

The full path to the referral credentials file.

To create a new referral file called samplercf.txt, enter the following parameters on the command line:

netbeans_home\jdk\bin\java -cp ./stcldap13.jar
com.stc.connector.ldapadapter.utils.RCFUtil --create -- samplercf.txt

This action requests a user name and password. Enter the user name and password. This user name and password is for protecting the file itself, because the file contains sensitive credential information about other LDAP servers. For example:

      C:\temp>c:\JavaCAPS6\netbeans\jdk\bin\java -cp .\stcldap13.jar       
com.stc.connector.ldapadapter.utils.RCFUtil
      --create -- samplercf.txt
      Creating file samplercf.txt...
      Enter username >> test
      Enter password >> test
      File created!

A message "File created!" appears. The file name here is samplercf.txt. The extension does not matter.

To Add Credentials Information To the File

To add LDAP Server connection info to a referral file called samplercf.txt, enter the following parameters on the command line:

      
netbeans_home\jdk\bin\java -cp ./stcldap13.jar
      com.stc.connector.ldapadapter.utils.RCFUtil --add --
       samplercf.txt

Username and Password are required to access the file. Provide the user name and password given for creating the file previously.

When the following prompts appear, enter the following information, as indicated:

Prompts for the host name: Enter the host name.

Prompts for the port number: Enter the LDAP port number.

Prompts for the principal: Enter the fully qualified DN of the user.

Prompts for the password: Enter the password for the DN specified previously.

For example:

      C:\temp>c:\JavaCAPS6\netbeans\jdk\bin\java -cp .\stcldap13.jar
       com.stc.connector.ldapadapter.utils.RCFUtil --add --
       samplercf.txt
      Adding a referral credentials entry...
      Enter username >> test
      Enter password >> test
      Enter LDAP Host >> localhost.stc.com
      Enter LDAP Port >> 389
      Enter the Principal >> cn=Manager,dc=stc,dc=com
      Enter the Credentials >> secret
      
      Done.

To View the Contents of the Credentials File

To view LDAP Server connection info in a referral file called samplercf.txt, enter the following parameters on the command line:

      <netbeans_home>\jdk\bin\java -cp ./stcldap13.jar
      com.stc.connector.ldapadapter.utils.RCFUtil --list --
       samplercf.txt

Username and Password are required to access the file. Provide the user name and password given for creating the file previously.

The entries in the file are listed as shown in the following single-entry example:

      1> localhost.stc.com | 389 | cn=Manager,dc=stc,dc=com | l/
      ZRt1cfNKc=

The password is encrypted. To display the password in its decrypted form add --decrypt to the previous command. The output is as follows:

      1> localhost.stc.com | 389 | cn=Manager,dc=stc,dc=com | secret

For example:

      C:\temp>c:\JavaCAPS6\netbeans\jdk\bin\java -cp .\stcldap13.jar
       com.stc.connector.ldapadapter.utils.RCFUtil --list --
       samplercf.txt
      Listing entries in the referral credentials file...
      Enter username >> test
      Enter password >> test
      1> localhost.stc.com | 389 | cn=Manager,dc=stc,dc=com | l/
      ZRt1cfNKc=
      
      C:\temp>c:\JavaCAPS6\netbeans\jdk\bin\java -cp .\stcldap13.jar
       com.stc.connector.ldapadapter.utils.RCFUtil --list --decrypt --
       samplercf.txt
      Listing entries in the referral credentials file...
      Enter username >> test
      Enter password >> test
      1> localhost.stc.com | 389 | cn=Manager,dc=stc,dc=com | secret

Other operations, such as removing a credential entry and modifying a credential entry for an entry, can be done using the RCF utility in the same way.

The following example shows the content of a credentials file, samplercf.txt, with explanatory comments:

      ###This properties file was generated by
      #com.stc.connector.ldapadapter.utils.RCFUtil.
      #Do NOT modify this file "by hand" if you don’t understand the
       nature
      #or format of this file. Use the utility to create and
      #manage this file.
      #
      #Tue Feb 14 17:49:17 PST 2006
      password=P9He6eCUY6Q\=
      localhost.stc.com\:389=test;P9He6eCUY6Q\=
      username=test
      #New credentials entry that was created.

Where to Go Next

Security/SSL Section Properties.

Related Topics

Security/SSL Section Properties

The LDAP Adapter Security/SSL Section Properties are used to set the basic security features for SSL.

Table 60 LDAP Adapter— Security/SSL Settings

Name

Description

Required Value

JSSE Provider Class

Specifies the fully qualified name of the JSSE provider class. For more information, see the Sun Microsystems Java site at:

http://java.sun.com

The name of a valid JSSE provider class; the default is:

com.sun.net.ssl.internal.ssl.Provider

If you are running the Integration Server on AIX, specify:

com.ibm.jsse.IBMJSSEProvider

KeyStore

Specifies the default KeyStore file. The keystore is used for key/certificate management when establishing SSL connections.

A valid package location. There is no default value. It is recommended to use

c:\JavaCAPS\appserver\is\domains
MyDomain
\config\keystore.jks

where,

c:\JavaCAPS
 is the directory where the 
Sun Java Composite 
Application Platform Suite 
is installed and 
MyDomain
 is the name of your domain.

KeyStore password

Specifies the default KeyStore password. The password is used to access the KeyStore used for key/certificate management when establishing SSL connections; there is no default.

A valid KeyStore password. There is no default value.

KeyStore type

Allows you to specify the default KeyStore type. The keystore type is used for key/certificate management when establishing SSL connections. If the KeyStore type is not specified, the default KeyStore type, JKS, is used.

A valid KeyStore type.

KeyStore username

The user name for accessing the keystore used for key/certificate management when establishing SSL connections.

Note –

If the keystore type is PKCS12 or JKS, the keystore user name property is not used. PKCS12 and JKS keystore types require passwords for access but do not require user names. If you enter a value for this property, it is ignored for PKCS12 and JKS.

A valid KeyStore user name.

SSL Connection Type

Allows you to specify the type of SSL connection to be used.

Select None, Enable SSL, or TLS On Demand.

Enter the desired value as follows:

None: No SSL, simple plain connection.
Enable SSL: SSL is enabled. All communication to the LDAP server uses a secure communication channel.

Note –

If you are using the Enable SSL option, the ProviderURL property must point to a secure LDAP port (the default is 636).

For additional information on required values for this property, see SSL Connection Type.

SSL Protocol

The SSL protocol to use when establishing an SSL connection with the LDAP server. See your JSSE documentation for information on your App Server’s platform.

Select TLS, TLSv1, SSLv3, SSLv2, or SSL.

TrustStore

Specifies the default TrustStore. The TrustStore is used for CA certificate management when establishing SSL connections.

A valid TrustStore file; there is no default.

TrustStore password

Allows you to specify the default TrustStore password. The password is for accessing the TrustStore used for CA certificate management when establishing SSL connections.

A valid TrustStore password; there is no default.

TrustStore type

Allows you to specify the TrustStore type of the TrustStore used for CA certificate management when establishing an SSL connection. If the TrustStore type is not specified, the default TrustStore type, JKS, is used.

A valid TrustStore type.

Verify hostname

Determines whether the host name verification is done on the server certificate during the SSL handshake.

You can use this property to enforce strict checking of the server host name in the request URL and the host name in the received server certificate.

Select True or False.

The default is False.

For additional information on required values for this property, see Verify hostname.

X509 Algorithm Name

Specifies the X509 algorithm name to use for the trust and key manager factories.

The name of a valid X509 algorithm; the default is SunX509. If you are running the Integration Server on AIX, specify IbmX509.

Where to Go Next

Additional Security/SSL Property Notes

Related Topics

Additional Security/SSL Property Notes

Listed are the additional notes for the following Security/SSL section properties:

SSL Connection Type

Make sure that the SSL properties, including security certificate installation, port number, and so on, are set correctly for the current LDAP server.

Transport Layer Security (TLS) is a protocol that guarantees privacy and data integrity between client/server applications communicating over the Internet. The TLS operation for this Adapter supports both secure and nonsecure communication on the same connection.

However, some LDAP servers are required to start on a configured nonsecure port and cannot start on a secure port. For details, see the appropriate documentation for the LDAP server.

TLS on Demand: A feature of LDAP version 3 (StartTLS extended operation), which is supported in Java SDK version 1.4 and later. Selecting this option allows you to establish an SSL connection on demand programmatically.

Note –
If you are using the TLS on Demand option, the ProviderURL property must point to a nonsecure LDAP port (the default is 389).

After selecting this option, whenever secure communication is required, you must place any method call to the LDAP server between startTLS and stopTLS calls, which can be accessed through the LDAP OTD.

In the following example, the call to performAddEntry goes through a secure communication channel, but the call to performRename goes through a nonsecure plain-communication channel:

   startTLS();
   performAddEntry();
   stopTLS();
   
   performRename();

Make sure that the TLS settings (in addition to the SSL settings) are configured correctly for the current LDAP server.

Note –

Using the stopTLS method may cause unexpected behavior with some LDAP servers. You may need to remove the use of this method in your Collaboration Definitions. For example, you cannot use the stopTLS method when connecting to a Sun ONE Directory server. For details, see the appropriate documentation for the LDAP server.

Active Directory does not release the context, when you iteratively add a single attribute with multiple values using TLS connection. But, with the workaround of starting the TLS, adding the attribute operations and then stopping the TLS will release the context.

For information on how to use this feature with the LDAP OTD, see TLSExtension Node.

Verify Hostname

Under some circumstances, you can get different Java exceptions, depending on whether you set this property to True or False. This section explains what causes these exceptions.

For example, suppose the host name in the URL is localhost, and the host name in the server certificate is localhost.stc.com. Then, the following conditions apply:

If Verify hostname is set to False:

Host name checking between the requested URL and the server certificate is turned off.

You can use an incomplete domain host name, for example, https://localhost:444, or a complete domain host name, for example, https://localhost.stc.com:444, and get a positive response in each case.
If Verify hostname is set to True:

Host name checking between the requested URL and the server certificate is turned on.

Note –
If you use an incomplete domain host name, for example, https://localhost:444, you can get the exception java.io.IOException: HTTPS hostname wrong.

You must use a complete domain host name, for example, https://localhost.stc.com:444.

Note –
If the Java SDK version used by the Application Server and the corresponding Application Server property setting do not match, you can get the exception java.lang.ClassCastException.

Where to Go Next

Configuring MSMQ Adapter Inbound Connectivity Map Properties.

Related Topics