2.4. Configuring Cascading Chaining

The database link can be configured to point to another database link, creating a cascading chaining operation. A cascading chain occurs any time more than one hop is required to access all of the data in a directory tree.

2.4.1. Overview of Cascading Chaining

Cascading chaining occurs when more than one hop is required for the directory to process a client application's request.

The client application sends a modify request to Server 1. Server one contains a database link that forwards the operation to Server 2, which contains another database link. The database link on Server 2 forwards the operations to server three, which contains the data the clients wants to modify in a database. Two hops are required to access the piece of data the client want to modify.

During a normal operation request, a client binds to the server, and then any ACIs applying to that client are evaluated. With cascading chaining, the client bind request is evaluated on Server 1, but the ACIs applying to the client are evaluated only after the request has been chained to the destination server, in the above example Server 2.

For example, on Server A, a directory tree is split:

The root suffix dc=example,dc=comand the ou=people and ou=groups sub suffixes are stored on Server A. The l=europe,dc=example,dc=com and ou=groups suffixes are stored in on Server B, and the ou=people branch of the l=europe,dc=example,dc=com suffix is stored on Server C.

With cascading configured on servers A, B, and C, a client request targeted at the ou=people,l=europe,dc=example,dc=com entry would be routed by the directory as follows:

First, the client binds to Server A and chains to Server B using Database Link 1. Then Server B chains to the target database on Server C using Database Link 2 to access the data in the ou=people,l=europe,dc=example,dc=com branch. Because at least two hops are required for the directory to service the client request, this is considered a cascading chain.

2.4.2. Configuring Cascading Chaining Using the Console

Select the Configuration tab. Expand the Data folder in the left pane, and select the suffix, then the database link.
Click the Limits and Controls tab in the right navigation pane.
Select the Check local ACI check box to enable the evaluation of local ACIs on the intermediate database links involved in the cascading chain. Selecting this check box may require adding the appropriate local ACIs to the database link.
Enter the maximum number of times a database link can point to another database link in the Maximum hops field.
By default, the maximum is ten hops. After ten hops, a loop is detected by the server, and an error is returned to the client application.

2.4.3. Configuring Cascading Chaining from the Command Line

To configure a cascade of database links through the command line:

Point one database link to the URL of the server containing the intermediate database link.
To create a cascading chain, the nsFarmServerURL attribute of one database link must contain the URL of the server containing another database link. Suppose the database link on the server called example1.com points to a database link on the server called africa.example.com. For example, the cn=database_link, cn=chaining database,cn=plugins,cn=config entry of the database link on Server 1 would contain the following:
```
nsFarmServerURL: ldap://africa.example.com:389/
```
Configure the intermediate database link or links (in the example, Server 2) to transmit the Proxy Authorization Control.
By default, a database link does not transmit the Proxy Authorization Control. However, when one database link contacts another, this control is used to transmit information needed by the final destination server. The intermediate database link needs to transmit this control. To configure the database link to transmit the proxy authorization control, add the following to the cn=config,cn=chaining database,cn=plugins,cn=config entry of the intermediate database link:
```
nsTransmittedControls: 2.16.840.1.113730.3.4.12
```
The OID value represents the Proxy Authorization Control. For more information about chaining LDAP controls, see Section 2.3.2.2, “Chaining LDAP Controls”.
Create a proxy administrative user ACI on all intermediate database links.
The ACI must exist on the server that contains the intermediate database link that checks the rights of the first database link before translating the request to another server. For example, if Server 2 does not check the credentials of Server 1, then anyone could bind as anonymous and pass a proxy authorization control allowing them more administrative privileges than appropriate. The proxy ACI prevents this security breach.
1. Create a database, if one does not already exist, on the server containing the intermediate database link. This database will contain the admin user entry and the ACI. For information about creating a database, see Section 2.2.1, “Creating Databases”.
2. Create an entry that corresponds to the administrative user in the database.
3. Create an ACI for the administrative user that targets the appropriate suffix. This ensures the administrator has access only to the suffix of the database link. For example:
```
aci: (targetattr = "*")(version 3.0; acl "Proxied authorization for database links";
      allow (proxy) userdn = "ldap:///cn=proxy admin,cn=config";)
```
  This ACI is like the ACI created on the remote server when configuring simple chaining.
Warning
Carefully examine access controls when enabling chaining to avoid giving access to restricted areas of the directory. For example, if a default proxy ACI is created on a branch, the users that connect through the database link will be able to see all entries below the branch. There may be cases when not all of the subtrees should be viewed by a user. To avoid a security hole, create an additional ACI to restrict access to the subtree.
Enable local ACI evaluation on all intermediate database links.
To confirm that the proxy administrative ACI is used, enable evaluation of local ACIs on all intermediate database links involved in chaining. Add the following attribute to the cn=database_link, cn=chaining database,cn=plugins,cn=config entry of each intermediate database link:
```
nsCheckLocalACI: on
```
Setting this attribute to on in the cn=default instance config,cn=chaining database,cn=plugins,cn=config entry means that all new database link instances will have the nsCheckLocalACI attribute set to on in their cn=database_link, cn=chaining database,cn=plugins,cn=config entry.
Create client ACIs on all intermediate database links and the final destination database.
Because local ACI evaluation is enabled, the appropriate client application ACIs must be created on all intermediate database links, as well as the final destination database. To do this on the intermediate database links, first create a database that contains a suffix that represents a root suffix of the final destination suffix.
For example, if a client request made to the c=africa,ou=people,dc=example,dc=com suffix is chained to a remote server, all intermediate database links need to contain a database associated with the dc=example,dc=com suffix.
Add any client ACIs to this superior suffix entry. For example:
```
aci: (targetattr = "*")(version 3.0; acl "Client authentication for database link users";
      allow (all) userdn = "ldap:///uid=* ,cn=config";)
```
This ACI allows client applications that have a uid in the cn=config entry of Server 1 to perform any type of operation on the data below the ou=people,dc=example,dc=com suffix on server three.

2.4.4. Detecting Loops

An LDAP control included with Directory Server prevents loops. When first attempting to chain, the server sets this control to be the maximum number of hops, or chaining connections, allowed. Each subsequent server decrements the count. If a server receives a count of 0, it determines that a loop has been detected and notifies the client application.

The number of hops allowed is defined using the nsHopLimit attribute. If not specified, the default value is 10.

To use the control, add the following OID to the nsTransmittedControl attribute in the cn=config,cn=chaining database,cn=plugins,cn=config entry:

nsTransmittedControl: 1.3.6.1.4.1.1466.29539.12

If the control is not present in the configuration file of each database link, loop detection will not be implemented.

2.4.5. Summary of Cascading Chaining Configuration Attributes

The following describes the attributes used to configure intermediate database links in a cascading chain:

nsFarmServerURL

URL of the server containing the next database link in the cascading chain.

nsTransmittedControls

Enter the following OIDs to the database links involved in the cascading chain:

nsTransmittedControls: 2.16.840.1.113730.3.4.12
nsTransmittedControls: 1.3.6.1.4.1.1466.29539.12

aci

This attribute must contain the following ACI:

aci: (targetattr = "*")(version 3.0; acl "Proxied
 authorization for database links";
 allow (proxy) userdn = "ldap:///cn=proxy admin,cn=config";)

nsCheckLocalACI

To enable evaluation of local ACIs on all database links involved in chaining, turn local ACI evaluation on, as follows:

nsCheckLocalACI: on

2.4.6. Cascading Chaining Configuration Example

To create a cascading chain involving three servers as in the diagram below, the chaining components must be configured on all three servers.

2.4.6.1. Configuring Server One

Run ldapmodify and specify the configuration information for the database link, DBLink1, on Server 1:

# ldapmodify -a -D "cn=Directory Manager" -W -p 389 -h server.example.com -x

dn: cn=DBLink1,cn=chaining database,cn=plugins,cn=config
changetype: add
objectclass: top
objectclass: extensibleObject
objectclass: nsBackendInstance
nsslapd-suffix: c=africa,ou=people,dc=example,dc=com
nsfarmserverurl: ldap://africa.example.com:389/
nsMultiplexorBindDN: cn=server1 proxy admin,cn=config
nsMultiplexorCredentials: secret
cn: DBLink1
nsCheckLocalACI:off

dn: cn="c=africa,ou=people,dc=example,dc=com",cn=mapping tree,cn=config
changetype: add
objectclass: nsMappingTree
nsslapd-state: backend
nsslapd-backend: DBLink1
nsslapd-parent-suffix: ou=people,dc=example,dc=com
cn: c=africa,ou=people,dc=example,dc=com

The first section creates the entry associated with DBLink1. The second section creates a new suffix, allowing the server to direct requests made to the database link to the correct server. The nsCheckLocalACI attribute does not need to be configured to check local ACIs, as this is only required on the database link, DBLink2, on Server 2.

To implement loop detection, to specify the OID of the loop detection control in the nsTransmittedControl attribute stored in cn=config,cn=chaining database,cn=plugins,cn=config entry on Server 1.
```
dn: cn=config,cn=chaining database,cn=plugins,cn=config
changetype: modify
add: nsTransmittedControl
nsTransmittedControl: 1.3.6.1.4.1.1466.29539.12
```
As the nsTransmittedControl attribute is usually configured by default with the loop detection control OID 1.3.6.1.4.1.1466.29539.12 value, it is wise to check beforehand whether it already exists. If it does exist, this step is not necessary.

2.4.6.2. Configuring Server Two

Create a proxy administrative user on Server 2. This administrative user will be used to allow Server 1 to bind and authenticate to Server 2. It is useful to choose a proxy administrative user name which is specific to Server 1, as it is the proxy administrative user which will allow server one to bind to Server 2. Create the proxy administrative user, as follows:
```
dn: cn=server1 proxy admin,cn=config
objectclass: person
objectclass: organizationalPerson
objectclass: inetOrgPerson
cn: server1 proxy admin
sn: server1 proxy admin
userPassword: secret
description: Entry for use by database links
```
Warning
Do not use the Directory Manager or Administrator ID user as the proxy administrative user on the remote server. This creates a security hole.

Configure the database link, DBLink2, on Server 2:

dn: cn=DBLink2,cn=chaining database,cn=plugins,cn=config
objectclass: top
objectclass: extensibleObject
objectclass: nsBackendInstance
nsslapd-suffix: l=Zanzibar,c=africa,ou=people,dc=example,dc=com
nsfarmserverurl: ldap://zanz.africa.example.com:389/
nsMultiplexorBindDN: cn=server2 proxy admin,cn=config
nsMultiplexorCredentials: secret
cn: DBLink2
nsCheckLocalACI:on

dn: cn="l=Zanzibar,c=africa,ou=people,dc=example,dc=com",cn=mapping tree,cn=config
objectclass: top
objectclass: extensibleObject
objectclass: nsMappingTree
nsslapd-state: backend
nsslapd-backend: DBLink2
nsslapd-parent-suffix: c=africa,ou=people,dc=example,dc=com
cn: l=Zanzibar,c=africa,ou=people,dc=example,dc=com

Since database link DBLink2 is the intermediate database link in the cascading chaining configuration, set the nsCheckLocalACI attribute to on to allow the server to check whether it should allow the client and proxy administrative user access to the database link.

The database link on Server 2 must be configured to transmit the proxy authorization control and the loop detection control. To implement the proxy authorization control and the loop detection control, specify both corresponding OIDs. Add the following information to the cn=config,cn=chaining database,cn=plugins,cn=config entry on Server 2:
```
dn: cn=config,cn=chaining database,cn=plugins,cn=config
changetype: modify
add: nsTransmittedControl
nsTransmittedControl: 2.16.840.1.113730.3.4.12
nsTransmittedControl: 1.3.6.1.4.1.1466.29539.12
```
nsTransmittedControl: 2.16.840.1.113730.3.4.12 is the OID for the proxy authorization control. nsTransmittedControl: 1.3.6.1.4.1.1466.29539.12 is the or the loop detection control.
Check beforehand whether the loop detection control is already configured, and adapt the above command accordingly.
Configure the ACIs. On Server 2, ensure that a suffix exists above the l=Zanzibar,c=africa,ou=people,dc=example,dc=com suffix, so that the following actions are possible:
- Add the database link suffix
- Add a local proxy authorization ACI to allow Server 1 to connect using the proxy authorization administrative user created on Server 2
- Add a local client ACI so the client operation succeeds on Server 2, and it can be forwarded to server three. This local ACI is needed because local ACI checking is turned on for the DBLink2 database link.
Both ACIs will be placed on the database that contains the c=africa,ou=people,dc=example,dc=com suffix.
Note
To create these ACIs, the database corresponding to the c=africa,ou=people,dc=example,dc=com suffix must already exist to hold the entry. This database needs to be associated with a suffix above the suffix specified in the nsslapd-suffix attribute of each database link. That is, the suffix on the final destination server should be a sub suffix of the suffix specified on the intermediate server.
1. Add the local proxy authorization ACI to the c=africa,ou=people,dc=example,dc=com entry:
```
aci:(targetattr="*")(target="l=Zanzibar,c=africa,ou=people,dc=example,dc=com")
     (version 3.0; acl "Proxied authorization for database links"; allow (proxy)
     userdn = "ldap:///cn=server1 proxy admin,cn=config";)
```
2. Then add the local client ACI that will allow the client operation to succeed on Server 2, given that ACI checking is turned on. This ACI is the same as the ACI created on the destination server to provide access to the l=Zanzibar,c=africa,ou=people,dc=example,dc=com branch. All users within c=us,ou=people,dc=example,dc=com may need to have update access to the entries in l=Zanzibar,c=africa,ou=people,dc=example,dc=com on server three. Create the following ACI on Server 2 on the c=africa,ou=people,dc=example,dc=com suffix to allow this:
```
aci:(targetattr="*")(target="l=Zanzibar,c=africa,ou=people,dc=example,dc=com")
     (version 3.0; acl "Client authorization for database links"; allow (all)
     userdn = "ldap:///uid=*,c=us,ou=people,dc=example,dc=com";)
```
  This ACI allows clients that have a UID in c=us,ou=people,dc=example,dc=com on Server 1 to perform any type of operation on the l=Zanzibar,c=africa,ou=people,dc=example,dc=com suffix tree on server three. If there are users on Server 2 under a different suffix that will require additional rights on server three, it may be necessary to add additional client ACIs on Server 2.

2.4.6.3. Configuring Server Three

Create an administrative user on server three for Server 2 to use for proxy authorization:

dn: cn=server2 proxy admin,cn=config
objectclass: person
objectclass: organizationalPerson
objectclass: inetOrgPerson
cn: server2 proxy admin
sn: server2 proxy admin
userPassword: secret
description: Entry for use by database links

Then add the same local proxy authorization ACI to server three as on Server 2. Add the following proxy authorization ACI to the l=Zanzibar,ou=people,dc=example,dc=com entry:
```
aci: (targetattr = "*")(version 3.0; acl "Proxied authorization
     for database links"; allow (proxy) userdn = "ldap:///cn=server2
     proxy admin,cn=config";)
```
This ACI gives the Server 2 proxy admin read-only access to the data contained on the remote server, server three, within the l=Zanzibar,ou=people,dc=example,dc=com subtree only.

Create a local client ACI on the l=Zanzibar,ou=people,dc=example,dc=com subtree that corresponds to the original client application. Use the same ACI as the one created for the client on Server 2:

aci: (targetattr ="*")(target="l=Zanzibar,c=africa,ou=people,dc=example,dc=com")
     (version 3.0; acl "Client authentication for database link users"; allow (all)
     userdn = "ldap:///uid=*,c=us,ou=people,dc=example,dc=com";)

The cascading chaining configuration is now set up. This cascading configuration allows a user to bind to Server 1 and modify information in the l=Zanzibar,c=africa,ou=people,dc=example,dc=com branch on server three. Depending on your security needs, it may be necessary to provide more detailed access control.

Where did the comment section go?

Red Hat's documentation publication system recently went through an upgrade to enable speedier, more mobile-friendly content. We decided to re-evaluate our commenting platform to ensure that it meets your expectations and serves as an optimal feedback mechanism. During this redesign, we invite your input on providing feedback on Red Hat documentation via the discussion platform.

Log in to Your Red Hat Account

Red Hat Account

Customer Portal

Select Your Language

Infrastructure and Management

Cloud Computing

Storage

JBoss Development and Management

JBoss Integration and Automation

Mobile

Services

Tools

Red Hat Insights

Red Hat Product Security Center

Security Updates

Resources

Customer Portal Community

Customer Events

Stories