Because of the distributed nature of directory services, operations sent to an LDAP server often result in a referral to another LDAP server that might contain the requested data or entries.
When an LDAP server does not contain the requested data and a referral is necessary, eDirectory and your application can be configured to handle them in one of four ways.:
Configure eDirectory to return complete data and never referrals to the client (always chain).
Send referrals to the client only for eDirectory servers that do not support chaining.
Always send referrals to the client (never chain).
If the second or third option is selected and your application will recieve referrals from eDirectory, your application can be configured to have the API automatically follow referrals (anonymous by default or authenticated using a rebind process), or your application can perform its own manual referral handling.
In eDirectory, the LDAP server can be configured to return complete data and not return referrals. This is done through the LDAP Group Object using ConsoleOne. For possible configurations in e-Directory, see the documentation for the LDAP Group Object.
The LDAP server in eDirectory can also be configured to return referrals to your application. This is done through the LDAP Group Object using ConsoleOne. For possible configurations in Novell e-Directory, see the documentation for the LDAP Group Object
The LDAP Libraries for C are initially set up to automatically follow referrals. This feature is controlled through the LDAP_OPT_REFERRALS option in the ld session handle.
When set to ON (the default value), the libraries follow the referrals and perform an anonymous bind to the referred servers. In eDirectory, this bind is equivalent to the [Public] user and grants minimal rights to entries in the directory.
If you want your application to follow referrals but to perform a stronger authentication than an anonymous bind, you must supply a rebind process (see Creating a Rebind Process).
When set to OFF, the libraries return LDAP_REFERRAL status (10) on LDAP operations and continuation references on search operations as part of the search results. When you recieve LDAP_REFERRAL status the referrals can be retrieved using ldap_get_option and specifying LDAP_OPT_REFERRAL_LIST as the requested value. This returns a NULL-terminated list of string pointers containing the referrals.
HINT:To change the setting of the LDAP_OPT_REFERRALS option, call the ldap_set_option function with the option parameter set to LDAP_OPT_REFERRALS (see ldap_set_option).
The rebind function must use the following syntax.
int LIBCALL rebind_function (
LDAP *ld,
const char *url,
int request,
ber_int_t msgid)
{
/* the body must perform a synchronous bind */
}
The ld parameter must be used by the application to bind to the referred server if the application wants the libraries to follow the referral.
The url parameter points to the URL referral string received from the LDAP server. The LDAP application can use the ldap_url_parse function to parse the string into its components.
The request parameter specifies the request operation that generated the referral. For possible values, see Section 6.8, Request Message Types.
The msgid parameter specifies the message ID of the request generating the referral.
The libraries set all the parameters when they call the rebind function. The application should not attempt to free either the ld or the url structures in the rebind function.
The application is responsible for obtaining the required authentication information (user name, password, and certificates) associated with the ld and passing this information to the rebind function. The rebind function is responsible for performing the synchronous bind.
You must design your application to handle the possibility that the rebind process cannot bind to any of the referrals (for examle, the servers are down or the authentication information is invalid). When this happens, the LDAP libraries return either
results with referrals
search results with search references
For the libraries to use a rebind process, the application must configure the ld to the following values:
LDAP_OPT_REFERRALS option must be set to ON (the default value). For configuration information, see ldap_set_option.
LDAP_REBIND_PROC must be set to the rebind function (see ldap_set_rebind_proc).
When the ld has the proper settings, the referrals are processed according to the following algorithm.
The LDAP server sends a referral back to the libraries.
The libraries call the rebind function, setting the ld and url parameters.
The application supplies the logic for determining the type of bind.
For example, if the referral is to a server outside of a firewall, the application could decide to do an anonymous bind rather than a secure bind.
The application supplies the bind credentials associated with the ld (user name, password, and certificates) and with the bind method (such as simple, SSL, or SASL)
The libraries process the rebind function. If successful, the rebind function returns LDAP_SUCCESS.
If any other value is returned, the referral process stops and either LDAP_REFERRAL is returned as a result code for the original LDAP operation, or if a search operation, a search continuation is returned with the search results.
When eDirectory is configured to return referrals and automatic referral handling is turned off in your application, the libraries return LDAP_REFERRAL status (10) on LDAP operations and continuation references on search operations as part of the search results. When you recieve LDAP_REFERRAL status, referrals can be retrieved using ldap_get_option and specifying LDAP_OPT_REFERRALS as the requested value. This returns a NULL-terminated list of string pointers containing the referrals.
If a referral is returned with no DN field, the library inserts the DN of the original request in the referral before returning it.
Your application can then determine how to handle each returned referral.
eDirectory 8.7 can return referrals for non-search operations. See Enabling Referral Handling in the Application for details on handling these referrals.
Your application can specify the maximum number of referral hops the LDAP libraries will follow. For example, suppose you set the limit to two. Your application does a search, and the search refers you to the following:
The libraries will follow the referral through Server 3, but they will not continue to Server 4 because Server 4 exceeds the hop limit of 2. They return an result code of LDAP_REFERRAL_LIMIT_EXCEEDED.
To set the referral hop limit, call the ldap_set_option function with the option parameter set to LDAP_OPT_REFERRAL_HOP_LIMIT (see ldap_set_option).