--- title: Working with targets description: The following section presents a detailed look and examples of the target access control instruction (ACI) keywords: component: pingdirectory version: 11.0 page_id: pingdirectory:managing_access_control:pd_ds_work_with_targets canonical_url: https://docs.pingidentity.com/pingdirectory/11.0/managing_access_control/pd_ds_work_with_targets.html revdate: August 12, 2024 page_aliases: ["pd_ds_target.adoc", "pd_ds_targetattr.adoc", "pd_ds_targetfilter.adoc", "pd_ds_targettrfilters.adoc", "pd_ds_targetscope.adoc", "pd_ds_targetcontrol.adoc", "pd_ds_extop.adoc"] section_ids: target: target targetattr: targetattr targetfilter: targetfilter targattrfilters: targattrfilters targetscope: targetscope targetcontrol: targetcontrol extop: extOp --- # 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:///) ``` 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="||||||…​||")` 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 = ) ``` 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. * ``, ``… `` Represents the targeted attributes. * ``, ``… `` 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";) ```