Groups
DS servers support several methods of grouping entries:
"Dynamic Groups" look up their membership based on an LDAP filter.
"Static Groups" list each member.
Static groups are easy to start, but can become large and expensive to maintain.
For static groups, you must have a mechanism to remove members whose entries are deleted, and members whose entries are modified in a way that ends their membership. DS servers use a referential integrity plugin for this.
"Virtual Static Groups" use a dynamic group-style definition, but let applications list group members as if the group were static.
Tip
The examples that follow assume ou=Groups,dc=example,dc=com already exists. The ds-evaluation profile includes this entry by default. If you are using another profile, you can create the groups entry:
$ ldapmodify \
--hostname localhost \
--port 1636 \
--useSsl \
--usePkcs12TrustStore /path/to/opendj/config/keystore \
--trustStorePasswordFile /path/to/opendj/config/keystore.pin \
--bindDN uid=admin \
--bindPassword password << EOF
dn: ou=Groups,dc=example,dc=com
objectClass: organizationalunit
objectClass: top
ou: Groups
EOFDynamic Groups
A dynamic group references members using LDAP URLs. Dynamic group entries take the groupOfURLs object class, with one or more memberURL values specifying LDAP URLs to identify group members.
Dynamic groups are a natural fit for directory servers. If you have a choice, choose dynamic groups over static groups for these reasons:
Dynamic group membership is a property of a member's entry.
There is no need to maintain a separate entry with the list of members.
Determining dynamic group membership is as simple as applying the member URL criteria.
Dynamic groups scale to any size without performance issues.
Dynamic group entries remain small even when the group has a large number of members.
The following dynamic group includes entries matching the filter "(l=San Francisco)" (users whose location is San Francisco):
$ ldapmodify \
--hostname localhost \
--port 1636 \
--useSsl \
--usePkcs12TrustStore /path/to/opendj/config/keystore \
--trustStorePasswordFile /path/to/opendj/config/keystore.pin \
--bindDN uid=kvaughan,ou=People,dc=example,dc=com \
--bindPassword bribery << EOF
dn: cn=My Dynamic Group,ou=Groups,dc=example,dc=com
cn: My Dynamic Group
objectClass: top
objectClass: groupOfURLs
ou: Groups
memberURL: ldap:///ou=People,dc=example,dc=com??sub?l=San Francisco
EOF Group membership changes dynamically as entries change to match the memberURL values:
$ldapsearch \ --hostname localhost \ --port 1636 \ --useSsl \ --usePkcs12TrustStore /path/to/opendj/config/keystore \ --trustStorePasswordFile /path/to/opendj/config/keystore.pin \ --baseDN dc=example,dc=com \ "(&(uid=*jensen)(isMemberOf=cn=My Dynamic Group,ou=Groups,dc=example,dc=com))" \ 1.1dn: uid=bjensen,ou=People,dc=example,dc=com dn: uid=rjensen,ou=People,dc=example,dc=com$ldapmodify \ --hostname localhost \ --port 1636 \ --useSsl \ --usePkcs12TrustStore /path/to/opendj/config/keystore \ --trustStorePasswordFile /path/to/opendj/config/keystore.pin \ --bindDN uid=kvaughan,ou=People,dc=example,dc=com \ --bindPassword bribery << EOF dn: uid=ajensen,ou=People,dc=example,dc=com changetype: modify replace: l l: San Francisco EOF$ldapsearch \ --hostname localhost \ --port 1636 \ --useSsl \ --usePkcs12TrustStore /path/to/opendj/config/keystore \ --trustStorePasswordFile /path/to/opendj/config/keystore.pin \ --baseDN dc=example,dc=com \ "(&(uid=*jensen)(isMemberOf=cn=My Dynamic Group,ou=Groups,dc=example,dc=com))" \ 1.1dn: uid=ajensen,ou=People,dc=example,dc=com dn: uid=bjensen,ou=People,dc=example,dc=com dn: uid=rjensen,ou=People,dc=example,dc=com
Virtual Static Groups
DS servers let you create virtual static groups. Virtual static groups allow applications to see dynamic groups as if they had an enumerated list of members like a static group.
The virtual static group takes the auxiliary object class ds-virtual-static-group. Virtual static groups use the object class groupOfNames, or groupOfUniqueNames. Instead of member or uniqueMember attributes, they have ds-target-group-dn attributes pointing to other groups.
Generating the list of members can be resource-intensive for large groups. By default, you cannot retrieve the list of members. If you have an application that must read the list of members, change the configuration of Virtual Static member or Virtual Static uniqueMember to set allow-retrieving-membership:true:
$ dsconfig \
set-virtual-attribute-prop \
--hostname localhost \
--port 4444 \
--bindDN uid=admin \
--bindPassword password \
--name "Virtual Static member" \
--set allow-retrieving-membership:true \
--usePkcs12TrustStore /path/to/opendj/config/keystore \
--trustStorePasswordFile /path/to/opendj/config/keystore.pin \
--no-promptThe following example creates a virtual static group, and reads the group entry with all members:
$ldapmodify \ --hostname localhost \ --port 1636 \ --useSsl \ --usePkcs12TrustStore /path/to/opendj/config/keystore \ --trustStorePasswordFile /path/to/opendj/config/keystore.pin \ --bindDN uid=kvaughan,ou=People,dc=example,dc=com \ --bindPassword bribery << EOF dn: cn=Virtual Static,ou=Groups,dc=example,dc=com cn: Virtual Static objectclass: top objectclass: groupOfNames objectclass: ds-virtual-static-group ds-target-group-dn: cn=My Dynamic Group,ou=Groups,dc=example,dc=com EOF$ldapsearch \ --hostname localhost \ --port 1636 \ --useSsl \ --usePkcs12TrustStore /path/to/opendj/config/keystore \ --trustStorePasswordFile /path/to/opendj/config/keystore.pin \ --baseDN dc=example,dc=com \ "(cn=Virtual Static)"dn: cn=Virtual Static,ou=Groups,dc=example,dc=com objectClass: top objectClass: groupOfNames objectClass: ds-virtual-static-group cn: Virtual Static ds-target-group-dn: cn=My Dynamic Group,ou=Groups,dc=example,dc=com member: uid=abergin,ou=People,dc=example,dc=com member: uid=ajensen,ou=People,dc=example,dc=com member: uid=aknutson,ou=People,dc=example,dc=com member: uid=awalker,ou=People,dc=example,dc=com member: uid=aworrell,ou=People,dc=example,dc=com member: uid=bjensen,ou=People,dc=example,dc=com member: uid=bplante,ou=People,dc=example,dc=com member: uid=btalbot,ou=People,dc=example,dc=com member: uid=cwallace,ou=People,dc=example,dc=com member: uid=dakers,ou=People,dc=example,dc=com member: uid=dthorud,ou=People,dc=example,dc=com member: uid=ewalker,ou=People,dc=example,dc=com member: uid=gfarmer,ou=People,dc=example,dc=com member: uid=jbourke,ou=People,dc=example,dc=com member: uid=jcampaig,ou=People,dc=example,dc=com member: uid=jmuffly,ou=People,dc=example,dc=com member: uid=jreuter,ou=People,dc=example,dc=com member: uid=jwalker,ou=People,dc=example,dc=com member: uid=kcarter,ou=People,dc=example,dc=com member: uid=kschmith,ou=People,dc=example,dc=com member: uid=mjablons,ou=People,dc=example,dc=com member: uid=mlangdon,ou=People,dc=example,dc=com member: uid=mschneid,ou=People,dc=example,dc=com member: uid=mtalbot,ou=People,dc=example,dc=com member: uid=mtyler,ou=People,dc=example,dc=com member: uid=mwhite,ou=People,dc=example,dc=com member: uid=pshelton,ou=People,dc=example,dc=com member: uid=rjensen,ou=People,dc=example,dc=com member: uid=smason,ou=People,dc=example,dc=com member: uid=tlabonte,ou=People,dc=example,dc=com member: uid=tschmith,ou=People,dc=example,dc=com
Static Groups
A static group entry enumerates the entries in the group. Static group entries grow as their membership increases.
Large static groups are a performance bottleneck. If you have a choice, choose dynamic groups over static groups for these reasons:
Static group membership is defined in a separate, potentially large LDAP entry.
Large static group entries are expensive to maintain, cache, and replicate.
Determining static group membership involves reading the group entry, or using virtual membership attributes.
Static group performance tends to decrease with size.
Reading and updating the group entry becomes more expensive as group size grows.
Important
When working with static groups, also read "Verify Membership" and "Referential Integrity".
If you have a deployment with large static groups that are updated regularly, use an entry cache. For details, see "Cache for Large Groups".
Static group entries are based on one of the following standard object classes:
groupOfNamesThe
groupOfNamesobject class requires at least onememberattribute.Each value is the distinguished name of an entry.
groupOfEntriesThe
groupOfEntriesobject class requires zero or morememberattributes.groupOfUniqueNamesThe
groupOfUniqueNamesobject class has at least oneuniqueMemberattribute.Each value follows Name and Optional UID syntax. Name and Optional UID syntax values are a DN, optionally followed by
#BitString. The BitString, such as'0101111101'B, serves to distinguish the entry from another entry with the same DN, which can occur when the original entry was deleted and a new entry was created with the same DN.
Like other LDAP attributes, each group member attribute value is unique. LDAP does not allow duplicate values for the same attribute on the same entry.
Tip
When creating a group entry, use groupOfNames or groupOfEntries where possible.
To create a static group, add a group entry such as the following to the directory:
$ ldapmodify \
--hostname localhost \
--port 1636 \
--useSsl \
--usePkcs12TrustStore /path/to/opendj/config/keystore \
--trustStorePasswordFile /path/to/opendj/config/keystore.pin \
--bindDN uid=kvaughan,ou=People,dc=example,dc=com \
--bindPassword bribery << EOF
dn: cn=My Static Group,ou=Groups,dc=example,dc=com
cn: My Static Group
objectClass: groupOfNames
objectClass: top
ou: Groups
member: uid=ahunter,ou=People,dc=example,dc=com
member: uid=bjensen,ou=People,dc=example,dc=com
member: uid=tmorris,ou=People,dc=example,dc=com
EOFTo change group membership, modify the values of the membership attribute:
$ldapmodify \ --hostname localhost \ --port 1636 \ --useSsl \ --usePkcs12TrustStore /path/to/opendj/config/keystore \ --trustStorePasswordFile /path/to/opendj/config/keystore.pin \ --bindDN uid=kvaughan,ou=People,dc=example,dc=com \ --bindPassword bribery << EOF dn: cn=My Static Group,ou=Groups,dc=example,dc=com changetype: modify add: member member: uid=scarter,ou=People,dc=example,dc=com EOF$ldapsearch \ --hostname localhost \ --port 1636 \ --useSsl \ --usePkcs12TrustStore /path/to/opendj/config/keystore \ --trustStorePasswordFile /path/to/opendj/config/keystore.pin \ --baseDN dc=example,dc=com \ "(cn=My Static Group)"dn: cn=My Static Group,ou=Groups,dc=example,dc=com objectClass: groupOfNames objectClass: top cn: My Static Group member: uid=ahunter,ou=People,dc=example,dc=com member: uid=bjensen,ou=People,dc=example,dc=com member: uid=tmorris,ou=People,dc=example,dc=com member: uid=scarter,ou=People,dc=example,dc=com ou: Groups
RFC 4519 says a groupOfNames entry must have at least one member. Although DS servers allow you to create a groupOfNames without members, strictly speaking, that behavior is not standard. Alternatively, you can use the groupOfEntries object class as shown in the following example:
$ldapmodify \ --hostname localhost \ --port 1636 \ --useSsl \ --usePkcs12TrustStore /path/to/opendj/config/keystore \ --trustStorePasswordFile /path/to/opendj/config/keystore.pin \ --bindDN uid=kvaughan,ou=People,dc=example,dc=com \ --bindPassword bribery << EOF dn: cn=Initially Empty Static Group,ou=Groups,dc=example,dc=com cn: Initially Empty Static Group objectClass: groupOfEntries objectClass: top ou: Groups EOF$ldapmodify \ --hostname localhost \ --port 1636 \ --useSsl \ --usePkcs12TrustStore /path/to/opendj/config/keystore \ --trustStorePasswordFile /path/to/opendj/config/keystore.pin \ --bindDN uid=kvaughan,ou=People,dc=example,dc=com \ --bindPassword bribery << EOF dn: cn=Initially Empty Static Group,ou=Groups,dc=example,dc=com changetype: modify add: member member: uid=ahunter,ou=People,dc=example,dc=com member: uid=bjensen,ou=People,dc=example,dc=com member: uid=tmorris,ou=People,dc=example,dc=com member: uid=scarter,ou=People,dc=example,dc=com EOF
Nested Groups
DS servers let you nest groups. The following example shows a group of groups of managers and administrators:
$ ldapmodify \
--hostname localhost \
--port 1636 \
--useSsl \
--usePkcs12TrustStore /path/to/opendj/config/keystore \
--trustStorePasswordFile /path/to/opendj/config/keystore.pin \
--bindDN uid=kvaughan,ou=People,dc=example,dc=com \
--bindPassword bribery << EOF
dn: cn=The Big Shots,ou=Groups,dc=example,dc=com
cn: The Big Shots
objectClass: groupOfNames
objectClass: top
ou: Groups
member: cn=Accounting Managers,ou=groups,dc=example,dc=com
member: cn=Directory Administrators,ou=Groups,dc=example,dc=com
member: cn=HR Managers,ou=groups,dc=example,dc=com
member: cn=PD Managers,ou=groups,dc=example,dc=com
member: cn=QA Managers,ou=groups,dc=example,dc=com
EOFAlthough not shown in the example above, DS servers let you nest groups within nested groups.
DS servers let you create dynamic groups of groups. The following example shows a group of other groups. The members of this group are themselves groups, not users:
$ ldapmodify \
--hostname localhost \
--port 1636 \
--useSsl \
--usePkcs12TrustStore /path/to/opendj/config/keystore \
--trustStorePasswordFile /path/to/opendj/config/keystore.pin \
--bindDN uid=kvaughan,ou=People,dc=example,dc=com \
--bindPassword bribery << EOF
dn: cn=Group of Groups,ou=Groups,dc=example,dc=com
cn: Group of Groups
objectClass: top
objectClass: groupOfURLs
ou: Groups
memberURL: ldap:///ou=Groups,dc=example,dc=com??sub?ou=Groups
EOF Use the isMemberOf attribute to determine what groups a member belongs to, as described in "Verify Membership". The following example requests the groups that Kirsten Vaughan belongs to:
$ldapsearch \ --hostname localhost \ --port 1636 \ --useSsl \ --usePkcs12TrustStore /path/to/opendj/config/keystore \ --trustStorePasswordFile /path/to/opendj/config/keystore.pin \ --baseDN dc=example,dc=com \ "(uid=kvaughan)" \ isMemberOfdn: uid=kvaughan,ou=People,dc=example,dc=com isMemberOf: cn=Directory Administrators,ou=Groups,dc=example,dc=com isMemberOf: cn=HR Managers,ou=groups,dc=example,dc=com isMemberOf: cn=The Big Shots,ou=Groups,dc=example,dc=com
Notice that Kirsten is a member of The Big Shots group.
Notice also that Kirsten does not belong to the Group of Groups. The members of that group are groups, not users. The following example requests the groups that the directory administrators group belongs to:
$ldapsearch \ --hostname localhost \ --port 1636 \ --useSsl \ --usePkcs12TrustStore /path/to/opendj/config/keystore \ --trustStorePasswordFile /path/to/opendj/config/keystore.pin \ --baseDN dc=example,dc=com \ "(cn=Directory Administrators)" \ isMemberOfdn: cn=Directory Administrators,ou=Groups,dc=example,dc=com isMemberOf: cn=Group of Groups,ou=Groups,dc=example,dc=com isMemberOf: cn=The Big Shots,ou=Groups,dc=example,dc=com
The following example shows which groups each group belong to. The search is unindexed, and so is performed here with directory administrator credentials:
$ldapsearch \ --hostname localhost \ --port 1636 \ --useSsl \ --usePkcs12TrustStore /path/to/opendj/config/keystore \ --trustStorePasswordFile /path/to/opendj/config/keystore.pin \ --bindDN uid=admin \ --bindPassword password \ --baseDN dc=example,dc=com \ "(ou=Groups)" \ isMemberOfdn: ou=Groups,dc=example,dc=com dn: cn=Accounting Managers,ou=groups,dc=example,dc=com isMemberOf: cn=The Big Shots,ou=Groups,dc=example,dc=com isMemberOf: cn=Group of Groups,ou=Groups,dc=example,dc=com dn: cn=Directory Administrators,ou=Groups,dc=example,dc=com isMemberOf: cn=The Big Shots,ou=Groups,dc=example,dc=com isMemberOf: cn=Group of Groups,ou=Groups,dc=example,dc=com dn: cn=Group of Groups,ou=Groups,dc=example,dc=com dn: cn=HR Managers,ou=groups,dc=example,dc=com isMemberOf: cn=The Big Shots,ou=Groups,dc=example,dc=com isMemberOf: cn=Group of Groups,ou=Groups,dc=example,dc=com dn: cn=Initially Empty Static Group,ou=Groups,dc=example,dc=com isMemberOf: cn=Group of Groups,ou=Groups,dc=example,dc=com dn: cn=My Dynamic Group,ou=Groups,dc=example,dc=com dn: cn=My Static Group,ou=Groups,dc=example,dc=com isMemberOf: cn=Group of Groups,ou=Groups,dc=example,dc=com dn: cn=PD Managers,ou=groups,dc=example,dc=com isMemberOf: cn=The Big Shots,ou=Groups,dc=example,dc=com isMemberOf: cn=Group of Groups,ou=Groups,dc=example,dc=com dn: cn=QA Managers,ou=groups,dc=example,dc=com isMemberOf: cn=The Big Shots,ou=Groups,dc=example,dc=com isMemberOf: cn=Group of Groups,ou=Groups,dc=example,dc=com dn: cn=The Big Shots,ou=Groups,dc=example,dc=com isMemberOf: cn=Group of Groups,ou=Groups,dc=example,dc=com
Notice that the group of groups is not a member of itself.
Verify Membership
For a dynamic group, you can check membership directly on the candidate member's entry using the same search criteria as the dynamic group's member URL.
DS servers also let you verify which groups a user belongs to by requesting the virtual isMemberOf attribute. This is more efficient than reading a large static group to determine whether a candidate belongs to the group:
$ldapsearch \ --hostname localhost \ --port 1636 \ --useSsl \ --usePkcs12TrustStore /path/to/opendj/config/keystore \ --trustStorePasswordFile /path/to/opendj/config/keystore.pin \ --baseDN dc=example,dc=com \ "(uid=bjensen)" \ isMemberOfdn: uid=bjensen,ou=People,dc=example,dc=com isMemberOf: cn=Initially Empty Static Group,ou=Groups,dc=example,dc=com isMemberOf: cn=My Static Group,ou=Groups,dc=example,dc=com isMemberOf: cn=My Dynamic Group,ou=Groups,dc=example,dc=com isMemberOf: cn=Virtual Static,ou=Groups,dc=example,dc=com isMemberOf: cn=Carpoolers,ou=Self Service,ou=Groups,dc=example,dc=com
You must request isMemberOf explicitly.
Referential Integrity
When you delete or rename an entry that belongs to static groups, that entry's DN must be removed or changed in each group it belongs to. You can configure the server to resolve membership changes by enabling referential integrity.
Referential integrity functionality is implemented as a plugin. The referential integrity plugin is disabled by default. To enable the plugin, use the dsconfig command:
$ dsconfig \
set-plugin-prop \
--hostname localhost \
--port 4444 \
--bindDN uid=admin \
--bindPassword password \
--plugin-name "Referential Integrity" \
--set enabled:true \
--usePkcs12TrustStore /path/to/opendj/config/keystore \
--trustStorePasswordFile /path/to/opendj/config/keystore.pin \
--no-promptWith the plugin enabled, referential integrity resolves group membership automatically:
$ldapsearch \ --hostname localhost \ --port 1636 \ --useSsl \ --usePkcs12TrustStore /path/to/opendj/config/keystore \ --trustStorePasswordFile /path/to/opendj/config/keystore.pin \ --baseDN dc=example,dc=com \ "(cn=My Static Group)"dn: cn=My Static Group,ou=Groups,dc=example,dc=com objectClass: groupOfNames objectClass: top cn: My Static Group member: uid=ahunter,ou=People,dc=example,dc=com member: uid=bjensen,ou=People,dc=example,dc=com member: uid=tmorris,ou=People,dc=example,dc=com member: uid=scarter,ou=People,dc=example,dc=com ou: Groups$ldapdelete \ --hostname localhost \ --port 1636 \ --useSsl \ --usePkcs12TrustStore /path/to/opendj/config/keystore \ --trustStorePasswordFile /path/to/opendj/config/keystore.pin \ --bindDN uid=kvaughan,ou=People,dc=example,dc=com \ --bindPassword bribery \ uid=scarter,ou=People,dc=example,dc=com$ldapsearch \ --hostname localhost \ --port 1636 \ --useSsl \ --usePkcs12TrustStore /path/to/opendj/config/keystore \ --trustStorePasswordFile /path/to/opendj/config/keystore.pin \ --baseDN dc=example,dc=com \ "(cn=My Static Group)"dn: cn=My Static Group,ou=Groups,dc=example,dc=com objectClass: groupOfNames objectClass: top cn: My Static Group member: uid=ahunter,ou=People,dc=example,dc=com member: uid=bjensen,ou=People,dc=example,dc=com member: uid=tmorris,ou=People,dc=example,dc=com ou: Groups
By default, the referential integrity plugin is configured to manage member and uniqueMember attributes. These attributes take values that are DNs, and are indexed for equality by default for the default backend. Before you add an additional attribute to manage, make sure that it has DN syntax and that it is indexed for equality. DS servers require indexes because an unindexed search can consume too many of the server's resources. For instructions on indexing attributes, see "Configure Indexes".
Consider these settings when configuring the referential integrity plugin:
check-references:truechecks that members' entries exist when added to a group.check-references-filter-criterialets your members' entries match an LDAP filter.For example,
check-references-filter-criteria:member:(objectclass=person)checks that members are person entries.check-references-scope-criteria:naming-contextchecks that members' entries are in the same naming context (base DN).