Working with targets

The following section presents a detailed look and examples of the target access control instruction (ACI) keywords:

target
targetattr
targetfilter
targattrfilters
targetscope
targetcontrol
extop

target

The target keyword indicates that the ACI should apply to one or more entries at or below the specified distinguished name (DN).

The target DN must be equal or subordinate to the DN of the entry in which the ACI is placed. For example, if you place the ACI at the root of ou=People,dc=example,dc=com, you can target the DN, uid=user.1,ou=People,dc=example,dc=com, within your ACI rule. The DN must meet the string representation specification of distinguished names, outlined in RFC 4514, and requires that special characters be properly escaped.

The target clause has the following format, where DN is the distinguished name of the entry or branch:

(target = ldap:///<DN>)

For example, to target a specific entry, use a clause like the following.

(target = ldap:///uid=john.doe,ou=People,dc=example,dc=com)

In most cases, you should avoid specifying a target DN. Instead, define the ACI in that entry and omit the target element altogether.

For example, although you can have (target="ldap:///uid=john.doe,ou=People,dc=example,dc=com) in any of the dc=example,dc=com or ou=People entries, you should define it in the uid=john.doe entry and not explicitly include the target element.

The expression allows for the not equal operator (!=) to indicate that all entries within the scope of the given branch that do not match the expression be targeted for the ACI. The following expression targets all entries within the subtree that do not match uid=john.doe.

(target != ldap:///uid=john.doe,ou=People,dc=example,dc=com)

The target keyword also supports the use of asterisk (*) characters as wildcards to match elements within the distinguished name.

The following target expression matches all entries that contain and begin with john.d.
```
(target = ldap:///uid=john.d*,ou=People,dc=example,dc=com)
```
Entries such as john.doe,ou=People,dc=example,dc=com and john.davies,ou=People,dc=example,dc=com would match the target expression.
The following target expression matches all entries whose DN begins with john.d and matches the ou attribute.
```
(target = ldap:///uid=john.d*,ou=*,dc=example,dc=com)
```
Entries such as john.doe,ou=People,dc=example,dc=com and john.davies,ou=asia-branch,dc=example,dc=com would match the target expression.

Another example of a complete ACI targets the entries in the ou=People,dc=example,dc=com branch and the entries below it and grants the users the privilege to modify all of their user attributes within their own entries.

aci:(target="ldap:///ou=People,dc=example,dc=com")
(targetattr="*")
(version 3.0; acl "Allow all the ou=People branch to modify their own entries";
allow (write) userdn="ldap:///self";)

targetattr

The targetattr keyword targets the attributes for which the access control instruction should apply.

There are four general forms that it can take in the Server:

(targetattr="*"): Indicates that the access control rule applies to all user attributes. Operational attributes are not automatically included in this set.
(targetattr="+"): Indicates that the access control rule applies to all operational attributes. User attributes are not automatically included in this set.
(targetattr="<attr1>||<attr2>||<attr3>||…||<attrN>"): Indicates that the access control rule applies only to the named set of attributes.
(targetattr!="attr1||attr2||attr3||…||attrN"): Indicates that the access control rule applies to all user attributes except the named set of attributes. It does not apply to any operational attributes.

The targeted attributes can be classified as user attributes and operational attributes. User attributes define the actual data for that entry while operational attributes provide additional metadata about the entry that can be used for informational purposes, such as when the entry was created, last modified and by whom. Metadata can also include attributes specifying which password policy applies to the user, or overrided default constraints like size limit, time limit, or look-through limit for that user.

The Server distinguishes between these two types of attributes in its access control implementation. The PingDirectory server does not automatically grant any access at all to operational attributes. For example, the following clause applies only to user attributes and not to operational attributes.

(targetattr="*")

You can also target multiple attributes in the entry. The following clause targets the common name (cn), surname (sn) and state (st) attribute.

(targetattr="cn||sn||st")

You can use the + symbol to indicate that the rule should apply to all operational attributes.

(targetattr="+")

To include all user and all operational attributes, use both symbols.

(targetattr="*||+")

If you need to target a specific operational attribute rather than all operational attributes, include it in the values of the targetattr clause.

(targetattr="ds-rlim-size-limit")

If you want to target all user attributes and a specific operational attribute, use them in the targetattr clause.

(targetattr="*||ds-rlim-size-limit")

The following sample ACIs are placed on the dc=example,dc=com tree. The first ACI allows any user anonymous read access to all entries except the userPassword attribute. The second ACI allows users to update their own contact information. The third ACI allows the uid=admin user full access privileges to all user attributes in the dc=example,dc=com subtree.

aci: (targetattr!="userPassword")(version 3.0; acl "Allow anonymous
   read access for anyone"; allow (read,search,compare) userdn="ldap:///anyone";)
aci: (targetattr="telephonenumber||street||homePhone||l||st")
  (version 3.0; acl "Allow users to update their own contact info";
   allow (write) userdn="ldap:///self";)
aci: (targetattr="*")(version 3.0; acl "Grant full access for the admin user";
  allow (all) userdn="ldap:///uid=admin,dc=example,dc=com";)

When assigning access to user and operational attributes, it is easy to inadvertently create an access control instruction that grants far more capabilities to a user than originally intended. The following example shows the implications of the PingDirectory server not distinguishing between these attributes.

aci: (targetattr!="uid||employeeNumber")
  (version 3.0; acl "Allow users to update their own entries";
    allow (write) userdn="ldap:///self";)

This instruction is intended to allow a user to update any attribute in his or her own entry with the exception of uid and employeeNumber. This ACI is a common rule and seems harmless, but has serious consequences for a PingDirectory server that does not distinguish between user attributes and operational attributes. It allows users to update operational attributes in their own entries, and could be used for several malicious purposes, including:

A user could alter password policy state attributes to become exempt from password policy restrictions.
A user could alter resource limit attributes and bypass size limit, time limit, and look-through-limit constraints.
A user could add access control rules to his or her own entry, which could allow them to make their entry completely invisible to all other users, including administrators granted full rights by access control rules, but excluding users with the bypass-acl privilege allows them to edit any other attributes in their own entry, including those excluded by rules like uid and employeeNumber in the previous example, or add, modify, or delete any entries below his or her own entry.

Because the Server does not automatically include operational attributes in the target attribute list, these types of ACIs do not present a security risk for it. Users cannot add ACIs to any entries unless they have the modify-acl privilege.

Another danger in using the (targetattr!="x") pattern is that two ACIs within the same scope could have two different targetattr policies that cancel each other out. For example, if one ACI has (targetattr!="cn||sn") and a second ACI has (targetattr!="userPassword"), then the net effect is (targetattr="*"), because the first ACI inherently allows userPassword and the second allows cn and sn.

targetfilter

The targetfilter keyword targets all attributes that match results returned from a filter.

The targetfilter clause has the following syntax.

(targetfilter =  <ldap_filter>)

For example, the following clause targets all entries that contain the ou=engineering attribute.

(targetfilter = "(ou=engineering)")

You can only specify a single filter, but that filter can contain multiple elements combined with the OR operator. The following clause targets all entries that contain ou=engineering, ou=accounting, and ou=marketing.

(targetfilter = "(|(ou=engineering)(ou=accounting)(ou=marketing)")

The following example allows the user, uid=eng-mgr, to modify the departmentNumber, cn, and sn attributes for all entries that match the filter ou=engineering.

aci:(targetfilter="(ou=engineering)")
  (targetattr="departmentNumber||cn||sn")
  (version 3.0; acl "example"; allow (write)
   userdn="ldap:///uid=eng-mgr,dc=example,dc=com";)

targattrfilters

The targattrfilters keyword targets specific attribute values that match a filtered search criteria.

This keyword allows you to set up an ACI that grants or denies permissions on an attribute value if that value meets the filter criteria. The targattrfilters keyword applies to individual values of an attribute, not to the whole attribute. The keyword also allows the use of wildcards in the filters.

The keyword clause has the following format.

(target = "add=attr1:Filter1 && attr2:Filter2... && attrn:FilterN,
del=attr1:Filter1 && attr2:Filter2 ... && attrN:FilterN" )

Where:

add: Represents the operation of adding an attribute value to the entry.
del: Represents the operation of removing an attribute value from the entry.
<attr1>, <attr2>… <attrN>: Represents the targeted attributes.
<filter1>, <filter2>… <filterN>: Represents filters that identify matching attribute values.

The following conditions determine when the attribute must satisfy the filter:

When adding or deleting an entry containing an attribute targeted a targattrfilters element, each value of that attribute must satisfy the corresponding filter.
When modifying an entry, if the operation adds one or more values for an attribute targeted by a targattrfilters element, each value must satisfy the corresponding filter. If the operation deletes one or more values for a targeted attribute, each value must satisfy the corresponding filter.
When replacing the set of values for an attribute targeted by a targattrfilters element, each value removed must satisfy the delete filters and each value added must satisfy the add filters.

The following example allows any user who is part of the cn=directory server admins group to add the soft-delete-read privilege.

aci:(targattrfilter="add=ds-privilege-name:(ds-privilege-name=soft-delete-read)")
  (version 3.0; acl "Allow members of the the directory server admins group to grant the
   soft-delete-read privilege"; allow (write)
   groupdn="ldap:///cn=PingDirectory Server admins,ou=group,dc=example,dc=com";)

targetscope

Use the targetscope keyword to restrict the scope of an access control rule (ACR).

ACIs use a subtree scope by default, meaning they are applied to the target entry and all entries below it, either as defined by the target clause of the ACI or the entry in which the ACI is defined if it does not include a target. However, you can add the targetscope element into an ACR to restrict the set of entries to which it applies.

The following targetscope keyword values are allowed:

base: Indicates that the ACR applies only to the target entry and not to any of its subordinates.
onelevel: Indicates that the ACR applies only to entries that are immediate children of the target entry and not to the target entry itself nor to any subordinates of the immediate children of the target entry.
subtree: Indicates that the ACR applies to the target entry and all of its subordinates. This is the default behavior if no targetscope is specified.
subordinate: Indicates that the ACR applies to all entries below the target entry but not the target entry itself.

The following ACI targets all users to view the operational attributes present in the root DSA-specific entry (DSE):

supportedControl
supportedExtension
supportedFeatures
supportedSASLMechanisms
vendorName
vendorVersion

In the following example, targetscope is set to base to limit users to view only those attributes in the root DSE.

aci: (target="ldap:///")(targetscope="base")
    (targetattr="supportedControl||supportedExtension||
     supportedFeatures||supportedSASLMechanisms||vendorName||vendorVersion")
    (version 3.0; acl "Allow users to view Root DSE Operational Attributes";
     allow (read,search,compare) userdn="ldap:///anyone")

targetcontrol

Use the targetcontrol keyword to indicate whether a given request control can be used by users targeted in the ACI.

You can provide multiple OIDs by separating them with two pipe characters, optionally surrounded by spaces. When specifying control OIDs, wildcards are not allowed.

The following ACI example shows the controls required to allow an administrator to use and manage the soft delete feature. The soft delete request control allows the user to soft-delete an entry, so that it could be undeleted at a later time. The hard delete request control allows the user to permanently remove an entry or soft-deleted entry. The undelete request control allows the user to undelete a currently soft-deleted entry. The soft-deleted entry access request control allows the user to search for any soft-deleted entries in the server.

aci: (targetcontrol="1.3.6.1.4.1.30221.2.5.20||1.3.6.1.4.1.30221.2.5.22||
   1.3.6.1.4.1.30221.2.5.23||1.3.6.1.4.1.30221.2.5.24")
  (version 3.0; acl "Allow admins to use the Soft Delete Request Control,
   Hard Delete Request Control,Undelete Request Control, and
   Soft-deleted entry access request control";
   allow (read) userdn="ldap:///uid=admin,dc=example,dc=com";)

extOp

Use the extop keyword to indicate whether a given extended request operation can be used.

You can provide multiple OIDs by separating them with two pipe characters, optionally surrounded by spaces. When specifying extended request OIDs, wildcards are not allowed.

The following ACI example allows the uid=user-mgr to use the password modify request, OID=1.3.6.1.4.1.4203.1.11.1, and the StartTLS, OID=1.3.6.1.4.1.1466.20037, which are extended request OIDs.

aci:(extop="1.3.6.1.4.1.4203.1.11.1 || 1.3.6.1.4.1.1466.20037")
  (version 3.0; acl "Allows the mgr to use the Password Modify Request and StartTLS;
   allow(read) userdn="ldap:///uid=user-mgr,ou=people,dc=example,dc=com";)