Show Table of Contents
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
nsFarmServerURLattribute of one database link must contain the URL of the server containing another database link. Suppose the database link on the server calledexample1.compoints to a database link on the server calledafrica.example.com. For example, thecn=database_link,cn=chaining database,cn=plugins,cn=configentry 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=configentry 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
anonymousand pass a proxy authorization control allowing them more administrative privileges than appropriate. The proxy ACI prevents this security breach.- 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”.
- Create an entry that corresponds to the administrative user in the database.
- 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=configentry of each intermediate database link:nsCheckLocalACI: on
Setting this attribute toonin thecn=default instance config,cn=chaining database,cn=plugins,cn=configentry means that all new database link instances will have thensCheckLocalACIattribute set toonin theircn=database_link,cn=chaining database,cn=plugins,cn=configentry. - 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=comsuffix is chained to a remote server, all intermediate database links need to contain a database associated with thedc=example,dc=comsuffix.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 auidin thecn=configentry of Server 1 to perform any type of operation on the data below theou=people,dc=example,dc=comsuffix 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 table describes the attributes used to configure intermediate database links in a cascading chain:
Table 2.5. Cascading Chaining Configuration Attributes
| Attribute | Description |
|---|---|
| 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.12The first OID corresponds to the Proxy Authorization Control. The second OID corresponds to the Loop Detection Control. |
| 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
ldapmodifyand 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=comThe first section creates the entry associated withDBLink1. The second section creates a new suffix, allowing the server to direct requests made to the database link to the correct server. ThensCheckLocalACIattribute 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
nsTransmittedControlattribute stored incn=config,cn=chaining database,cn=plugins,cn=configentry 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 thensTransmittedControlattribute is usually configured by default with the loop detection control OID1.3.6.1.4.1.1466.29539.12value, 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 thensCheckLocalACIattribute toonto 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=configentry 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.12is the OID for the proxy authorization control.nsTransmittedControl: 1.3.6.1.4.1.1466.29539.12is 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=comsuffix, 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
DBLink2database link.
Both ACIs will be placed on the database that contains thec=africa,ou=people,dc=example,dc=comsuffix.Note
To create these ACIs, the database corresponding to thec=africa,ou=people,dc=example,dc=comsuffix must already exist to hold the entry. This database needs to be associated with a suffix above the suffix specified in thensslapd-suffixattribute 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.- Add the local proxy authorization ACI to the
c=africa,ou=people,dc=example,dc=comentry: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";) - 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=combranch. All users withinc=us,ou=people,dc=example,dc=commay need to have update access to the entries inl=Zanzibar,c=africa,ou=people,dc=example,dc=comon server three. Create the following ACI on Server 2 on thec=africa,ou=people,dc=example,dc=comsuffix 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 inc=us,ou=people,dc=example,dc=comon Server 1 to perform any type of operation on thel=Zanzibar,c=africa,ou=people,dc=example,dc=comsuffix 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=comentry: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 thel=Zanzibar,ou=people,dc=example,dc=comsubtree only. - Create a local client ACI on the
l=Zanzibar,ou=people,dc=example,dc=comsubtree 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.