Enterprise Directory Groups | Middleware Services

Introduction

An Enterprise Directory group is a set of zero or more members that can be used for multiple purposes, the most common being authorization. Members can be people or groups, and nested groups are allowed provided that a circular reference is not created.

Groups provide an easy way to provide authorization to an application. Simply create a group of authorized users and when a user authenticates to your application check that they also exist in the group. Group membership can be retrieved from ED-LDAP, login.vt.edu (both CAS and Shibboleth profiles), and Middleware web services.

Group Creation

The VT 4Help website has information on how to get started with ED groups.

Quick start:

Fill out the Group Prefix Request Form.
When you have been approved for a group prefix create groups with the Group Manager.
Groups can be created and managed with the Group Manager or Middleware web services.
Groups can be retrieved from ED-LDAP, login.vt.edu, or Middleware web services.

Group Management

Web Application

The group manager web application is available to group administrators and managers at https://groups.it.vt.edu/.

Web Services

Middleware provides a set of web service APIs for those who need to manage their groups programmatically.

Interacting with these web services requires the use of an ED service for client authentication. In addition, you must be specifically authorized to make web service calls. Contact Daniel Fisher if you would like to make use of these web service interfaces.

See the Middleware Web Services page for detailed information on Web service architecture, calling conventions, and client usage guidelines.

Directory Information

The entire virginiaTechGroup schema can be found at https://www.middleware.vt.edu/ed/schema/.

A list of useful attributes follows.

ou=Groups,dc=vt,dc=edu

uugid

The unique identifier of a group is known as the uugid, which stands for universally unique group identifier. This attribute contains the unique name of a group. It must start with an alphanumeric, contain only alphanumerics, dots, underscores, and dashes, and end with an alphanumeric. It must be between 3 and 128 characters long. Nodes are the text in between dots in a uugid and must be between 1 and 16 characters long. This is the attribute you will use to access your group in the directory. A group with a uugid of 'middleware.staff' could be accessed at uugid=middleware.staff,ou=Groups,dc=vt,dc=edu.

member

The members of a group. You can add any person that exists in the Registry to this attribute, as well as other groups. Our implementation does not define what these relationships mean, that is up to whomever is using the group. What does it mean for a group to be a member of another group? That is up to you.

groupMembership

The groups that this group is a member of. This provides a mechanism to traverse up to parent groups if necessary.

administrator

The DN of the people and/or services who are responsible for administrating the group. Any person or service in this list is allowed to change any and all the data associated with this group, including deletion of the group.

manager

The DN of the people and/or services who are responsible for managing the group. Any person or service in this list is allowed to change the person members in the group.

viewer

The service DNs allowed to view the data in ED-LDAP. If an administrator sets this attribute then only those services listed will be able to see the group data.

suppressMembers

A boolean indicating whether the member and groupMembership attributes will be anonymously available in ED-LDAP. The default value for this attribute is true.

suppressDisplay

A boolean indicating whether demographic attributes will be anonymously available in ED-LDAP. The default value for this attribute is true. The current list of demographic attributes includes:

displayName
emailAddress
groupData
labeledURI
contactPerson

The DN of the people responsible for this group. These people will receive e-mail concerning this group, including notices concerning group expiration.

expirationDate

The date this group will be deleted from the Enterprise Directory. When a group is created its expiration date is set to one year from its creation date and may be renewed at any time. Several notifications will be sent to the group contact prior to group deletion.

ou=People,dc=vt,dc=edu

groupMembership

The groups a person is a member of. This attribute is only viewable to an authenticated person, it is not available anonymously. Typically you would inspect this attribute after authenticating the person.

groupMembershipUugid

The uugids of the groups a person is a member of.

Nested Group Membership

Groups can be nested in ED, which means that groups can be members of other groups. The group that contains a group member is known as a parent, while the group member is known as a child.

In ED-LDAP, parent groups contain the person members of their children.

For instance, assume we have group A and group B. A has person 1 and B as members, and B has person 2 as a member. The membership of A in ED-LDAP will contain 1, 2, and B. If we then add a group C with person 3 to B, both the membership of A and B will now contain 3.

In LDIF:

dn: uugid=A,ou=Groups,dc=vt,dc=edu
objectClass: virginiaTechGroup
uugid: A
member: uugid=B,ou=Groups,dc=vt,dc=edu
member: uid=1,ou=People,dc=vt,dc=edu
member: uid=2,ou=People,dc=vt,dc=edu
member: uid=3,ou=People,dc=vt,dc=edu

dn: uugid=B,ou=Groups,dc=vt,dc=edu
objectClass: virginiaTechGroup
uugid: B
member: uugid=C,ou=Groups,dc=vt,dc=edu
member: uid=2,ou=People,dc=vt,dc=edu
member: uid=3,ou=People,dc=vt,dc=edu
groupMembership: uugid=A,ou=Groups,dc=vt,dc=edu

dn: uugid=C,ou=Groups,dc=vt,dc=edu
objectClass: virginiaTechGroup
uugid: C
member: uid=3,ou=People,dc=vt,dc=edu
groupMembership: uugid=B,ou=Groups,dc=vt,dc=edu

Access Control

There are 3 attributes which control who can see what about your group.

The viewer attribute controls which ED Services can view your group in the ED-LDAP directory.
The suppressMembers attribute determines whether your group membership is publicly available in the ou=Groups branch of ED-LDAP.
The suppressDisplay attribute determines whether your group demographic data is publicly available in the ou=Groups branch of ED-LDAP.

By setting these attributes you can control what is exposed to various audiences.

Recommendations

Groups can be locked down tightly using the access controls above, but be warned that these controls may make using groups difficult.

Only use access control if you absolutely need it. In the majority of use cases it is not needed.

Google Groups

ED groups can be replicated to VT’s Google Apps instance by selecting the “Google Group” checkbox under the group administration section of the Group Manager.

The group will be named uugid@groups.vt.edu under VT Google Apps. It can be used in any way Google groups can be used, such as for access to calendars, documents, or as a mailing list.

Note that groups in Google will be checked recursively for membership. If you are a member of a group B that is a member of another group A and you give access to group A, the members of group B will also be given access.

Google group names are limited to 60 characters. ED groups longer than 60 characters (periods included) are ignored.

AD Groups

ED groups can be replicated to Active Directory (w2k.vt.edu) by selecting the “AD Group” checkbox under the group administration section of the Group Manager.

The group will have a DN of CN=uugid,OU=Middleware,OU=vt,DC=w2k,DC=vt,DC=edu in AD.

Note that only members that exist in AD will be added as members of the group on the AD side.

Groups can be nested in AD.

GitLab Groups

ED groups can be replicated to code.vt.edu by selecting the “GitLab Group” checkbox under the group administration section of the Group Manager.

If the group does not exist on the GitLab side, it will be created.

If the group does exist in GitLab, the group must have a shared admin/owner in ED and GitLab. Groups that don’t have an admin/owner mapping will be ignored. Groups that do have this mapping will have their membership updated to conform to the ED group (members in GitLab but not ED will be removed). Permissions are never updated after creation.

The ED to GitLab permissions map looks like:

Administrator => Owner
Manager       => Master
Member        => Developer

Group deletes are ignored to preserve projects and resources on the GitLab side. GitLab Groups should be deleted in GitLab.

Users must already exist in GitLab before they can be added to a GitLab group. If they don’t exist in GitLab, they will be ignored.

Groups that have the same name as a uupid will not be replicated.