ACI Syntax

ACIs are complex structures with many possible variations. The following sections describe the syntax of an ACI in detail.

• ACI Syntax Overview

• Defining Targets

• Defining Permissions

See also Bind Rule Syntax.

ACI Syntax Overview

The aci attribute has the following syntax:

aci: (target)(version 3.0;acl "name";permissionBindRules;)

where:

• target specifies the entry, attributes, or set of entries and attributes for which you want to control access. The target can be a distinguished name, one or more attributes, or a single LDAP filter. The target is optional. When the target is not specified, the ACI applies to the entire entry where it is defined and all of its children.

• version 3.0 is a required string that identifies the ACI version.

• name is a name for the ACI. The name can be any string that identifies the ACI. The ACI name is required and should describe the effect of the ACI. Although there are no restrictions on the name, it is good practice to use unique names for ACIs. If you use unique names, the Get Effective Rights control enables you to determine which ACI is in force.

• permission specifically states what rights you are either allowing or denying, for example read or search rights.

• bindRules specify the credentials and bind parameters that a user has to provide to be granted access. Bind rules can also be based on user or group membership or connection properties of the client.

You can specify multiple targets and permission-bind rule pairs. This allows you to refine both the entry and attributes being targeted and efficiently set multiple access controls for a given target, as shown here:

aci: (target)...(target)(version 3.0;acl "name"; permissionBindRule; permissionBindRule; ...; permissionBindRule;)

The following example shows a complete LDIF ACI:

aci: (target="ldap:///uid=bjensen,dc=example,dc=com")
(targetattr="*")(version 3.0; acl "example"; allow (write)
userdn="ldap:///self";)

In this example, the ACI states that the user bjensen has rights to modify all attributes in her own directory entry.

Defining Targets

The target identifies what the ACI applies to. When a client requests an operation on attributes in an entry, the directory server evaluates the target to see if the ACI must be evaluated to allow or deny the operation. If the target is not specified, the ACI applies to all attributes in the entry containing the aci attribute and to the entries below it.

The following sections describe how to define targets:

• Targeting a Directory Entry

• To Target Attributes

• To Target an Entry and Attributes

• To Target Entries or Attributes Using LDAP Filters

• To Target Attribute Values Using LDAP Filters

• To Target a Single Directory Entry

• To Specify the Scope of an ACI

• To Target LDAP Controls

• To Target LDAP Extended Operations

The general syntax for a target is one of the following:

(keyword = "expression")
(keyword != "expression")

where:

• keyword indicates the type of target. The following types of targets are defined by the keywords in Table 2-1:

  • A directory entry or its subtree

  • The attributes of an entry

  • A set of entries or attributes that match an LDAP filter

  • An attribute value or combination of values that match an LDAP filter

  • The scope of the ACI

  • An LDAP control

  • An extended operation

• The equal sign (=) indicates that the target is the object specified in the expression, and not equal (!=) indicates that the target is any object not specified in the expression.

  ---

  Note - The not-equal operator is not supported for the targattrfilters and targetscope keywords.

  ---

• expression is dependent on the keyword and identifies the target. The quotation marks ("") around expression are syntactically required, although the current implementation accepts expressions like targetattr=*. In future versions, syntax checking might become more strict, so you should always use quotation marks.

The following table lists each keyword and the associated expressions.

Table 2-1 LDIF Target Keywords

Targeting a Directory Entry

Use the target keyword and a DN inside an LDAP URL to target a specific directory entry and any entries below it. The targeted DN must be located in the entry where the ACI is defined or in the subtree below the entry. The target expression has the following syntax:

(target = "ldap:///distinguishedName")
(target != "ldap:///distinguishedName")

The distinguished name must be located in the entry where the ACI is defined or in the subtree below the entry. For example, the following target can be used in an ACI on ou=People,dc=example,dc=com:

(target = "ldap:///uid=bjensen,ou=People,dc=example,dc=com")

The keyword target is optional. If it is not present, the default target for the ACI is the entry where the ACI is stored.

(target="ldap:///uid=cfuentes,o=Example Bolivia\, S.A.")

You can also use a wildcard in the DN to target any number of entries that match the LDAP URL. The following are legal examples of wildcard usage:

• (target="ldap:///uid=*,dc=example,dc=com") Matches every immediate child of the example.com branch entry that has the uid attribute in the entry's RDN, as shown in this example.

  uid=tmorris,dc=example,dc=com
  uid=yyorgens,dc=example,dc=com
  uid=bjensen,dc=example,dc=com

• (target="ldap:///uid=*,**,dc=example,dc=com") Matches every entry more than one level below the example.com branch entry that has the uid attribute in the entry's RDN, as shown in this example.

  uid=tmorris,ou=sales,dc=example,dc=com
  uid=yyorgens,ou=marketing,dc=example,dc=com
  uid=bjensen,ou=eng,ou=east,dc=example,dc=com

• (target="ldap:///uid=*Anderson,ou=People,dc=example,dc=com") Matches every entry immediately below the ou=People branch entry with a uid ending in Anderson.

• (target="ldap:///*=*Anderson,ou=People,dc=example,dc=com") Matches every entry immediately below the ou=People branch whose RDN ends with Anderson, regardless of the naming attribute.

Multiple wildcards are allowed, such as in uid=*,ou=*,dc=example,dc=com, which matches every entry in the example.com tree whose distinguished name contains the uid and ou attributes in the specified positions.

To Target Attributes

In addition to targeting directory entries, you can also target one or more attributes, or all but one or more user attributes, that occur in the targeted entries. This is useful when you want to deny or allow access to partial information about an entry. For example, you can allow access to only the common name, surname, and telephone number attributes of a given entry. Similarly, you can deny access to sensitive information such as personal data.

If no targetattr rule is present, no attributes can be accessed by default. To access all user attributes, the rule must be targetattr="*". Operational attributes must be explicitly named.

The targeted attributes do not need to exist on the target entry or its subtree, but the ACI applies whenever they do. The attributes you target do not need to be defined in the schema. The absence of schema checking makes it possible to implement an access control policy before importing your data and its schema.

To target attributes, you use the targetattr keyword and provide the attribute names. The targetattr keyword uses the following syntax:

(targetattr = "attribute")
(targetattr != "attribute")

You can target multiple attributes by using the targetattr keyword with the following syntax:

(targetattr = "attribute1 || attribute2 ... || attributeN")
(targetattr != "attribute1 || attribute2 ... || attributeN")

For example, to target an entry's common name, surname, and UID attributes, you would use the following:

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

To target all of an entry's user attributes, except carlicense, you would use the following target:

(targetattr != "carlicense")

The preceding example does not return operational attributes.

Targeted attributes include all subtypes of the named attribute. For example, (targetattr = "locality") also targets locality;lang-fr. You can also target subtypes specifically, for example, (targetattr = "locality;lang-fr-ca").

You can use a wildcard as a stand-alone character in a targetattr rule (such as targetattr="*"), but this use is discouraged because it serves no particular purpose and can have a negative performance impact.

To Target an Entry and Attributes

By default, the entry targeted by an ACI containing a targetattr keyword is the entry on which the ACI is placed. That is, if you apply the ACI aci: (targetattr = "uid")(accessControlRules;) to the ou=Marketing, dc=example,dc=com entry, then the ACI applies to the entire Marketing subtree. However, you can also explicitly specify a target using the target keyword, as shown in the following example:

aci: (target="ldap:///uid=*,ou=Marketing,dc=example,dc=com")
(targetattr="uid") (accessControlRules;)

The order in which you specify the target and the targetattr keywords is irrelevant.

To Target Entries or Attributes Using LDAP Filters

You can use LDAP filters to target a set of entries that match certain criteria. To do this, use the targetfilter keyword with an LDAP filter. The ACI applies to all entries that match the filter at the level of the target DN and in the subtree below it.

The targetfilter keyword uses this syntax:

(targetfilter = "LDAPfilter")

where LDAPfilter is a standard LDAP search filter. For more information about filter syntax, see search filter in Oracle Fusion Middleware Glossary for Oracle Unified Directory.

For example, suppose that all entries representing employees have a status of salaried or contractor and an attribute representing the number of hours worked, as a percentage of a full-time position. To target all the entries representing contractors or part-time employees, you could use the following filter:

(targetfilter = "(|(status=contractor)(fulltime<=79))")

The Netscape extended filter syntax is not supported in ACIs. For example, the following target filter is not valid:

(targetfilter = "(locality:fr:=<= Qu?bec)")

Target filters select whole entries as targets of the ACI. You can associate the targetfilter and the targetattr keywords to create ACIs that apply to a subset of attributes in the targeted entries.

The following LDIF example allows members of the Engineering Admins group to modify the departmentNumber and manager attributes of all entries in the Engineering business category. This example uses LDAP filtering to select all entries with businessCategory attributes set to Engineering:

dn: dc=example,dc=com
objectClass: top
objectClass: organization
aci: (targetattr="departmentNumber || manager")
(targetfilter="(businessCategory=Engineering)")
(version 3.0; acl "eng-admins-write"; allow (write)
groupdn ="ldap:///cn=Engineering Admins, dc=example,dc=com";)

Although using LDAP filters can be useful when you are targeting entries and attributes that are spread across the directory, the results are sometimes unpredictable because filters do not directly name the object for which you are managing access. The set of entries targeted by a filtered ACI is likely to change as attributes are added or deleted. Therefore, if you use LDAP filters in ACIs, you should verify that they target the correct entries and attributes by using the same filter in an ldapsearch operation.

To Target Attribute Values Using LDAP Filters

You can use access control to target specific attribute values. This means that you can grant or deny permissions on an attribute if that attribute's value meets the criteria defined in the ACI. An ACI that grants or denies access based on an attribute's value is called a value-based ACI.

For example, you can grant all users in your organization permission to modify the roomNumber attribute in their own entries. However, you would also want to ensure that they do not give themselves reserved room numbers, all of which begin with 12. LDAP filters are used to check that the conditions on attribute values are satisfied.

To create a value-based ACI, you must use the targattrfilters keyword with the following syntax:

(targattrfilters="Op=attr1:F1[(&& attr2:F2)*][;Op=attr:F[(&& attr:F)*]")

where:

• Op is either an add or delete operation:

  • add represents the operation of creating an attribute.

  • delete represents the operation of deleting an attribute.

• attr represents the target attributes.

• F represents filters that apply only to the associated attribute.

When creating an entry, if a filter applies to an attribute in the new entry, then all values of that attribute must satisfy the filter. When deleting an entry, if a filter applies to an attribute in the entry, then all values of that attribute must also satisfy the filter.

When modifying an entry, if the operation adds an attribute, then the add filter that applies to that attribute must be satisfied. If the operation deletes an attribute, then the delete filter that applies to that attribute must be satisfied. If individual values of an attribute already present in the entry are replaced, then both the add and delete filters must be satisfied.

The following example attribute filter allows users to add any roomNumber attribute to their own entries except the reserved room numbers, which have a 12 prefix. It also allows users to add a telephone number with a 123 prefix.

(targattrfilters="add=roomNumber:(!(roomNumber=12*)) && telephoneNumber:(telephoneNumber=123*)")

To Target a Single Directory Entry

There is no explicit way to target a single entry. However, you can achieve this in one of two ways:

• By creating a bind rule that matches user input in the bind request with an attribute value stored in the targeted entry

• By using the targetfilter keyword

With the targetfilter keyword you can specify an attribute value that appears only in the desired entry. For example, during the installation of the directory server, the following ACI is created:

aci: (targetattr="*")(targetfilter=(o=example))
(version 3.0; acl "Default anonymous access";
allow (read, search) userdn="ldap:///anyone";)

This ACI can apply only to the o=example entry, because that is the only entry with an attribute o having the value example.

The risk associated with these methods is that your directory tree can change in the future, and you would have to remember to modify this ACI.

To Specify the Scope of an ACI

Usually an ACI has subtree scope. You can restrict the scope of an ACI by using the targetscope keyword with the following syntax:

(targetscope="expression")

where expression is one of the following:

base

The ACI applies to the target resource only.

onelevel

The ACI applies to the target resource's first-generation children.

subtree

The ACI applies to the target resource and the subtree below it.

subordinate

The ACI applies only to the subtree below the target resource.

If the targetscope is not specified, the default value is subtree. The following example restricts the ACI target match only to the entry with the distinguished name uid=bjensen,ou=People,dc=example,dc=com and any of the children one level below it:

(target = "ldap:///uid=bjensen,ou=People,dc=example,dc=com")(targetscope="onelevel")

To Target LDAP Controls

To target LDAP controls, use the targetcontrol keyword and provide the control OID. The targetcontrol keyword uses the following syntax:

(targetcontrol = "oid")

(targetcontrol != "oid")

You can target multiple LDAP controls by using the targetcontrol keyword with the following syntax:

(targetcontrol = "oid1 || oid2 ... || oidN")

(targetcontrol != "oid1 || oid2 ... || oidN")

For example, to target both the get effective rights control and the proxied authorization V2 control, use the following targetcontrol expression:

(targetcontrol = "1.3.6.1.4.1.42.2.27.9.5.2 || 2.16.840.1.113730.3.4.18")

To Target LDAP Extended Operations

To target extended operations, use the extop keyword and provide the operation OID. The extop keyword uses the following syntax:

(extop= "oid")

(extop!= "oid")

You can target multiple extended operations by using the extop keyword with the following syntax:

(extop = "oid1 || oid2 ... || oidN")

(extop != "oid1 || oid2 ... || oidN")

For example, to target both the StartTLS extended operation and the Password Modify extended operation, use the following extop expression:

(extop = "1.3.6.1.4.1.1466.20037 || 1.3.6.1.4.1.4203.1.11.1.")

Defining Permissions

Permissions specify the type of access that you are allowing or denying. You can either allow or deny permission to perform specific operations in the directory. The various operations that can be assigned are known as rights.

There are two parts to setting permissions:

• Allowing or denying access

• Assigning rights

The following sections describe how to define permissions:

• To Allow or Deny Access

• To Assign Rights

• Rights Required for LDAP Operations

• Permissions Syntax

To Allow or Deny Access

You can explicitly allow or deny access permissions by using the allow or the deny keyword.

To Assign Rights

Rights detail the specific operations a user can perform on directory data. You can allow or deny all rights, or you can assign one or more of the following rights:

Read

Indicates whether users can read the directory entries and the attributes of entries specified in the ACI. This permission applies only to the search operation. (Compare the Read permission with the description of the Search permission that follows.)

Write

Indicates whether users can modify an entry by adding, modifying, or deleting attributes. This permission applies to the modify and modRDN operations.

Add

Indicates whether users can create entries. This permission applies only to the add operation.

Delete

Indicates whether users can delete entries. This permission applies only to the delete operation.

Search

Indicates whether users can search on the targets specified in the ACI. This permission applies only to the search operation. The Search right is checked once, and after the search is allowed or denied, it is not checked again. If the search is allowed, the read right is then applied to each entry to be returned as a result of the search and to each attribute of each entry.

Compare

Indicates whether users can compare data they supply with data stored in the directory. With compare rights, the directory returns a success or failure message in response to an inquiry, but the user cannot see the value of the entry or attribute. This permission applies only to the compare operation.

Selfwrite

Indicates whether users can add or delete their own DN in an attribute of the target entry. The syntax of this attribute must be a distinguished name. This right is used only for group management. Selfwrite works with proxy authorization: it grants the right to add or delete the proxy DN from the group entry (not the DN of the bound user).

Proxy

Indicates whether the specified DN can access the target with the rights of another entry. You can grant proxy access using the DN of any user in the directory except the Directory Manager DN. Moreover, you cannot grant proxy rights to the Directory Manager. An example is provided in Proxy Authorization ACIs in Oracle Fusion Middleware Administration Guide for Oracle Unified Directory.

Import

Used by the modify DN operation. This access right indicates whether an entry can be imported to the specified DN.

Export

Used by the modify DN operation. This access right indicates whether an entry can be exported from the specified DN.

All

Indicates that the specified DN has the following rights to the targeted entry: read, write, search, delete, compare, and selfwrite. The All access right does not give the following rights to the target entry: proxy, import, and export.

Rights are granted independently of one another. This means, for example, that a user who is granted add rights can create an entry but cannot delete it if delete rights have not been specifically granted. Therefore, when planning the access control policy for your directory, you must ensure that you grant rights in a way that makes sense for users. For example, it does not usually make sense to grant write permission without granting read and search permissions.

Rights Required for LDAP Operations

This section describes the rights that you need to grant to users depending on the type of LDAP operation that you want to authorize them to perform.

• Adding an entry

  • Grant add permission on the entry being added.

  • Grant write permission on the value of each attribute in the entry. This right is granted by default but could be restricted using the targattrfilters keyword.

• Deleting an entry

  • Grant delete permission on the entry to be deleted.

  • Grant write permission on the value of each attribute in the entry. This right is granted by default but could be restricted using the targattrfilters keyword.

• Modifying an attribute in an entry

  • Grant write permission on the attribute type.

  • Grant write permission on the value of each attribute type. This right is granted by default but could be restricted using the targattrfilters keyword.

• Modifying the RDN of an entry

  • Grant write permission on the entry.

  • Grant write permission on the attribute type used in the new RDN.

  • Grant write permission on the attribute type used in the old RDN, if you want to grant the right to delete the old RDN.

  • Grant write permission on the value of the attribute type used in the new RDN. This right is granted by default but could be restricted using the targattrfilters keyword.

• Moving an entry to another subtree

  • Grant export permissions on the entry that you want to move.

  • Grant import permission on the new superior entry of the entry that you want to move.

• Comparing the value of an attribute

  • Grant compare permission on the attribute type.

• Searching for entries

  • Grant search permission on each attribute type used in the search filter.

  • Grant read permission on at least one attribute type used in the entry to ensure that the entry is returned.

  • Grant read permission an each attribute type to be returned with the entry.

The permissions you need to set up to allow users to search the directory are more readily understood with an example. Consider the following search:

$ ldapsearch -h host -p port -D "uid=bjensen,dc=example,dc=com" \
  -w password -b "dc=example,dc=com" \
  "(objectclass=*)" mail

The following ACI is used to determine whether user bjensen can be granted access for searching her own entry:

aci: (targetattr = "mail")(version 3.0; acl "self access to \
mail"; allow (read, search) userdn = "ldap:///self";)

The search result list is empty because this ACI does not allow bjensen the right to search on the objectclass attribute. For the search operation to be successful, you must modify the ACI, as shown in the following example:

aci: (targetattr = "mail || objectclass")(version 3.0; acl \
"self access to mail"; allow (read, search) userdn = \
"ldap:///self";)

Permissions Syntax

In an ACI statement, permissions use the following syntax:

allow|deny (rights)

where rights is a list of comma-separated keywords enclosed within parentheses. Valid keywords are read, write, add, delete, search, compare, selfwrite, proxy, import, export, or all.

The all access right does not give the following rights to the target entry: proxy, import, and export.

In the following example, read, search, and compare access is allowed, provided that the bind rule is evaluated to be true:

aci: (target="ldap:///dc=example,dc=com") (version 3.0;acl \
"example"; allow (read, search, compare) bindRule;)