Chapter 7.4 Referrals

Referral is the process by which an LDAP server, instead of returning a result will return a reference (a referral) to another LDAP server which may contain further information. OpenLDAP documentation confusingly uses the terms superior and subordinate in the context of referrals. The conditions under which OpenLDAP will return a referral are covered in this section:

1. Using a generic referral returned where the DN of a search filter does not exist in any suffix directive of the LDAP server. This feature is configured using the referral directive in the global section of slapd.conf. More Info.

2. If a client attempts to update a slave (or consumer) DIT the server can be configured to return a referral using the updateref directive in the database section of slapd.conf. More Info.

3. Use of the referral ObjectClass within a DIT. This allows for delegation of responsibity for parts of an LDAP system to one or more other LDAP systems. More Info.

4. Configuring LDAP servers to follow (or chase) referral objectclass definitions rather than simply returning a referral. This feature uses the overlay chain directive. More Info.

7.4.1 Generic Referrals

If an LDAP client issues a request to an LDAP server with an invalid DN (the base of the DN does not exist in any suffix directive for the server) then it will return an error. The server can be configured to return a referral (an LDAP URI) to one or more servers which may be able to provide further services. This feature is defined using the referral directive in the global section of slapd.conf as shown in the follwing examples:

# sladp.conf
# global section
...
# if the server receives a search for a DN
# which does not exist in any suffix directive 
# for any database section it will return both LDAP URI's
# in this example case the DN does not terminate
# with dc=example,dc=net
referral ldap://ldap-master.example.com
referral ldap://ldap-services.example.com:10389
...
# databases section(s)
database bdb
...
suffix "dc=example,dc=net"
...

7.4.2 Slave (Consumer) Modify Referrals

If an LDAP client issues a write (modify) request to a slurpd slave or a syncrepl consumer it will be rejected. The server may be configured to supply a referral (an LDAP URI) that would typically point to the replication master or provider as shown in the following example:

# sladp.conf slave or consumer
# global section
...
...
# database section(s)
database bdb
...
# updatedn directive (for slurpd style replication)
# OR
# syncrepl directive

# refer to the DIT master (provider) server
updateref ldap://ldap-master.example.com
...

7.4.3 Referral Objects

Referrals may be explicitly defined in a DIT using the referral ObjectClass. This object class takes a single ref attribute (a LDAP URI).

To illustrate this process assume Figure 7.4-1 illustrates a delegated or referral based LDAP system:

Figure 7.4-1 - Referrals to LDAP2 and LDAP3

To define the referral in LDAP1 -> LDAP2 the following LDIF definition is used:

# definition creates o=grommets RDN
# and refers it to ldap2
dn: o=grommets,dc=example,dc=com
objectClass: referral
objectClass: extensibleObject
o: grommets
ref: ldap://ldap2.example.com/o=grommets,dc=example,dc=net

Notes:

1. The extensibleObject objectClass allows any attribute (in this case o (organizationName) to be added to the referral objectClass.

2. A referral to LDAP2 will be returned (or followed) if LDAP1.example.com receives a search DN for:

   cn=cheri,ou=uk,o=grommets,dc=example,dc=com
   

To define the referral LDAP2 -> LDAP3 the following LDIF definition is used:

# an organizationalUnit objectClass (entry) with an 
# attribute of organizationName (o) of grommets must be 
# defined in this server
# or the LDAP2 suffix is defined as o=grommets,dc=examnple,dc=com

# definition creates ou=uk RDN
# and refers it to ldap3
dn: ou=uk,o=grommets,dc=example,dc=com
objectClass: referral
objectClass: extensibleObject
ou: uk
ref: ldap://ldap3.example.com/ou=uk,o=grommets,dc=example,dc=net

Notes:

1. The extensibleObject objectClass allows any attribute (in this case o (organizationName) to be added to the referral objectClass.

2. A referral to LDAP2 will be returned (or followed) if LDAP1.example.com receives a search DN for:

   cn=cheri,ou=uk,o=grommets,dc=example,dc=com
   

7.4.4 Referral Chaining

In the normal case if an LDAP server encounters a referral object on the search path it will return a referral to the LDAP client. In the case where it is required the server may be configured to follow (or chase) referrals and return a complete result to the user. This process is frequently called chaining and is configured in the server through the use on the overlay chain directive. Figure 7.4-2 show chaining and referral:

Figure 7.4-2 - Chaining to LDAP2 and LDAP3

The following example illustrates the configuration required at LDAP1 to chain (or follow) the two referrals shown in Figure 7.4-2: Full configuration information about the chain overlay).

# sladp.conf 
# global section
...
# generic referral for invalid DN cases
referral ldap:ldap-master.example.com
...
# databases section(s)
database bdb
...
suffix "dc=example,dc=com"
...

overlay chain
# allow two referrals - one in this DIT 
# and a second in the referral DIT
chain-max-depth 2
# return a referral in the case of an error
chain-return-error FALSE


overlay	chain
chain-uri "ldap://ldap2.example.com"
chain-rebind-as-user yes
chain-idassert-bind bindmethod="simple"
 binddn="cn=admin,dc=example,dc=com"
 credentials="secret"
 mode="self"
chain-uri "ldap://ldap3.example.com"
chain-rebind-as-user yes
chain-idassert-bind bindmethod="simple"
 binddn="cn=admin,dc=example,dc=com"
 credentials="secret"
 mode="self"