Sun Java System Directory Server Enterprise Edition 6.2 Administration Guide

Advanced Access Control: Using Macro ACIs

Organizations that use repeating directory tree structures can optimize the number of ACIs used in the directory by using macros. When you reduce the number of ACIs in your directory tree, it is easier to manage your access control policy. In addition, the efficiency of your ACI memory usage is improved.

Macros are placeholders that are used to represent a DN or a portion of a DN in an ACI. You can use a macro to represent a DN in the target portion of the ACI, in the bind rule portion, or in both. In practice, when Directory Server gets an incoming LDAP operation, the ACI macros are matched against the resource targeted by the LDAP operation. The matching occurs in order to determine a matching substring, if any matching substring exists. If a match exists, the bind rule-side macro is expanded using the matched substring, and access to the resource is determined by evaluating that expanded bind rule.

This section contains an example of a macro ACI and information about macro ACI syntax.

Macro ACI Example

The benefits of macro ACIs and how they work are best explained by using an example. Figure 6–1 shows a directory tree in which using macro ACIs is an effective way of reducing the overall number of ACIs.

In this illustration, note the repeating pattern of subdomains with the same tree structure (ou=groups,ou=people). This pattern is also repeated across the tree because the directory tree stores the two suffixes dc=hostedCompany2,dc=example,dc=com, and dc=hostedCompany3,dc=example,dc=com, which are not shown in the figure.

The ACIs in the directory tree also have a repeating pattern. For example, the following ACI is located on the dc=hostedCompany1,dc=example,dc=com node:

aci: (targetattr="*")
 (targetfilter=(objectClass=nsManagedDomain))(version 3.0;
 acl "Domain access"; allow (read,search) groupdn=

This ACI grants the domainAdmins group read and search rights to any entry in the dc=hostedCompany1,dc=example,dc=com tree.

Figure 6–1 Example Directory Tree for Macro ACIs

Topography of an example directory tree, showing dc=hostedcompany1,dc=example,dc=com,
and various subdomains.

The following ACI is located on the dc=hostedCompany1,dc=example,dc=com node:

aci: (targetattr="*")
 (version 3.0; acl "Domain access"; allow (read,search)

The following ACI is located on the dc=subdomain1,dc=hostedCompany1, dc=example,dc=com node:

aci: (targetattr="*")
 (version 3.0; acl "Domain access"; allow (read,search)

The following ACI is located on the dc=hostedCompany2,dc=example,dc=com node:

aci: (targetattr="*")
 (version 3.0; acl "Domain access"; allow (read,search)
 groupdn="ldap:///cn=DomainAdmins,ou=Groups,dc=hostedCompany2, dc=example,dc=com";)

The following ACI is located on the dc=subdomain1,dc=hostedCompany2, dc=example,dc=com node:

aci: (targetattr="*")
 (version 3.0; acl "Domain access"; allow (read,search)

In the preceding four ACIs, the only difference is the DN that is specified in the groupdn keyword. By using a macro for the DN, it is possible to replace these ACIs with a single ACI at the root of the tree, on the dc=example,dc=com node. This macro ACI reads as follows:

aci: (target="ldap:///ou=Groups,($dn),dc=example,dc=com")
 (version 3.0; acl "Domain access"; allow (read,search) 

Note that the target keyword which was not previously used needs to be introduced.

In the preceding example, the number of ACIs is reduced from four to one. However, the real benefit is a factor of how many repeating patterns you have down and across your directory tree.

Macro ACI Syntax

To simplify the discussion in this section, the ACI keywords such as userdn, roledn, groupdn, and userattr that are used to provide bind credentials are collectively called the subject of the ACI. The subject determines to whom the ACI applies.

The following table shows which macros can be used to replace specific ACI keywords.

Table 6–1 Macro ACI Keywords



ACI Keywords 


For matching in the target, and direct substitution in the subject. 

target, targetfilter, userdn, roledn, groupdn, userattr


For substituting multiple RDNs that work in subtrees of the subject. 

targetfilter, userdn, roledn, groupdn, userattr


For substituting the value of the attributeName attribute from the target entry into the subject.

userdn, roledn, groupdn, userattr

The following restrictions apply to macro ACI keywords:

Matching for ($dn) in the Target

The ($dn) macro in the target of an ACI determines the substitution value by comparing it to the entry targeted by the LDAP request. For example, you have an LDAP request targeted at this entry:

cn=all,ou=groups,dc=subdomain1, dc=hostedCompany1,dc=example,dc=com

In addition, you have an ACI that defines the target as follows:


The ($dn) macro matches with “dc=subdomain1, dc=hostedCompany1”. This substring is then used for substitutions in the subject of the ACI.

Substituting ($dn) in the Subject

In the subject of the ACI, the ($dn) macro is replaced by the entire substring that matches in the target. For example:


The subject becomes this:


After the macro has been expanded, Directory Server evaluates the ACI following the normal process to determine whether access is granted.

Note –

Unlike a standard ACI, an ACI that uses macro substitution does not necessarily grant access to the child of the targeted entry. This is because when the child DN is the target, the substitution might not create a valid DN in the subject string.

Substituting [$dn] in the Subject

The substitution mechanism for [$dn] is slightly different than for ($dn). The DN of the targeted resource is examined several times, each time dropping the left-most RDN component, until a match is found.

For example, suppose that you have an LDAP request targeted at the cn=all,ou=groups, dc=subdomain1,dc=hostedCompany1,dc=example,dc=com subtree, and the following ACI:

aci: (targetattr="*")
 (version 3.0; acl "Domain access"; allow (read,search)

    The server proceeds as follows to expand this ACI:

  1. The server verifies that the ($dn) in target matches dc=subdomain1,dc=hostedCompany1.

  2. The server replaces [$dn] in the subject with dc=subdomain1,dc=hostedCompany1.

    The resulting subject is groupdn="ldap:///cn=DomainAdmins,ou=Groups, dc=subdomain1,dc=hostedCompany1,dc=example,dc=com". If access is granted because the bind DN is a member of that group, the macro expansion stops, and the ACI is evaluated. If the bind DN is not a member, the process continues.

  3. The server replaces [$dn] in the subject with dc=hostedCompany1.

    The resulting subject is groupdn="ldap:///cn=DomainAdmins,ou=Groups, dc=hostedCompany1,dc=example,dc=com". Again, the bind DN is tested as a member of this group and if it is, the ACI is evaluated fully. If the bind DN is not a member, macro expansion stops with the last RDN of the matched value, and ACI evaluation is finished for this ACI.

The advantage of the [$dn] macro is that it provides a flexible way to grant domain-level administrators access to all the subdomains in the directory tree. Therefore, the [$dn] macro is useful for expressing a hierarchical relationship between domains.

For example, consider the following ACI:

aci: (target="ldap:///ou=*,($dn),dc=example,dc=com") (targetattr="*")
(version 3.0; acl "Domain access"; allow (read,search) groupdn= 

The ACI grants access to the members of cn=DomainAdmins,ou=Groups, dc=hostedCompany1,dc=example,dc=com to all of the subdomains under dc=hostedCompany1. Thus, an administrator who belongs to that group could access, for example, the subtree ou=people,dc=subdomain1.1,dc=subdomain1.

However, at the same time, members of cn=DomainAdmins,ou=Groups, dc=subdomain1.1 would be denied access to the ou=people,dc=subdomain1, dc=hostedCompany1 and ou=people,dc=hostedCompany1 nodes.

Macro Matching for ($attr.attrName)

The ($attr.attrname) macro is always used in the subject part of a DN. For example, you could define the following roledn:

roledn = "ldap:///cn=DomainAdmins,($attr.ou),dc=HostedCompany1,dc=example,dc=com"

Now, assume that the server receives an LDAP operation that is targeted at the following entry:

dn: cn=Babs Jensen,ou=People,dc=HostedCompany1,dc=example,dc=com
cn: Babs Jensen
sn: Jensen
ou: Sales

To evaluate the roledn part of the ACI, the server reads the value of the ou attribute stored in the targeted entry. The server then substitutes this value in the subject to expand the macro. In the example, the roledn is expanded as follows:

roledn = "ldap:///cn=DomainAdmins,ou=Sales,dc=HostedCompany1,dc=example,dc=com"

Directory Server then evaluates the ACI according to the normal ACI evaluation algorithm.

When the attribute that is named in the macro is multivalued, each value is used in turn to expand the macro. The first value that provides a successful match is used.