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.

Referral Scenarios

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

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

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

   or

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

2. 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.

3. 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

1. 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

2. Username and Password are required to access the file. Provide the user name and password given for creating the file previously.
3. When the following prompts appear, enter the following information, as indicated:
4. Prompts for the host name: Enter the host name.
5. Prompts for the port number: Enter the LDAP port number.
6. Prompts for the principal: Enter the fully qualified DN of the user.
7. 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

1. 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

2. Username and Password are required to access the file. Provide the user name and password given for creating the file previously.
3. 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=

4. 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

• About Configuring Java CAPS Adapter Connectivity Map Properties

• Configuring Java CAPS Project Components for Communication Adapters

• About Communication Adapters

• Designing with Communication Adapters

• Developing OTDs for Communication Adapters

• Configuring Java CAPS Environment Components for Communications Adapters