PingDirectory

Summary of access control keywords

This section provides an overview of the supported keywords in the server access control implementation.

Targets

A target expression specifies the set of entries and attributes to which an access control rule applies.

A target expression has three components:

Keyword

The keyword specifies the type of target element.

Expression

The expression specifies the items that are targeted by the access control rule.

Operator

The operator is either equal, =, or not-equal, !=.

You cannot use the != operator with the targattrfilters and targetscope keywords.

For specific examples of each target keyword, see Working with targets.

(keyword[=||!=]expression)

You can use the following keywords in the target portion of ACIs:

Summary of Access Control Target Keywords
Target Keyword Description Wildcards

extop

Specifies the OIDs for any extended operations to which the access control rule should apply.

No

requestcriteria

Determines whether an access control rule applies to an operation based on whether that operation matches a given request criteria definition.

If present in an access control rule, the operator must be either "=" or "!=". The value must be enclosed in quotation marks and it must be the name or full DN of the configuration object that defines the desired request criteria.

For example, let’s say that you want to allow members of the cn=Sales Administrators,ou=Groups,dc=example,dc=com group to be able to read from and write to the entries for the users that are members of the cn=Sales Employees,ou=Groups,dc=example,dc=com group. To do this, you must first create a request criteria object that will match entries for users in the cn=Sales Employees,ou=Groups,dc=example,dc=com group. You can do this with the following configuration change:

dsconfig create-request-criteria \
     --criteria-name "Requests Targeting Sales Employees" \
     --type simple \
     --set "any-included-target-entry-group-dn:cn=Sales Employees,ou=Groups,dc=example,dc=com"

With that request criteria defined, you can use a modification like the following to create the corresponding access control rule:

dn: dc=example,dc=com
changetype: modify
add: aci
aci: (targetattr="*")(requestcriteria="Requests Targeting Sales
  Employees")(version 3.0; acl "Allow sales administrators to manage
  sales employees"; allow (read,search,compare,write)
  groupdn="ldap:///cn=Sales Administrators,ou=Groups,dc=example,dc=com";)

target

Specifies the set of entries, identified using LDAP URLs, to which the access control rule applies.

Yes

targattrfilters

Identifies specific attribute values based on filters that can be added to or removed from entries to which the access control rule applies.

Yes

targetattr

Specifies the set of attributes to which the access control rule should apply.

Yes

targetcontrol

Specifies the OIDs for any request controls to which the access control rule should apply.

No

targetfilter

Specifies one or more search filters that can be used to indicate the set of entries to which the access control should apply.

Yes

targetscope

Specifies the scope of entries, relative to the defined target entries or the entry containing the ACI if there is no target, to which the access control rule should apply.

No

Permissions

Permissions indicate the types of operations to which an access control rule could apply.

You can specify if the user or group of users are allowed or not allowed to carry out a specific operation. For example, you can grant read access to targeted entries using the allow (read) permission. You can also deny access to the target entries and attributes using the deny (read) permission. You can list multiple permissions as required in the ACI.

allow(permission1...,permission2,...permissionN)
deny(permission1...,permission2,...permissionN)

You can use the following keywords in the permissions portion of ACIs.

Keyword Description

add

Indicates that the access control applies to add operations. Learn more about Changing the allow add ACI behavior for entries.

compare

Indicates that the access control applies to compare operations and to search operations with a base-level scope that targets a single entry.

delete

Indicates that the access control applies to delete operations.

export

Indicates that the access control applies only to modify DN operations in which an entry is moved below a different parent by specifying a new superior distinguished name (DN) in the modify DN request. The requestor must have the export permission for operations against the entry’s original DN. The requestor must have the import permission for operations against the entry’s new superior DN.

For modify DN operations that alter the relative distinguished name (RDN) of an entry but keeps it below the same parent, such as renaming the entry, only the write permission is required. This is true regardless of whether the entry being renamed is a leaf entry or has subordinate entries.

import

See the description for the export permission.

proxy

Indicates that the access control rule applies to operations that attempt to use an alternate authorization identity, such as operations that include a proxied authorization request control, an intermediate client request control with an alternate authorization identity, or a client that has authenticated with a Simple Authentication and Security Layer (SASL) mechanism that allows an alternate authorization identify to be specified.

read

Indicates that the access control rule applies to search result entries returned by the server.

search

Indicates that the access control rule applies to search operations with a non-base scope.

selfwrite

Indicates that the access control rule applies to operations in which a user attempts to add or remove their own DN to the values for an attribute, such as users adding or removing themselves from groups.

write

Indicates that the access control rule applies to modify and modify DN operations.

all

An aggregate permission that includes all other permissions except import, export, and proxy. This is equivalent to providing a permission of add, compare, delete, read, search, selfwrite, and write.

Bind rules

The bind rules indicate whether an access control rule should apply to a given requester.

The syntax for the target keyword has three components:

Keyword

The keyword specifies the type of target element.

Expression

The expression specifies the items that are targeted by the access control rule.

Operator

The operator is either equal, =, or not-equal, !=.

You must use the semicolon delimiter symbol, ;, after the end of the final bind rule.

keyword[=||!=]expression;

For added access control precision, you can combine multiple bind rules using the Boolean operations AND, OR, and NOT. The standard Boolean rules for evaluation apply:

  • Innermost to outer parentheses first

  • Left to right expressions

  • NOT before AND or OR

For example, an access control instruction (ACI) with the following bind rule targets all users who are not uid=admin,dc=example,dc=com and use simple authentication.

(userdn!="ldap:///uid=admin,dc=example,dc=com" and authmethod="simple");

The following bind rule targets users that are uid=admin,dc=example,dc=com and authenticate using Simple Authentication and Security Layer (SASL) EXTERNAL or access the server from a loopback interface.

(userdn="ldap:///uid=admin,dc=example,dc=com and (authmethod="SSL" or ip="127.0.0.1"));

You can use the following keywords in the bind rule portion of ACIs.

Bind Rule Keyword Description

authmethod

Indicates that the requester’s authentication method is taken into account when determining whether the access control rule should apply to an operation. You cannot use wildcards in this expression.

Use the syntax authmethod = method where method is one of the following representations:

  • none

  • simple indicates that the client is authenticated to the server using a bind DN and password.

  • ssl indicates that the client is authenticated with an SSL/TLS certificate (for example, via SASL EXTERNAL), and not just over a secure connection to the server.

  • sasl \{sasl_mechanism} indicates that the client is authenticated to the server using a specified SASL mechanism.

The following example allows users who authenticate with an SSL/TLS certificate (for example, using SASL EXTERNAL) to update their own entries.

aci: (targetattr="*")
(version 3.0; acl "Allow users to update their own entries";
allow (write) (userdn="ldap:///self" and authmethod="ssl");)

connectioncriteria

Allows or denies an operation based on whether the client connection matches a given connection criteria definition.

If present in an access control rule, the operator must be either "=" or "!=". The value must be enclosed in quotation marks, and it must be the name or full DN of the configuration object that defines the desired connection criteria.

For example, you can use a modification like the following to allow any client matching the "Root Users and Topology Administrators" connection criteria to have full read and write access to entries below dc=example,dc=com:

dn: dc=example,dc=com
changetype: modify
add: aci
aci: (targetattr="*")(version 3.0; acl "Full read and write access for
  administrators"; allow (read,search,compare,write)
  connectioncriteria="Root Users and Topology Administrators";)

dayofweek

Indicates that the day of the week is taken into account when determining whether the access control rule should apply to an operation. You cannot use wildcards in this expression.

You can separate multiple day of week values by commas. Use the following syntax.

dayofweek =  day1,  day2, ...

day is one of the following:

  • sun

  • mon

  • tues

  • wed

  • thu

  • fri

  • sat

The following example allows users who authenticate on weekdays with an SSL/TLS certificate, such as SASL EXTERNAL, to update their own entries.

aci: (targetattr="*")
(version 3.0; acl "Allow users to update their own entries";
allow (write) (dayofweek!="sun,sat" and userdn="ldap:///self"
and authmethod="ssl");)

dns

Indicates that the requester’s DNS-resolvable host name is taken into account when determining whether the access control rule should apply to an operation. You can use wildcards in this expression.

You can separate multiple DNS patterns by commas. Use the following syntax.

dns =  dns-host-name

The following example allows users on host name server.example.com to update their own entries.

aci: (targetattr="*")
(version 3.0; acl "Allow users to update their own entries";
allow (write) (dns="server.example.com" and userdn="ldap:///self");)

groupdn

Indicates that the requester’s group membership is taken into account when determining whether the access control rule should apply to any operation. You cannot use wildcards in this expression.

groupdn [ = || != ] "ldap:///groupdn [ || ldap:///groupdn ] ..."

The following example allows users in the managers group to update their own entries.

aci: (targetattr="*")
(version 3.0; acl "Allow users to update their own entries";
allow (write)
(groupdn="ldap:///cn=managers,ou=groups,dc=example,dc=com");)

ip

Indicates that the requester’s IP address is taken into account when determining whether the access control rule should apply to an operation. You can use wildcards in this expression.

You can separate multiple IP address patterns by commas. Use the following syntax.

ip [ = || != ]  <ipAddressList>

ipAddressList is one of the following:

  • A specific IPv4 address: 127.0.0.1

  • An IPv4 address with wildcards to specify a subnetwork: 127.0.0.*

  • An IPv4 address or subnetwork with subnetwork mask: 123.4.5.0+255.255.255.0

  • An IPv4 address range using CIDR notation: 123.4.5.0/24

  • An IPv6 address as defined by RFC 2373.

The following example allows users on 10.130.10.2 and localhost to update their own entries.

aci: (targetattr="*")
(version 3.0; acl "Allow users to update their own entries";
allow (write) (ip="10.130.10.2,127.0.0.1" and userdn="ldap:///self");)

oauthscope

Indicates that the scopes associated with any OAuth 2.0 access token presented by a SCIMv2 client is taken into account when determining whether the access control rule applies to an operation.

Use the following syntax.

oauthscope [ = || != ] "<scopeIdentifier>"

scopeIdentifier is one of the following:

  • The name of a single scope to match. The name will be treated as case-sensitive.

  • A substring assertion that contains one or more asterisks as wildcards.

  • A single asterisk by itself, which will match any scope.

The following example grants all rights to any client that presented an OAuth 2.0 token that is associated with the scim_admin scope.

aci: (targetattr="*")
(version 3.0; acl "Full rights for users with the scim_admin OAuth 2.0 scope";
allow (all) oauthscope="scim_admin";)

secure

Allows or denies an operation based on whether the client is communicating with the server over a secure connection; for example, using LDAPS or StartTLS over LDAP.

If present in an access control rule, the operator must be either "=" or "!=", and the value must be either "true" or "false" including the quotation marks. With this in mind, the secure bind rule takes the following forms:

  • secure="true" indicates that the ACI will apply only if the connection was received over a secure connection.

  • secure="false" indicates that the ACI will only apply if the connection was received over a non-secure connection.

  • secure!="true" indicates that the ACI will apply only if the connection was received over a non-secure connection.

  • secure!="false" indicates that the ACI will apply only if the connection was received over a secure connection.

For example, you can use a modification like the following to allow users below dc=example,dc=com to update their own passwords over a secure connection:

dn: dc=example,dc=com
changetype: modify
add: aci
aci: (targetattr="userPassword")(version 3.0; acl "Allow users to update
  their own passwords over a secure connection"; allow (write)
  userdn="ldap:///self" and secure="true";)

timeofday

Indicates that the time of day is taken into account when determining whether the access control rule should apply to an operation. You cannot use wildcards in this expression.

Use the following syntax.

timeofday [ = || != || >= || > || <= || < ]  <time>

time is one of the following:

  • 4-digit 24-hour time format (0000 to 2359, where the first two digits represent the hour of the day and the last two represent the minute of the hour)

  • You cannot use wildcards in this expression

The following example allows users to update their own entries if the request is received before 12 noon.

aci: (targetattr="*")
(version 3.0; acl "Allow users who authenticate before noon
to update their own entries";
allow (write) (timeofday<1200 and userdn="ldap:///self"
and authmethod="simple");)

userattr

Indicates that the requester’s relation to the value of the specified attribute is taken into account when determining whether the access control rule should apply to an operation.

Use the following syntax.

userattr =  <attrName># [  <bindType>  ||  <attrValue> ]

Where:

  • attrName = name of the attribute for matching

  • bindType= USERDN, GROUPDN, LDAPURL

  • attrValue = an attribute value. The attrVALUE of the attribute must match on both the bind entry and the target of the ACI.

A bindType value of USERDN indicates that the target attribute should have a value which matches the DN of the authenticated user. A bindType value of GROUPDN indicates that the target attribute should have a value which matches the DN of a group in which the authenticated user is a member. A bindType value of LDAPURL indicates that the target attribute should have a value that is an LDAP URL whose criteria matches the entry for the authenticated user.

Any value other than USERDN, GROUPDN, or LDAPURL is expected to be present in the target attribute of the authenticated user’s entry.

The following example allows a manager to change employee’s entries. If the bind DN is specified in the manager attribute of the targeted entry, the bind rule is evaluated to TRUE.

aci: (targetattr="*")
(version 3.0; acl "Allow a manager to change employee entries";
allow (write) userattr="manager#USERDN";)

The following example allows any member of a group to change employee’s entries. If the bind DN is a member of the group specified in the allowEditors attribute of the targeted entry, the bind rule is evaluated to TRUE.

aci: (targetattr="*")
(version 3.0; acl "Allow allowEditors to change employee entries";
allow (write) userattr="allowEditors#GROUPDN";)

The following example allows a user’s manager to edit that user’s entry and any entries below the user’s entry up to two levels deep. You can specify up to five levels (0, 1, 2, 3, 4) below the targeted entry, with zero 0 indicating the targeted entry.

aci: (targetattr="*")
(version 3.0; acl "Allow managers to change employees entries two levels below";
allow (write) userattr="parent[0,1,2].manager#USERDN";)

The following example allows any member of the engineering department to update any other member of the engineering department at or below the specified ACI.

aci: (targetattr="*")
(version 3.0; acl "Allow any member of Eng Dept to update any other member of the
enginering department at or below the ACI";
allow (write) userattr="department#ENGINEERING";)

The following example allows an entry to be updated by any user whose entry matches the criteria defined in the LDAP URL contained in the allowedEditorCriteria attribute of the target entry.

aci: (targetattr="*")
(version 3.0; acl "Allow a user that matches the filter to change entries";
allow (write) userattr="allowedEditorCriteria#LDAPURL";)

userdn

Indicates that the user’s DN is taken into account when determining whether the access control rule should apply to an operation.

Use the following syntax..

userdn [ = || != ] "ldap:///<value>  [ || "ldap:///<value>  ..."]

Where value is one of the following representations:

  • The DN of the target user

  • A value of anyone to match any client, including unauthenticated clients.

  • A value of all to match any authenticated client.

  • A value of parent to match the client authenticated as the user defined in the immediate parent of the target entry.

  • A value of self to match the client authenticated as the user defined in the target entry.

If the value provided is a DN, then that DN can include wildcard characters to define patterns. A single asterisk will match any content within the associated DN component, and two consecutive asterisks can be used to match zero or more DN components.

The following example allows users to update their own entries.

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