Creating and managing access controls

To create and update ACLs in LDBM, TDBM, CDBM, GDBM, or the schema entry, use a tool implementing ldap_modify APIs, such as ldapmodify. The ldapmodify utility allows creation, modification, and deletion of any set of attributes that are associated with an entry in the directory. Because access control information is maintained as a set of additional attributes within an entry, ldapmodify is a natural choice for administering access control information in LDBM, TDBM, CDBM, GDBM, or the schema entry.

For more information about the utilities, see LDAP client utilities in z/OS IBM Tivoli Directory Server Client Programming for z/OS.

Creating an ACL

In order to create an ACL, the aclEntry and aclPropagate attributes must be added to the information stored for an entry. The aclEntry and aclPropagate attributes are added to an entry by either specifying them as part of the entry information when the entry is added to the directory or by modifying the entry after it exists to contain the aclEntry and aclPropagate information.

It is possible to create an ACL without specifying the aclPropagate attribute. In this case, the aclPropagate attribute is assumed to have a value of TRUE and is added into the directory entry automatically, along with the aclEntry information.

Because the ldapmodify utility is powerful, all the possible ways of adding the aclEntry and aclPropagate information cannot be shown here. The examples shown here describe the more common uses of the ldapmodify utility to add ACL information.

Figure 1 shows how to add a propagating ACL with three aclEntry values to an existing entry replacing any current aclEntry value.

Figure 1. Example of adding propagating ACL to existing entry in directory
$ ldapmodify -h 127.0.0.1 -D "cn=admin" -w xxxx -f newAcl.ldif

Where newAcl.ldif contains:

dn: cn=tim, o=Your Company
changetype: modify
replace: aclEntry
aclEntry: cn=jeanne, o=Your Company:
 normal:rsc:sensitive:rsc:critical:rsc
aclEntry: cn=jeff, cn=tim, o=Your Company:normal:rsc
aclEntry: cn=tim, o=Your Company:
 normal:rwsc:sensitive:rwsc:critical:rwsc
-

The ACL added in Figure 1 is created as a propagating ACL because the aclPropagate attribute is not specified and is assumed to be TRUE. This means that the ACL applies to all entries below cn=tim, o=Your Company that do not already have an ACL associated with them. Note that the first and last aclEntry values span two lines in the newAcl.ldif file. In order to do this, the first character on the continued line must be a space character, as shown in the example.

It is not required that an administrator updates all ACL information, the examples in this section all use a root administrator when updating ACLs. Further, the use of -h 127.0.0.1 implies that the ldapmodify utility is performed from the same system that the LDAP server is running and that the LDAP server is listening on TCP/IP port 389. For more details about the -h, -p, -D, and -w command-line options, see ldapmodify and ldapadd utilities in z/OS IBM Tivoli Directory Server Client Programming for z/OS. The ACL attributes can be updated from any LDAP client if the user performing the updates has the correct authorization to update the ACL information.

The ACL attributes are defined to be in a special access class called restricted. Therefore, in order to allow someone other than an LDAP administrator to update the ACL attributes, they must either be the entry owner or have the correct authorization to restricted attributes. Figure 2 shows an example of adding an ACL so that cn=jeanne, o=Your Company can update the ACL information:

Figure 2. Example of adding propagating ACL to existing entry in the directory.
$ ldapmodify -h 127.0.0.1 -D "cn=admin" -w xxxx -f newAcl.ldif

Where newAcl.ldif contains:

dn: cn=jeanne, o=Your Company
changetype: modify
replace: aclEntry
aclEntry: cn=jeanne, o=Your Company:
 normal:rsc:sensitive:rsc:critical:rsc:restricted:rwsc
aclEntry: cn=jeff, cn=tim, o=Your Company:normal:rsc
aclEntry: cn=tim, o=Your Company:
 normal:rsc
-
add: aclPropagate
aclPropagate: TRUE
-

The ACL added in Figure 2 allows cn=jeanne, o=Your Company to update the ACL information for this entry. In addition, because the ACL is a propagating ACL, this allows cn=jeanne, o=Your Company to create new ACL information against any entry that is controlled by this ACL. Care must be taken here, however, because it is possible for cn=jeanne, o=Your Company to set up an ACL which then does not allow cn=jeanne, o=Your Company update capability on the ACL information. If this occurs, a user with sufficient authority (an administrator, for example) must be used in order to reset/change the ACL information.

Figure 3 shows an example of adding a non-propagating ACL. A non-propagating ACL applies only to the entry that it is attached and not to the subtree of information that might be stored below the entry in the directory.

Figure 3. Example of setting up a non-propagating ACL
$ ldapmodify -h 127.0.0.1 -D "cn=admin" -w xxxx -f newAcl.ldif

Where newAcl.ldif contains:

dn: cn=jeff, cn=tim, o=Your Company
changetype: modify
replace: aclEntry
aclEntry: cn=tim, o=Your Company:normal:rwsc:sensitive:rwsc:
 critical:rwsc:restricted:rwsc
aclEntry: cn=jeff, cn=tim, o=Your Company:normal:rwsc:
 sensitive:rwsc:critical:rwsc
aclEntry: cn=jeanne, o=Your Company:normal:rsc
-
replace: aclPropagate
aclPropagate: FALSE
-

Setting up a non-propagating ACL is like setting up a propagating ACL. The difference is that the aclPropagate attribute value is set to FALSE.

Modifying an ACL

Once an ACL exists for an entry in the directory, it might need to be updated. To do this, the ldapmodify utility is used. The examples in this section use the ldapmodify utility, however, any LDAP client application issuing LDAP modify operations to the LDAP server might be used. Therefore, modifications to ACL information do not need to be performed from the same system that the LDAP server is running.

Modifications to ACLs can be of a number of different types. The most common modifications are to:

  • Add an additional aclEntry value to the ACL to allow another person or group access to the entry
  • Change an ACL from propagating to non-propagating (not permitted for the GDBM change log suffix, cn=changelog)
  • Remove an aclEntry value that exists in the ACL to disallow another person or group access to the entry that they had before.

Figure 4, Figure 5, and Figure 6 show examples of these modifications, in that order.

Access determination shows how an additional aclEntry value is added to existing ACL information.

Figure 4. Example of adding an aclEntry attribute value
$ ldapmodify -h 127.0.0.1 -D "cn=admin" -w xxxx -f modAcl.ldif

Where modAcl.ldif contains:

dn: cn=jeff, cn=tim, o=Your Company
changetype: modify
add: aclEntry
aclEntry: cn=dylan, cn=tim, o=Your Company:
 normal:rwsc:sensitive:rwsc:critical:rwsc:restricted:rwsc
-

In Figure 4, cn=dylan, cn=tim, o=Your Company is granted permissions against the cn=jeff, cn=tim, o=Your Company entry in the directory. The existing ACL information remains in the entry; the aclEntry attribute value for cn=dylan, cn=tim, o=Your Company is added to this information.

Figure 5 shows how to modify an existing ACL to be non-propagating instead of propagating.

Figure 5. Example of modifying aclPropagate attribute
$ ldapmodify -h 127.0.0.1 -D "cn=admin" -w xxxx -f modAcl.ldif

Where modAcl.ldif contains:

dn: cn=tim, o=Your Company
changetype: modify
replace: aclPropagate
aclPropagate: FALSE
-

In Figure 5, the existing ACL against cn=tim, o=Your Company is modified to be a non-propagating ACL instead of a propagating ACL. This means that the ACL no longer applies to entries below cn=tim, o=Your Company in the directory tree. Instead, the first propagating ACL that is found in an entry above cn=tim, o=Your Company is applied to the entries below cn=tim, o=Your Company. If no propagating ACL is found in the entries above cn=tim, o=Your Company, then the default ACL is used.

Figure 6 shows how to remove an aclEntry value from existing ACL information:

Figure 6. Example of removing a single aclEntry attribute value
$ ldapmodify -h 127.0.0.1 -D "cn=admin" -w xxxx -f modAcl.ldif

Where modAcl.ldif contains:

dn: cn=jeff, cn=tim, o=Your Company
changetype: modify
delete: aclEntry
aclEntry: cn=dylan, cn=tim, o=Your Company
-

In Figure 6, the aclEntry attribute value for cn=dylan, cn=tim, o=Your Company is removed from the ACL information for entry cn=jeff, cn=tim, o=Your Company. Only the distinguished name part of the aclEntry value must be specified when deleting the value.

Deleting an ACL

In order to delete an ACL that is attached to an entry in the directory, the aclEntry and aclPropagate attributes must be deleted from the entry. To do this, use the ldapmodify command to delete the entire attribute (all values) from the entry.
Note: This is not allowed for the change log suffix entry, cn=changelog, when GDBM is Db2®-based.

Figure 7 shows an example of deleting an ACL from an entry.

Figure 7. Example of deleting an ACL from an entry
$ ldapmodify -h 127.0.0.1 -D "cn=admin" -w xxxx -f delAcl.ldif

Where delAcl.ldif contains:

dn: cn=jeff, cn=tim, o=Your Company
changetype: modify
delete: aclEntry
-
delete: aclPropagate
-

In Figure 7, the existing ACL against cn=jeff, cn=tim, o=Your Company is removed. This means that the ACL no longer applies to the entry. Instead, the first propagating ACL that is found in an entry above cn=jeff, cn=tim, o=Your Company is applied to cn=jeff, cn=tim, o=Your Company. If no propagating ACL is found in the entries above cn=jeff, cn=tim, o=Your Company, then the default ACL is used.

Creating an owner for an entry

In addition to the access control list control of directory entries, each entry can have assigned to it an entry owner or set of entry owners. As an entry owner, full access is allowed to the entry. Entry owners are granted add and delete permission, including read, write, search, and compare for all attribute classes. Entry owners can add and modify ACL information about the entries that they are specified as the owner.

Entry owners are listed in the entryOwner attribute. Like aclEntry information, entryOwner information can be propagating or non-propagating based on the setting of the ownerPropagate attribute. Like the aclSource attribute for aclEntry information, the ownerSource attribute lists the distinguished name of the entry that contains the entryOwner attribute that applies to the entry. The ownerSource attribute is set by the server and cannot be directly set when modifying the ACLs.

In order to create an entry owner, the entryOwner and ownerPropagate attributes must be added to the information stored for an entry. The entryOwner and ownerPropagate attributes are added to an entry by either specifying them as part of the entry information when the entry is added to the directory or by modifying the entry after it exists to contain the entryOwner and ownerPropagate information.

You can create an entry owner without specifying the ownerPropagate attribute. In this case, the ownerPropagate attribute is assumed to have a value of TRUE and is added into the directory entry automatically.

Because the ldapmodify utility is very powerful, all the possible ways of adding the entryOwner and ownerPropagate information cannot be shown here. The examples shown here describe the more common uses of the ldapmodify utility to add entry owner information.

Figure 8 shows how to add a propagating entry owner with two entryOwner values to an existing entry.

Figure 8. Example of adding a propagating set of entry owners to existing entry in the directory
$ ldapmodify -h 127.0.0.1 -D "cn=admin" -w xxxx -f newOwn.ldif

Where newOwn.ldif contains:

dn: cn=tim, o=Your Company
changetype: modify
replace: entryOwner
entryOwner: cn=joe, o=Your Company
entryOwner: cn=carol, o=Your Company
-

The entry owners added in Figure 8 are created as a propagating set of entry owners since the ownerPropagate attribute is not specified and, therefore, assumed to be TRUE. This means that the entry owners apply to all entries below cn=tim, o=Your Company that do not already have an entry owner associated with them.

It is not required that an LDAP administrator update all entry owner information, the examples in this section all use the administrator as the entry owner updating ACLs. Further, the use of -h 127.0.0.1 implies that the ldapmodify utility is performed from the same system that the LDAP server is running and that the LDAP server is listening on TCP/IP port 389. For more information about the -h, -p, -D, and -w command-line options, see ldapmodify and ldapadd utilities in z/OS IBM Tivoli Directory Server Client Programming for z/OS The entry owner attributes can be updated from any LDAP client if the user performing the update has the correct authorization to update the entry owner information.

The entry owner attributes such as the ACL attributes are defined to be in a special access class called restricted. Therefore, in order to allow someone other than an LDAP administrator to update the entry owner attributes, they must either be the entry owner or have the correct authorization to restricted attributes. See Figure 2 for an example of allowing users other than an LDAP administrator the ability to update entry owner information.

Figure 9 shows an example of adding a non-propagating entry owner. A non-propagating entry owner applies only to the entry that it is attached and not to the subtree of information that might be stored below the entry in the directory.

Figure 9. Example of setting up a non-propagating entry owner
$ ldapmodify -h 127.0.0.1 -D "cn=admin" -w xxxx -f newOwn.ldif

Where newOwn.ldif contains:

dn: cn=jeff, cn=tim, o=Your Company
changetype: modify
replace: entryOwner
entryOwner: cn=george, o=Your Company
entryOwner: cn=jane, o=Your Company
-
replace: ownerPropagate
ownerPropagate: FALSE
-

Setting up a non-propagating entry owner is similar to setting up a propagating entry owner. The difference is that the ownerPropagate attribute value is set to FALSE.

Modifying an owner for an entry

Once an entry owner exists for an entry in the directory, it might need to be updated. To do this, the ldapmodify utility is used. The examples in this section use the ldapmodify utility, however, any LDAP client application issuing LDAP modify operations to the LDAP server might be used. Therefore, modifications to entry owner information do not need to be performed from the same system that the LDAP server is running.

Modifications to entry owners can be of a number of different types. The most common modifications are to:

  • Add an additional entryOwner value to the set of entry owners to allow another person or group to control the entry
  • Change an entry owner from propagating to non-propagating (not permitted for the GDBM change log suffix, cn=changelog)
  • Remove an entryOwner value that exists in the entry owner set to disallow another person or group access to control the entry that they had control over before.

Figure 10, Figure 11, and Figure 12 show examples of these modifications, in that order.

Figure 10 shows how an additional entryOwner value is added to existing entry owner information.

Figure 10. Example of adding an entryOwner attribute value
$ ldapmodify -h 127.0.0.1 -D "cn=admin" -w xxxx -f modOwn.ldif

Where modOwn.ldif contains:

dn: cn=jeff, cn=tim, o=Your Company
changetype: modify
add: entryOwner
entryOwner: cn=george, o=Your Company
-

In Figure 10, cn=george, o=Your Company is granted entry owner control of the cn=jeff, cn=tim, o=Your Company entry in the directory. The existing entry owner information remains in the entry; the entryOwner attribute value for cn=george, o=Your Company is added to this information.

Figure 11 shows how to modify an existing entry owner to be non-propagating instead of propagating.

Figure 11. Example of modifying the ownerPropagate attribute
$ ldapmodify -h 127.0.0.1 -D "cn=admin" -w xxxx -f modOwn.ldif

Where modOwn.ldif contains:

dn: cn=tim, o=Your Company
changetype: modify
replace: ownerPropagate
ownerPropagate: FALSE
-

In Figure 11, the existing entry owner set for cn=tim, o=Your Company is modified to be non-propagating instead of propagating. This means that the entry owner no longer applies to entries below cn=tim, o=Your Company in the directory tree. Instead, the first propagating entry owner set that is found in an entry above cn=tim, o=Your Company is applied to the entries below cn=tim, o=Your Company. If no propagating entry owner is found in the entries above cn=tim, o=Your Company, then the default entry owner is used.

Figure 12 shows how to remove an entryOwner value from existing entry owner information:

Figure 12. Example of removing a single entryOwner Attribute value
$ ldapmodify -h 127.0.0.1 -D "cn=admin" -w xxxx -f modOwn.ldif

Where modOwn.ldif contains:

dn: cn=jeff, cn=tim, o=Your Company
changetype: modify
delete: entryOwner
entryOwner: cn=george, cn=tim, o=Your Company
-

In Figure 12, the entryOwner attribute value for cn=george, cn=tim, o=Your Company is removed from the entry owner information for entry cn=jeff, cn=tim, o=Your Company. Only the distinguished name part of the entryOwner value must be specified when deleting the value.

Deleting an owner for an entry

In order to delete an entry owner set that is attached to an entry in the directory, the entryOwner and ownerPropagate attributes must be deleted from the entry. To do this, use the ldapmodify utility to delete the entire attribute (all values) from the entry.
Note: This is not allowed for the change log suffix entry, cn=changelog, when GDBM is Db2-based.

Figure 13 shows an example of deleting an entry owner set from an entry.

Figure 13. Example of deleting an entry owner set from an entry
$ ldapmodify -h 127.0.0.1 -D "cn=admin" -w xxxx -f delOwn.ldif

Where delOwn.ldif contains:

dn: cn=jeff, cn=tim, o=Your Company
changetype: modify
delete: entryOwner
-
delete: ownerPropagate
-

In Figure 13, the existing entry owner set against cn=jeff, cn=tim, o=Your Company is removed. This means that the entry owner information no longer applies to the entry. Instead, the first propagating entry owner set that is found in an entry above cn=jeff, cn=tim, o=Your Company is applied to cn=jeff, cn=tim, o=Your Company. If no propagating entry owner set is found in the entries above cn=jeff, cn=tim, o=Your Company, then the default entry owner is used.

Creating a group for use in ACLs and entry owner settings

Sets of users can be grouped together in the directory by defining them as members of a group in the directory. A directory group, which is used for access control checking, is just another entry in the directory. A static, dynamic, or nested group entry can be used as a group on the aclEntry or entryOwner attributes. See Static, dynamic, and nested groups for more information about creating, modifying, and deleting static, dynamic, and nested group entries.

When defining access controls or entry owner sets, names of group entries can be used in the same place as user entry names. When access control decisions are performed, a user’s group memberships can be used in determining whether a user can perform the action requested.

Groups are added to access control information in just the same way as user entries are added to access control information. Figure 14 shows how to be added to the aclEntry information in an existing access control specification for an entry. Figure 15 shows how a group can be added as an entryOwner to an existing entry owner specification for an entry.

Figure 14. Example of adding a group to access control information
$ ldapmodify -h 127.0.0.1 -D "cn=admin" -w xxxx -f modAcl.ldif

Where modAcl.ldif contains:

dn: cn=jeff, cn=tim, o=Your Company
changetype: modify
add: aclEntry
aclEntry: group:cn=group1, o=Your Company:normal:rwsc:sensitive:rsc 
-
Figure 15. Example of adding a group to entry owner information
$ ldapmodify -h 127.0.0.1 -D "cn=admin" -w xxxx -f modOwn.ldif

Where modOwn.ldif contains:

dn: cn=jeff, cn=tim, o=Your Company
changetype: modify
add: entryOwner
entryOwner: cn=group1, o=Your Company
-